Sending Events

This section shows you how to send the JOIN Stories events to specific data platforms. You can use the following function of JOINStoriesAnalyticsListener to redirect the JOIN Stories events to your data platform :

val analyticsListener: JOINStoriesAnalyticsListener = object : JOINStoriesAnalyticsListener {
  override fun joinStoriesAnalyticsCallback(event: JOINTrackingEvent, payload: Map<String, Any?>)) {}
}
...
trigger.joinAnalyticsListener = analyticsListener
// OR
JOINStories.startPlayer(context, "<you_join_alias>", analyticsListener)

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.

val userId = AdvertisingIdClient.getAdvertisingIdInfo(this).id
JOINStories.setTrackingUserId(userId) // if you wish to use your personnalize advertising 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

Category : Interaction

Category : Widget

Properties

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

Common properties

Story properties

Interaction properties

Widget properties

🚧

Analytics sender

When integrating, you need to be aware of the widget's lifecycle, as the widget may send events several times during use if it is destroyed and recreated, in the case of a dynamic list (RecyclerView, for example).

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 :

JOIN Stories Events (Deprecated)

In order to get notification about JOIN Stories events, you should override the following functions in JOINStoriesAnalyticsListener. The events are separated between trigger events (onTriggerAnalyticsCallback called) and player events (onPlayerAnalyticsCallback called).

Trigger Events

onTriggerAnalyticsCallback returns the following payload for each event:

data class JOINAnalyticsTrigger(
    val eventOwner: String, // owner of the story (equal teamId)
    val cpWidgetAlias: String, // Alias of the trigger
    val cpWidgetVersion: String, // Version of the SDK
    val date: Long, // Current UNIX Timestamp in ms
    val eventCategory: String = "widget",
    val eventTypeName: String, // The event type name
    var eventType: JOINStoriesTriggerEventType?, // The event type
    val storyClicked: String? // The story id - only for click events
)

Stories Fetched Event

Each time the trigger fetch the list of stories from the API, a Stories fetched event is sent:

event: JOINStoriesTriggerEventType.StoriesFetched

Trigger Mounted Event

Each time the trigger is instantiated, a Trigger Mounted event is sent:

event: JOINStoriesTriggerEventType.WidgetMounted

Trigger Visibility 50% Event

After instantiation, the first time the trigger is visible at least on 50% of its height, a Trigger Visible 50% event is sent:

event: JOINStoriesTriggerEventType.ComponentVisible50

Trigger Visibility 75% Event

After instantiation, the first time the trigger is visible at least on 75% of its height, a Trigger Visible 75% event is sent:

event: JOINStoriesTriggerEventType.ComponentVisible75

First Click on Trigger Event

After instantiation, the first time the trigger is clicked to open the player, a First Click on Trigger event is sent:

event: JOINStoriesTriggerEventType.FirstClickOnWidget

It also contains the following value: storyClicked: STORY_ID

Additional Click on Trigger

Each time the trigger is clicked after the first click (see previous event), an Additional Click on Trigger event is sent:

event: JOINStoriesTriggerEventType.AdditionalClickOnWidget

It also contains the following value: storyClicked: STORY_ID

Player Events

onPlayerAnalyticsCallback returns the following payload for each event:

data class JOINAnalyticsPlayer(
    val storyPageCount: Int, // Number of chapter of the story
    val eventOwner: String, // owner of the story (equal teamId)
    val storyId: String, // ID of the story
    val date: Long, // Current UNIX Timestamp in ms
    val eventCategory: String = "story",
    val cpIndex: Int, // Index of the current chapter: from 0 to N
    val cpTitle: String, // Title of the story
    var eventType: JOINStoriesPlayerEventType?, // The event type
    val eventTypeName: String, // The event type name
		val ctaUrl: String? // Url of CTA
)

Chapter View Event

Each time a chapter (equivalent to story page) starts playing, a Chapter View event is sent:

event: JOINStoriesPlayerEventType.StoryPageVisible

Last Chapter View Event

Each time the last chapter (last story page) starts playing, a Last Chapter View event is sent:

event: JOINStoriesPlayerEventType.StoryLastPageVisible

Click Call To Action Event

Each time the user clicks on a CTA, a Click Call To Action event is sent:

event: JOINStoriesPlayerEventType.StoryClickOnCallToAction

The parameter ctaUrl is set on this event only.