Analytics listener

You can listen to various events on the triggers to generate you own analytics. These events can come from a Bubble or Card component.

Example

import { JoinStoriesView, JoinStories } from '@join-stories/react-native-widgets';

export default function Home() {
  useEffect(() => {
    const analyticsSubscription = JoinStories.addAnalyticsListener((data) => {
      console.log('analytics event', data.event_type);
    });

    return () => {
      analyticsSubscription.remove();
    };
  }, [])
  
  return (
  	<SafeAreaView>
    	<Text>Welcome !</Text>
      <JoinStoriesView alias="<your_join_alias>" />
    </SafeAreaView>)
}

Tracking user ID

In stories analytics, you can track user activity by adding a user ID. You can use the setTrackingUserId() method to enter the user's ID, or set it to empty if the user does not accept consent.

JoinStories.setTrackingUserId("<custom_user_id>") // if you wish to use your personnalize ID
//or 
JoinStories.setTrackingUserId("") // if user does not accept consent

Analytics Events

During its life on a mobile, a widget can trigger various analytics events. There are events related to the widget itself and events related to the stories inside of it. They track how the users interact with the widget and its content.

Analytics v2

A new Analytics stack has been implemented. Old events have been renamed, with more properties. New events have been added. They are split by categories. Each category has its own properties.

Category : Story

Event Name	Trigger Scenario
story-chapter-view	A chapter of the story become active: Opening a player, Change of story (swipe,…), Change of chapter, Coming back to a tab with a story opened ...
story-first-chapter-view	The first chapter of the story becomes active.
story-last-chapter-view	The last chapter of the story becomes active.
story-chapter-exit	The active chapter exits either manually or automatically.
story-view	A story become active: Opening a player, Change of story (swipe,…), Coming back to a tab with a story opened ...
story-exit	The active story exits, either manually or automatically.
story-completed	The last chapter of the story is fully read or ends due to a tap to next.
story-tap-next	User taps to next on a story.
story-tap-previous	User taps to previous on a story.
story-swipe-next	User swipes to the right or clicks on the next story button.
story-swipe-previous	User swipes to the left or clicks on the previous story button.
story-pause	Long press on mobile or on click of the pause button on desktop.
story-unpause	Long press is released on mobile or on click of the play button on desktop.

Category : Interaction

Event Name	JOINTrackingEvent	Trigger Scenario
interaction-view	`eventInteractionView`	An interaction becomes active (displayed/viewed) in an active story.
interaction-completed	`eventInteractionCompleted`	User completes an interaction. It must be triggered only once.
interaction-engage	`eventInteractionEngage`	User executes an action on an interaction (e.g., form -> fill fields, tooltip click, CTA click).
interaction-exit	`eventInteractionExit`	The interaction becomes inactive (from an active state).

Category : Widget

Event Name	Trigger Scenario
widget-initialized	The widget has finished initialization before loading data. In case of changing audiences, it is not re-initialized.
widget-data-loaded	The widget loads data (from internal JSON, API fetch, cache, or fallback).
widget-displayed	The widget is inserted in the page and displayed or ready to be displayed.
widget-thumbnail-ready	All thumbnails of visible elements of the widget are loaded.
widget-view-50	At least 50% of the widget’s height is visible (in the viewport and not obstructed by another element on top of it).
widget-view-75	At least 75% of the widget’s height is visible(in the viewport and not obstructed by another element on top of it).
widget-view-100	100% of the widget’s height is visible (in the viewport and not obstructed by another element on top of it).
widget-click	User clicks on a widget.
widget-player-close	The player is closed (e.g., swipe down, tap next when no story, or programmatically).
widget-scrolled	User scrolls (mobile) or clicks on an arrow (desktop) to see next stories.
widget-close	The widget is closed in certain cases (e.g., sticky widget).

Properties

All events have at least the common properties. Each category has its own properties.

Common properties

Name	Description
event_category	story, widget, interaction, …
event_type	Event name. See above for a list of event names
event_version	Event analytics version. (Should be v2)
event_date_timezone	Timezone of the visitor triggering the event. Number in minutes from UTC
event_date_creation	Timestamp (in s) the event was created client side.
event_owner	JOIN owner
event_user_id	Anonymous user id to monitor sessions
event_device_screen_width
event_device_screen_height
event_device_screen_color
event_device_screen_ratio
event_device_pixel_ratio
event_device_network_type	Wi-Fi, cellular, bluetooth, ethernet, unknown
event_device_network_effective_type	Wi-Fi, 4G, 5G, Ethernet, unknown
event_device_orientation	portrait, landscape
event_device_battery_level	battery level. Between 0 and 1
event_integration_environment	`app`
event_integration_location_name
event_integration_app_id
event_integration_app_name
event_integration_app_version
event_integration_app_language
event_integration_app_language_locale
event_integration_app_sdk_version
event_integration_app_sdk_type

Story properties

Name	JOINEventParams	Description
story_id	`STORY_ID`	Story technical id
story_title	`STORY_TITLE`	Story's title
story_label	`STORY_LABEL`	Story's displayed label (may be different from title)
story_last_published_date	`STORY_LAST_PUBLISHED_DATE`	Last published date of the story
story_has_subtitles	`STORY_HAS_SUBTITLES`	Wether story has subtitles or not
story_has_interactions	`STORY_HAS_INTERACTIONS`	Wether story has interactions or not
story_has_sound	`STORY_HAS_SOUND`	If at least one chapter has sound on a story, then yes
story_chapter_count	`STORY_CHAPTER_COUNT`	Total count of chapters
story_interaction_count	`STORY_INTERACTION_COUNT`	Total count of interactions on the story
story_duration	`STORY_DURATION`	Total duration of a story (in ms)
story_chapter_index	`STORY_CHAPTER_INDEX`	The index of the chapter responsible for sending the event. Indexes start at 0
story_chapter_duration	`STORY_CHAPTER_DURATION`	Total duration of the chapter
story_previous_chapter_index	`STORY_PREVIOUS_CHAPTER_INDEX`	The index of the previous chapter
story_index_in_widget	`STORY_INDEX_IN_WIDGET`	Index of the story in the list of stories. Indexes start at 0.
story_muted	`STORY_MUTED`	Is Story muted by the user
story_displayed_format	`STORY_DISPLAYED_FORMAT`	`mobile`
story_completion	`STORY_COMPLETION`	Ratio of completion between 0 and 1
story_chapter_completion	`STORY_CHAPTER_COMPLETION`	Ratio of completion between 0 and 1
story_viewing_time	`STORY_VIEWING_TIME`	Duration in ms
story_chapter_viewing_time	`STORY_CHAPTER_VIEWING_TIME`	Duration in ms
story_is_active	`STORY_IS_ACTIVE`	Property that should always be true for now, but can be used to dissociate events in the future
story_chapter_is_active	`STORY_CHAPTER_IS_ACTIVE`	Property that should always be true for now, but can be used to dissociate events in the future
story_exit_reason	`STORY_EXIT_REASON`	Enum: swipeDown, swipeNext, swipePrevious, tapNext, tapPrevious, closeButton, ctaClick, autoAdvance
story_chapter_exit_reason	`STORY_CHAPTER_EXIT_REASON`	Enum: swipeDown, swipeNext, swipePrevious, tapNext, tapPrevious, closeButton, ctaClick, autoAdvance
story_pause_duration	`STORY_PAUSE_DURATION`	Duration in ms
story_version	`STORY_VERSION`	Story's technical version.

Interaction properties

Name	Description
interaction_id	Interaction technical Id
interaction_type	Interaction type (CTA, Quiz, Shopping, ...)
interaction_engage_type	`redirect`\| `form-input-focus`\| `form-input-change`\| `form-submit`\| `poll-clicked`\| `quiz-click` \| `open-product-config`\| `continue-shopping`
interaction_engage_value_1	First generic value
interaction_engage_value_2	Second generic value
interaction_engage_url	Only used in case of CTA (replacing value 1-2)
interaction_engage_label	Only used in case of CTA (replacing value 1-2)
interaction_engaging_time	Time between first interactionEngage and interactionEngageComplete or interactionExit
interaction_viewing_time	Time between interactionView and interactionExit
interaction_has_been_blocking	In case the interaction has blocked the auto-advance in the chapter/story, waiting for an engagement
interaction_is_already_completed	`true` if it was already completed when the interaction became active
interaction_is_first_engage	`interaction-engage` event is the first engagement of the page.
interaction_is_story_first_engage	`interaction-engage` event is the first engagement of the story.
interaction_is_completion_engage	The event is the one that has completed the interaction.
interaction_exit_state	`completed` \| `canceled`: engaged at least once \| `ignored`: exited interaction without engage \| `already-completed`

Widget properties

Name	JOINEventParams	Description
widget_id	`WIDGET_ID`	Widget technical id
widget_alias	`WIDGET_ALIAS`	Widget alias
widget_type	`WIDGET_TYPE`	Widget type (list, standalone)
widget_shape	`WIDGET_SHAPE`	(Only applies for type list) Widget shape (bubble, card, square)
widget_layout	`WIDGET_LAYOUT`	Widget layout (list, grid)
widget_integration_type	`WIDGET_INTEGRATION_TYPE`	sdk
widget_story_count	`WIDGET_STORY_COUNT`	Number of stories in the widget, after `widget-data-loaded` (with audience conditions applied)
widget_duration_displayed	`WIDGET_DURATION_DISPLAYED`	Duration (in ms) since widget is displayed, starting at widget_display event
widget_click_count	`WIDGET_CLICK_COUNT`	Number of clicks on the widget since it has been displayed, also to set for all story events
widget_player_close_reason	`WIDGET_PLAYER_CLOSE_REASON`	`close-button` \| `background` \| `auto-advance` \| `swipe-down`\| `tap-next`
widget_close_reason	`WIDGET_CLOSE_REASON`	close reason (`manual` or `auto`)
widget_version	`WIDGET_VERSION`	Widget version
widget_audience_slots_matched	`WIDGET_AUDIENCE_SLOTS_MATCHED`	For every widget event except widget initialized, and also for stories when available
widget_visible_duration_threshold	`WIDGET_VISIBLE_DURATION_THRESHOLD`	Used in the event widgetView100Extended, to know the threshold of visibility
widget_is_scrollable	`WIDGET_IS_SCROLLABLE`	According to integration, if the widget is too large to be displayed fully and is made scrollable
widget_scroll_type	`WIDGET_SCROLL_TYPE`	natural/button – to know in case of widgetScroll event, if the scroll is from button or natural gesture
widget_data_loading_time	`WIDGET_DATA_LOADING_TIME`	Duration of the data loading (from API) if instant if coming from JSON = null
widget_data_loaded_source	`WIDGET_DATA_LOADED_SOURCE`	The source from where the data has been loaded (from API, embedded-data, cache, fallback, ...)
widget_video_cover_count	`WIDGET_VIDEO_COVER_COUNT`	Count of the number of video covers
widget_static_cover_count	`WIDGET_STATIC_COVER_COUNT`	Count of the number of static covers
widget_element_height	`WIDGET_ELEMENT_HEIGHT`	Height of the widget (element not full bloc) configured in the studio (or in app) in px

Migration from V1 to V2 events

If you are using event analysis from a callback, you can perform a simple migration of events from version V1 to version V2 using the following table :

Event V1	Event V2	More
widgetMounted	widget-displayed
storiesFetched	widget-data-loaded
componentVisible50	widget-view-50
componentVisible75	widget-view-75
firstClickOnWidget	widget-click	you can use the `widget_click_count` property to specify the first click.
additionalClickOnWidget	widget-click	you can use the `widget_click_count` property to specify additional clicks.
storyPageVisible	story-chapter-view
storyLastPageVisible	story-last-chapter-view
storyClickOnCallToAction	interaction-engage	you can use the `interaction_type` property equal to “`cta`” to specify the cta interaction

Analytics V1 (Deprecated)

Trigger Analytics

You can listen to various events on the triggers to generate you own analytics. These events can come from a Bubble or Card component.

Example

import { JoinStoriesView, JoinStories } from '@join-stories/react-native-widgets';

export default function Home() {
  useEffect(() => {
    const triggerAnalyticsSubscription = JoinStories.addTriggerAnalyticsListener((data) => {
      console.log(data);
    });

    return () => {
      triggerAnalyticsSubscription.remove();
    };
  }, [])
  
  return (
  	<SafeAreaView>
    	<Text>Welcome !</Text>
      <JoinStoriesView alias="<your_join_alias>" />
    </SafeAreaView>)
}

Event payload

Each event has the following basic payload:

{
  type: string;
  cpWidgetAlias: string;
  date: string;
  cpWidgetVersion: string;
  eventOwner: string;
  eventType: string;
  eventCategory: string;
  storyClicked: string;
}

type field is one of the events below.

List of events

Event name	additional parameters	Description
StoriesFetched		Each time the trigger fetch the list of stories from the API.
WidgetMounted		Each time the trigger is instantiated.
ComponentVisible50		After instantiation, the first time the trigger is visible at least on 50% of its height.
ComponentVisible75		After instantiation, the first time the trigger is visible at least on 75% of its height.
FirstClickOnWidget	`storyClicked`(string) : storyId	After instantiation, the first time the trigger is clicked to open the player.
AdditionalClickOnWidget	`storyClicked` (string) : storyId	Each time the trigger is clicked after the first click (see previous event).

Player Analytics

You can listen to various events on the player to generate you own analytics. These events can come from a player opened via a Bubble or Card component or via a Standalone Player.

Example

import { JoinStoriesView, JoinStories } from '@join-stories/react-native-widgets';

export default function Home() {
  useEffect(() => {
  	const playerAnalyticsSubscription = JoinStories.addPlayerAnalyticsListener((data) => {
      console.log(data);
    });

    return () => {
      playerAnalyticsSubscription.remove();
    };
  }, [])
  
  return (
  	<SafeAreaView>
    	<Text>Welcome !</Text>
      <JoinStoriesView alias="<your_join_alias>" />
    </SafeAreaView>)
}

Event payload

Each event has the following payload:

{
  type: string;
  storyId: string;
  cpIndex: string;
  cpTitle: string;
  cpScreenColor: string;
  eventOwner: string;
  date: string;
  eventCategory: string;
  storyPageCount: string;
  ctaUrl: string;
}

type field is one of the events below.

List of events

Event name	Description
StoryPageVisible	Each time a chapter (equivalent to story page) starts playing.
StoryLastPageVisible	Each time the last chapter (last story page) starts playing.
StoryError	Something went wrong with the player.
StoryClickOnCallToAction	Each time the user clicks on a CTA. The url of CTA added on this event only.