Getting Started with FullStory React Native Capture

Available for the following Plan types:

FullStory Enterprise*

FullStory Advanced*

FullStory Business*

FullStory Free

*with the following add-on:

FullStory for Mobile Apps

Available to the following User roles:

Admin

Architect

Standard

 

 

Before You Begin 

The FullStory React Native Plugin does not support React Native's new Architecture, Metro Server, or Expo Go

Ejected Expo apps are fully supported. If you want to use the Metro Server for local development, we recommend disabling FullStory for these builds. While running a local Metro Server during development, we recommend disabling FullStory (read more on Metro support).

Overview

The FullStory React Native Plugin works in conjunction with and does not replace the FullStory for Mobile Apps Plugin.

Minimum React Native version

0.61.0

Recommended React Native version

0.63.0+


As you're implementing the instructions below, you may find it useful to reference a sample app with FullStory integrated. We have an example of the SDK being implemented into a React Native app here.

Configure FullStory for Mobile Apps

First, make sure your Android and iOS projects are properly configured with FullStory for Mobile Apps.

This step can be skipped in an Expo Managed Workflow.

Adding the FullStory React Native Plugin

Modify your application’s package.json file and add the FullStory React Native Plugin as a dependency:

"dependencies": {
   ...
    "@fullstory/react-native": "1.1.0"
  },

Once this is done, execute yarn install or npm install to bring in the new dependencies.

  • iOS
    • Legacy Projects: If your React Native project does not auto-link dependencies, add the following to ios/Podfile:
pod 'fullstory_react-native', :path => '../node_modules/@fullstory/react-native'

All Projects: In the ios sub-directory, execute pod update or pod install

Configuring the React Native Plugin

The FullStory React Native Plugin includes 2 babel dependencies.

@fullstory/react-native must be configured while @fullstory/babel-plugin-annotate-react is optional.

Modify your application’s babel.config.js file and add the plugins:

module.exports = {
  ...
  plugins: [
...
'@fullstory/react-native', ['@fullstory/babel-plugin-annotate-react', { native: true }],
]
};

Configuring for Expo

FullStory React Native currently does not support Expo Go workflows. For Expo Go users, we suggest transitioning to development builds to get the Expo client experience with the ability customize native code.

Add the config plugin to the plugins array of your app.json  or app.config.json

{
"expo": {
"plugins": [
[
"@fullstory/react-native",
{
"version": "<THE PLUGIN VERSION>",
"org": "<YOUR ORG ID HERE>"
}
]
]
}
}

Note: <THE PLUGIN VERSION>refers to the FullStory for Mobile Apps plugin version. See the Release Notes to find the latest version.

Plugin Properties

Plugins allow for extra customization by passing in an object with properties. If no extra properties are added, defaults will be used. Certain properties are required.

Property Platform Required Description
version Android & iOS FullStory for Mobile Apps plugin version
org Android & iOS Your assigned organization ID
host Android & iOS Optional. Defaults to: fullstory.com The server url your sessions are sent to
enabledVariants Android Optional. Defaults to: release Specifies which variants to apply FullStory instrumentation
logLevel Android Optional. Defaults to: info Captures any log statements at or above the specified level


Troubleshooting

Run expo prebuild to generate native files without running your app.

Verify that the correct native file changes have been applied in your /ios and /android folders by comparing the changes with the iOS and Android documentation.

If incorrect native file changes have been applied, please contact support so that we can further troubleshoot.

Limitations

Metro Server Support

The FullStory React Native Plugin uses babel plugins to perform transformations on JSX to enable privacy state declarations and to capture click events. During development, it is possible for Metro’s caching and hot module reloading to corrupt these transformations and cause unexpected bugs in FullStory sessions.

Therefore, we recommend disabling FullStory while running a local Metro Server during development.

Automatic props provided to React Native components

The included babel plugins, when properly configured, will provide read-only and writable props.

  • Read-only props to help with element identity:
    data-component
    data-element
    data-source-file

  • Writable props:
    fsAttribute
    fsClass
    fsTagName

Limitations: The automatic props are not respected on layout-only components at this time. Additionally for custom components, you can also inherit support as below:

const MyCustomComponent = (props) => {
return (
<View fsClass={this.props.fsClass}>
<Text >Text goes here</Text>
</View>
);
}

Note: In order to use our automatic properties with Typescript, you can create a tsx file with the following contents:

declare global {
namespace JSX {
interface IntrinsicAttributes {
fsAttribute?: {[key: string]: string};
fsClass?: string;
fsTagName?: string;
}
}
}

export {};

Using fsAttribute for Privacy Rules

  • You can utilize the new fsAttribute prop to help create selector-based rules in the FullStory app settings.
<Text fsAttribute={{attr1: 'custom_value1', attr2: 'custom_value2'}}>Text element with custom attributes</Text>
  • The corresponding selector in the FullStory app settings:

Screen Shot 2022-06-17 at 11.53.36 AM.png

Using fsTagName for Privacy Rules

  • You can utilize the new fsTagName prop to help create selector-based rules in the FullStory app settings. 
    <text fsTagName="my_tag_name">Text element with custom tagName</Text>
    The corresponding selector in the FullStory app settings:Screen Shot 2022-06-17 at 11.54.25 AM.png

Using fsClass for Privacy Rules

You can use the new fsClass prop on React Native elements to declare privacy rules.

  • Standard privacy rules
<Text fsClass="fs-exclude">Text element that is excluded</Text>
<Text fsClass="fs-mask">Text element that is masked</Text>
<Text fsClass="fs-unmask">Text element that is unmasked</Text>
  • Consent privacy rules
<Text fsClass="fs-exclude-without-consent">Text element that is excluded unless the user consents</Text>
<Text fsClass="fs-mask-without-consent">Text element that is masked unless the user consents</Text>
<Text fsClass="fs-unmask-with-consent">Text element that is unmasked only if the user consents</Text>

Using testID for Privacy Rules

You can also utilize React Native’s built-in testID prop to help create selector-based rules in the FullStory app settings.

<Text testID="test_id_for_unmasking">Text element that is unmasked via privacy rules settings</Text>
  • The corresponding selector in the FullStory app settings:Screen Shot 2022-06-17 at 11.55.19 AM.png

FullStory API

Supported API methods

  • Support for the FullStory JS API has been added with the following methods:
    anonymize
    consent
    event
    getCurrentSession
    getCurrentSessionURL

    identify
    onReady
    restart
    shutdown
    setUserVars
    FullStory.shutdown

Using the FS API

  • Import the FullStory API via:
import FullStory from '@fullstory/react-native';

In your React Native app, once you import the FullStory plugin, you can call any of the supported API methods.

  • Using FullStory.anonymize
    Anonymize can be invoked via:

FullStory.anonymize();
  • Using FullStory.consent 
    Consent can be granted via:
FullStory.consent(true);
  • Using FullStory.event 
    A custom event can be invoked via:
FullStory.event('Checkout invoked', {
  page_str: 'Checkout Page',
  cart_amount_real: 299,
});

Note: array values are not currently supported. 

  • Using FullStory.getCurrentSession 
    We can retrieve the current session ID:
    FullStory.getCurrentSession().then(function(result) {
      const sessionId = result;
    });

    Note: this will be null if called before a session is active.

  • Using FullStory.getCurrentSessionURL 
    We can retrieve the current session URL:
    FullStory.getCurrentSessionURL().then(function(result) {
      const sessionUrl = result;
    });

    Note: this will be null if called before a session is active.

  • Using FullStory.identify 
    User identify is set via:
    FullStory.identify('462718483', {
     displayName: 'Daniel Falko',
     Email: 'daniel.falko@example.com',
    });

    Note: array values are not currently supported.

  • Using FullStory.onReady
    We can subscribe to a callback to be invoked when we have a session:
    FullStory.onReady().then(function(result) {
     const replayStartUrl = result.replayStartUrl;
      const replayNowUrl = result.replayNowUrl;
      const sessionId = result.sessionId;
    });
  • Using FullStory.restart
    We can invoke a request for a new session:
FullStory.restart();
  • UsingFullStory.setUserVars
    User vars can be set via:
FullStory.setUserVars({
"displayName" : "Daniel Falko",
"email" : "daniel.falko@example.com",
"pricingPlan_str" : "free", // is he a freemium, basic, or pro customer?
"popupHelp_bool" : true, // did he turn off the aggressive in-app help?
"totalSpent_real" : 14.50 // how much has he spent on in-app purchases so far?
});

Note: array values are not currently supported.

  • Using FullStory.shutdown
    We can shutdown the current session:
    FullStory.shutdown();

New in FullStory React Native Plugin 1.0.3

  • Using FullStory.log
    Logging can be used via:
    FullStory.log(FullStory.LogLevel.Log, 'Log at Log'); // on iOS, clamps to Debug
    FullStory.log(FullStory.LogLevel.Debug, 'Log at Debug');
    FullStory.log(FullStory.LogLevel.Info, 'Log at Info');
    FullStory.log(FullStory.LogLevel.Warn, 'Log at Warn');
    FullStory.log(FullStory.LogLevel.Error, 'Log at Error');
    FullStory.log(FullStory.LogLevel.Assert, 'Log at Assert'); // on Android, clamps to Error

    Note: If an invalid level is specified, it will default to Info.

Need to get in touch with us?

The FullStory Team awaits your every question.

Ask the Community Technical Support