Fullstory Integration with Segment Technical Guide - Mobile

Deprecation Notice

Overview

Segment is a customer data platform that unifies data collection and provides data to every team in your company. Fullstory is already a destination for Segment on the web. 

This article explains several methods that you can use to integrate Fullstory with the Segment Analytics for iOS and Android SDK, and receive event data from Segment.

For more information on Fullstory destination - Web(Javascript), please take a look at our solution and guide.

Note: Segment defaults to using cloud-based connection mode ("cloud-mode") for any destination connected to a mobile source. This means integrating Middleware is required if you'd like to use Device mode (client-side actions). 

Integrations

Sending data to Fullstory using Middleware:

Handle Login/Logout 

• Identify a user and their traits at login:

Similar to FS.identify Segment has an Analytics.identify API that lets you tie a user’s identity to their actions and sessions in order to help you understand their journey.

With this API, you can also capture what Segment calls traits (userVars in Fullstory) about your users, like their email, name, preferences, etc. 

We automatically hook into Segment API: Analytics.identify that sends user ID and traits to Fullstory

• Anonymize the user at logout

If your app supports login/logout, then you need to anonymize logged in users when they log out by calling Analytics.reset to clear Segment cache and anonymize this user. This API behaves differently for Android and iOS, so make sure you set the correct segment tag when initializing FullStoryMiddleware. See implementation details below.

Alternatively, you can manually call FS.anonymize after Analytics.reset, see below section "Client side integration - Manual" for more information

Custom events

Similar to identify, we can automatically hook into Analytics.track and Analytics.screen events and funnel the data to Fullstory session replay.

Note that by default, no track or screen events are captured as custom events. Learn more about our Privacy by Default approach.

When initiating the middleware, allowlist the events that you would like to send to Fullstory. If you wish to enable all events, set allowlistAllTrackEvents to true. See below section "Implementation Guide" for code examples.

We will log to Fullstory that a Segment API is called but omit all data if the event is not allowlisted.

All custom events are searchable in Fullstory. You can find and view sessions that match your search criteria.

Add FS session replay URL to Segment events using Middleware

With Fullstory for Mobile Apps, you can retrieve a link to the session replay and attach it to any Segment event.

• By default we automatically insert the Fullstory session replay URL as part of the Segment track and screen event properties, and all event contexts. 
• Depending on the destinations, some may receive only properties, others may be able to parse information in event context.
• This enables you to receive Fullstory session replay links at your destinations and easily identify and navigate to the session of interest.
• You can disable this behavior by setting enableFSSessionURLInEvent to false

Implementation Guide: 

1. Checkout our demo project for Android and iOS
2. Before you begin, make sure you have both Fullstory and Segment setup in your application: 
   • Add Fullstory to your Android or iOS apps
   • Add Segment Analytics for Android or iOS apps
3. Add the files FullStoryMiddleware for Android or FullStoryMiddleware for iOS to your project. Or use CocoaPods/Gradle to add as dependencies:
   • iOS: 

   pod 'FullStorySegmentMiddleware', :git => 'https://github.com/fullstorydev/fullstory-segment-middleware-ios.git', :tag => '1.1'

   • Android (via jitpack): Root build.gradle:

   allprojects {
       repositories {
           ...
           maven {
               url 'https://jitpack.io' 
           }
       }
   }

   • App level build.gradle:

   implementation 'com.github.fullstorydev:fullstory-segment-middleware-android:1.1'

4. Add the middleware during the initialization of your segment analytics client to enable Fullstory.
   • Create FullStoryMiddleware with appropriate settings 

   Android

   // use the same values as Segment builder requires // if you set a segment tag explicitly, // use the same tag rather than the write key to init FullStoryMiddleware FullStoryMiddleware fsm = new FullStoryMiddleware(getApplicationContext() , "write_key" , ["Order Completed", "Viewed Checkout Step", "Completed Checkout Step"]); // enable to insert FS session URL to Segment event properties and contexts // default to true fsm.enableFSSessionURLInEvents = true; // when calling Segment group, send group traits as userVars // default to false fsm.enableGroupTraitsAsUserVars = true; // when calling Segment screen, sent the screen event as custom events to FS // default to false fsm.enableSendScreenAsEvents = true; // allow all track events as FS custom events // alternatively allow list that you would like to track // default to false fsm.allowlistAllTrackEvents = true; Analytics analytics = new Analytics .Builder(getApplicationContext(), "your_key") .useSourceMiddleware(fsm)

   iOS

   let fullStoryMiddleware: FullStoryMiddleware        = FullStoryMiddleware.init(allowlistEvents:                ["Order Completed",                 "Viewed Checkout Step",                 "Completed Checkout Step"]) // allow all events to be tracked by FS, default to false fsm.allowlistAllTrackEvents = true // allow FS session URL to be added in Segemnt event properties, default to true fsm.enableFSSessionURLInEvents = true // enable to send group traits as userVars, default to false fsm.enableGroupTraitsAsUserVars = true // enable to send FS custom events on screen event, default to false fsm.enableSendScreenAsEvents = true configuration.middlewares = [fsm] SEGAnalytics.setup(with: configuration)

5. Your integration is now ready. 

Take a look inside our middleware

1. Analytics.identify -> FS.identify
   • When a user completes a login or signup action, they become identifiable and you're likely calling the Analytics.identify. And an identify event in Segment is shown below:
   • In the meantime this previously anonymous user will then be identified in Fullstory along with all their previous sessions. Fullstory will associate the user’s uid and optional traits as userVars to the current anonymous user. Identified users will show their display name(default to email) and other userVars in Fullstory.
   • Additional Note: if the same trait key is sent multiple times for the same user, new values will override the old ones. Fullstory only keeps the latest record for each key
   • Shown below the same user in Fullstory:
2. Analytics.reset -> FS.anonymize
   1. Whenever Analytics.reset is called, it will anonymize the user in Fullstory which ends the current session, and creates a new anonymous session under a new anonymous user.
   2. iOS: reset gets pipelined through middleware, whenever Analytics.reset is called, we call FS.anonymize to reset the user back to anonymous.
   3. Android: Inside the middleware, a listener for shared preferences is set with the same context and segment tag as your analytics instance. When Analytics.reset is called, it clears the Segment SDK’s internal stores for the current user, and we will anonymize the user in Fullstory.
   4. If you have not set a Segment tag, use the write key as default when creating the Middleware
3. Analytics.track -> FS.event
   • Analytics.track lets you capture the actions your users perform, which can also have associated properties. A track event in Segment is shown below:
   • Set allowlistAllTrackEvents to true or allowlist events that you wish to be captured by Fullstory. When enabled, all allowlisted events will be passed onto the Fullstory session replay as Fullstory custom events.
   • The same track event is shown as custom events alongside the replay in Fullstory: 
   • Notice the blocked-out areas of the app visible during replay. These are our default privacy controls in action. To learn more about how we’ve designed our privacy controls for mobile apps, check out this article on our engineering blog
4. Analytics.screen -> FS.event
   • To capture screens manually, or add additional screens such as when the user is shown a view, fragment, or dialog in your app, use the Analytics.screen API. A track event in Segment is shown below:
   • Fullstory automatically captures any “Activity Visited” with the activity name. To enable Analytics.screento be translated as “Segment Screen” custom events in Fullstory, set recordScreenViews to true.
   • The same screen event is shown as custom events alongside the replay in Fullstory:
5. Analytics.group -> FS.setUserVars
   1. The Analytics.group API allows you to associate an individual user with a group. It also lets you capture custom traits about the group, like industry or number of employees. A group event in Segment is shown below:
   2. Fullstory will automatically add the groupID as userVars to your identified user. In Fullstory, one user can only be associated with one group. The latest group traits being passed will override any prior ones.
   3. Note that we do not automatically include the group traits (such as industry shown below) into userVars. This is because if you change a user's group, but the new group no longer has certain traits, we will not detect when to clear them in Fullstory. This means that the user would then be tied to old group data. However if you wish to enable this behavior, or you know that all your groups have the same set of traits, set enableGroupTraitsToUserVars to true and the group traits will be captured in userVars.
   4. The user with its group id along with group traits in Fullstory:

Client side integration - Manual

Use Cases

If you do not wish to use middleware to send all event data to Fullstory automatically, you can implement Fullstory APIs manually. This provides granular Control of which events and/or data you want to share with Fullstory. 

Implementation:

When capturing an event manually, you are likely calling something like: Analytics.with(context).xxx or SEGAnalytics.shared()?.xxx to capture your analytics data. Add the corresponding Fullstory APIs after the Segment method to pass on the same data into Fullstory when you need them.

See below for specific functions mapping: 

• Identify and Reset

Identify: When you identify a user with Segment, use FS.identify to  identify the user in Fullstory along with all of their sessions. 

Analytics.with(context).identify("userid");

FS.identify("userid");

Analytics
    .with(context)
    .identify(
        new Traits().putEmail("test@email.com"));

Map<String, Object> vars = new HashMap<>();
vars.put("email", "test@email.com");
FS.setUserVars(vars);

Analytics.with(context).identify("a user's id"
   , new Traits().putName("a user's name")
   , new Options());

Map<String, Object> vars = new HashMap<>();
vars.put("displayName", "a user's name");
FS.identify("a user's id", vars);

Reset: When you reset the Segment user data, use FS.anonymize to anonymize the user in Fullstory which ends the current session and create a new anonymous session.

Analytics.with(context).reset();

FS.anonymize();

•  Track(with properties/ with options)

Call FS.event and pass the same event name and properties into Fullstory custom events.  

Analytics
    .with(context)
    .track("Order Completed");

FS.event("Order Completed");

Analytics
    .with(context)
    .track("Order Completed"
        , new Properties().putSubtotal(subtotal));

Map<String, Object> props = new HashMap<>();
props.put("subtotal_real", subtotal);
FS.event("Order Completed", props);

Analytics
    .with(context)
    .track("Order Completed"
        , new Properties().putSubtotal(subtotal)
        , new Options());

Map<String, Object> props = new HashMap<>();
props.put("subtotal_real", subtotal);
FS.event("Order Completed", props);

• Screen

Call FS.event and send the same screen name and properties into Fullstory custom events the same way as track.

Analytics
    .with(context)
    .screen("Purchase Screen"
        ,new Properties()
            .putValue("sku", "13d31")
            .putCategory("Smartwatches"));

Map<String, Object> props = new HashMap<>();
props.put("sku_str", "13d31");
props.put("category_str", "Smartwatches");
FS.event("Purchase Screen", props);

• Group

Use FS.setUserVars to pass the group information into userVars and associate the groupID and traits with your user in Fullstory. Note that in Fullstory, you can only associate one group to one user. The latest value being passed will override the older ones

Analytics
    .with(context)
    .group("a group id");

Map<String, Object> vars = new HashMap<>();
vars.put("group_id_str", "a group id");
FS.setUserVars(vars);

Analytics
    .with(context)
    .group("a group id"
        , new Traits().putEmployees(20));

Map<String, Object> vars = new HashMap<>();
vars.put("group_id_str", "a group id");
vars.put("employees_int", 20)
FS.setUserVars(vars);

Analytics
    .with(context)
    .group("a group id"
        , new Traits().putEmployees(20)
        , new Options());

Map<String, Object> vars = new HashMap<>();
vars.put("group_id_str", "a group id");
vars.put("employees_int", 20)
FS.setUserVars(vars);