Guides

(OLD) React Native SDK

Suggest Edits

SDK Requirements

  • Minimum React Native Version 0.64 or greater.
  • For applications that are using React Native Versions less than or equal to 0.72.X, please use the 3.3.0 version of the NeuroID React Native SDK.
  • For applications that are using React Native Versions greater than or equal to 0.73.0, please use the 3.4.0 version or greater of the NeuroID React Native SDK.
  • The React Native SDK utilizes our native iOS and Android SDKs. Please see each of their respective requirements.
  • The following URLs should be whitelisted:

🚧

Advanced device is now a part of the core SDK in 3.4.2+

You do not need to include the advanced device library in 3.4.2+ . See the Advanced Device guide for details.

🚧

Expo-Go Workflows Require Additional Setup

Out of the box, managed work flows with Expo-Go are not supported. In order to add the SDK to a managed workflow, a manual build must be created. Please see our Managed Workflow with Expo-Go Instructions.

🚧

React-Router is Not Supported

The React-Router package is not supported at this time in conjunction with the NeuroID React-Native SDK.

Installation

Reference the following examples of successful NeuroID SDK integrations.

📱
React Native Installation
Open Recipe

Add the NeuroID SDK to the Project

Install with NPM CLI

Install the SDK into your project with NPM using the command npm i neuroid-reactnative-sdk

Add to Package.json

Alternatively you can add the SDK as a dependency to your package.json file and then run npm install or yarn. To see available versions, please visit Release Versions.

{
  ....
  "dependencies":{
		"neuroid-reactnative-sdk": "X.X.X"
	}
}

Initialize the SDK

NeuroID will provide two client keys, one for Production and one for Testing. The setup for both environments is the same, only differentiated by the key.

To initialize the SDK call NeuroID.configure. The Builder method takes 3 parameters:

  • clientKey which is either your Production or Testing key
  • RNOptions which is an object with the following keys available
    • isAdvancedDevice which is a boolean to indicate you are using the Advanced Device SDK in addition to the standard SDK. Please see the Advanced Device page for more information.
      • Note: This parameter is only available in SDK v3.3.0+.
    • usingReactNavigation which is a boolean to indicate you are using the @react-navigation package.
// Add this import to each view you will be tracking
import NeuroID from 'neuroid-reactnative-sdk';

...

const setupNeuroID = async () => {
  // This should be called once on App setup
  await NeuroID.configure('your_development_api_key_goes_here', {
    isAdvancedDevice: true,
  });

  // Set to true to generate a health report
  NeuroID.setVerifyIntegrationHealth(true);
};

// Recommended to call in the App useEffect to load once on start
useEffect(() => {
  setupNeuroID();
}, []);

...

// Add this import to each view you will be tracking
import NeuroID from 'neuroid-reactnative-sdk';

...

const setupNeuroID = async () => {
  // This should be called once on App setup
  await NeuroID.configure('your_development_api_key_goes_here');

  // Set to true to generate a health report
  NeuroID.setVerifyIntegrationHealth(true);
};

// Recommended to call in the App useEffect to load once on start
useEffect(() => {
  setupNeuroID();
}, []);

...

// Add this import to each view you will be tracking
import NeuroID from 'neuroid-reactnative-sdk';

...

const setupNeuroID = async () => {
  // This should be called once on App setup
  await NeuroID.configure('your_development_api_key_goes_here');
  
  // Set the siteID
  await NeuroID.setSiteId('form_neuro101');
    
  // Set the environment as production or not
	// false - declares the environment as development or testing
	// true  - declares the environment as production
   await NeuroID.setEnvironmentProduction(false);

  // Set to true to generate a health report.
  // Note: Only works when the ENV is DEV
  NeuroID.setVerifyIntegrationHealth(true);
};

// Recommended to call in the App useEffect to load once on start
useEffect(() => {
  setupNeuroID();
}, []);

...

Collection & Link People to Data

The NeuroID SDK provides two collection options:

  • Identify at Start - Use this in scenarios where a unique Identity ID is known at the start of collection (or you have chosen to have the NeuroID SDK generate an identifier that you will store).
  • Identify after Start - Use this in scenarios where a unique Identity ID is not known from the start of collection but will be known shortly after.

Identity ID/User ID Requirements

To connect NeuroID Analytics results to a specific individual applicant, the Identity ID must meet all of the following requirements:

  • It must be the same identifier used to persist an applicant's identity in your own system. You may refer to this as an Application ID, an Applicant ID, a User ID, a Customer ID, or something similar. Regardless, you must set an Identity ID that is unique to the applicant and exists in your own system. This value will be used to call the NeuroID API for signals to join with your internal applicant data.
  • It must be a string value.
  • It must contain only alphanumeric characters, dashes, underscores, or periods.
  • It must be a minimum length of 3 characters.
  • It must be a maximum length of 100 characters.
  • It must not contain any PII such as an email address or passport number.

Single Use-Case Data Collection

In scenarios where there is a single use-case within the app (e.g. Sign Up or Login), choose one of the available collection options.

Identify at Start sessions - the following commands are relevant:

  • startSession(userID:String, completionCallback: (StartSessionResult) -> Unit)
    • Note: Do not pass a userID if you would like an identifier automatically generated for you.
    • For < v3.3.0 the command is startSession(userID:String): StartSessionResult
  • pauseCollection() - Use this command to temporarily pause the SDK (to avoid collecting sensitive info).
  • resumeCollection() - Use this command if you want to resume from a temporary pause in collection.
  • stopSession() - Use this command when you want to end the session and collection.

Calling startSession a second time will end the previous session and begin a new one.

Note: These commands are only available in SDK v3.1.0+.

// e.g. When a Sign Up button is pressed
const sessionStarted = await NeuroID.startSession("myIdentityID")
console.log(`Session is started: ${sessionStarted.started} with ID: ${sessionStarted.sessionID}`)

// e.g. When a Continue button is pressed that leads to a PII screen
await NeuroID.pauseCollection()


// e.g. When a Continue button is pressed that leads to a screen that should be collected
await NeuroID.resumeCollection()


// e.g. When a Submit button is pressed and the session is complete
await NeuroID.stopSession()

Identify after Start sessions - the following commands are relevant:

  • start(completionCallback: (Bool) -> Unit)
    • For < v3.3.0 the command is start(): Bool
  • setUserID(userID:String)
  • stop()

Calling start a second time will end the previous session and begin a new one.

// e.g. When a Sign Up button is pressed
const started = await NeuroID.start() 
console.log(`Session is started: ${started}`)
// Optional - Call setUserID immediately after start
await NeuroID.setUserID("myIdentityID")
 

// e.g. On another page or later in the flow when the Identity ID is known
await NeuroID.setUserID("myIdentityID")

// e.g. When a Submit button is pressed and the session is complete
await NeuroID.stop()

❗️

Required for Setting the Identity ID in SDK v3.1.0 and prior

For SDK versions < 3.1.0 setUserID must be called after calling start.

NeuroID does not start collecting events until after the start method is called. The setUserID method emits an event that is required for a valid session.

The setUserID method will throw an exception in the following cases:

  • Calling setUserID prior to calling the start method.
  • Calling setUserID with an invalid userID string (see Identity ID requirements above).

Multi Use-Case Data Collection

In scenarios where there are multiple use-cases within the same app (e.g. Sign Up and Login), rather than calling start or startSession, use the command startAppFlow. This command takes the Site ID of the specific flow and allows the flexibility to Identify at Start or Identify after Start.

// Command API
NeuroID.startAppFlow(
  siteID:String, 
  userID:String?
)

// Example Usage with Identifier at start
const sessionStarted = await NeuroID.startAppFlow(
  "form_neuro101",
  "myIdentityID"
)
console.log(`Session is started: ${sessionStarted.started} with ID: ${sessionStarted.sessionID}`)


// Example Usage with Identifier after start
const sessionStarted = await NeuroID.startAppFlow(
  "form_neuro101"
) 
// it.sessionID will be empty
console.log(`Session is started: ${sessionStarted.started} with ID: ${sessionStarted.sessionID}`)

// At a later point (either in this callback or on a different page) call setUserID to set
// the `identityID`
await  NeuroID.setUserID("myIdentityID")



// Example for an additional flow after calling startAppFlow and starting a session
const sessionStarted = await NeuroID.startAppFlow(
  "form_neuro102"
)

// it.sessionID will be the previously set ID (either from the previous startAppFlow
//  or from the setUserID command)
console.log(`Session is started: ${sessionStarted.started} with ID: ${sessionStarted.sessionID}`)

Register Targets on Page

The React-Native screen rendering implementation for both iOS and Android requires that the NeuroID SDK be called on each page where user behavior is to be captured. This is to be done by calling the registerPageTargets method in the onLayout callback for the highest View containing the elements being monitored. I.e. LN 9-12, 15

import React, {useState} from 'react';
import {Button, Text, TextInput, View} from 'react-native';

import NeuroID from 'neuroid-reactnative-sdk';

export const MyForm = ({submitFn}: {submitFn: any}) => {
  const [text, setText] = useState('');

  const registerpage = async () => {
    await NeuroID.setScreenName('MyForm');
    await NeuroID.registerPageTargets();
  };

  return (
    <View onLayout={registerpage}>
      <Text>Form</Text>

      <View>
        <Text>Name</Text>
        <TextInput
          testID="name"
          onChangeText={t => setText(t)}
          defaultValue={text}
        />
      </View>
      <Button title="Submit" onPress={submitFn} />
    </View>
  );
};

export default MyForm;

🚧

registerPageTargets Must be called in the onLayout callback to work

If you call the registerPageTargets method in a different spot there is a chance the UI elements will not have finished rendering and then the SDK will not register those targets. I.e. Calling registerPageTargets in a useEffect callback on page load will cause fields to be missed because the UI has not completely loaded when the useEffect is called.

📘

setupPage can be used to combine registerPageTargets and setScreenName

Using the setupPage method allows you to pass the screenName as a parameter and it will register the page targets as well as set the screenName for you.

This is a preferred method if you are registering targets and setting a screen name but is not required if calling the methods separately is preferred.

await NeuroID.setupPage('MyForm');

// the above is the same as calling the following back to back
await NeuroID.setScreenName('MyForm');
await NeuroID.registerPageTargets();

React Native SDK Next Steps

Prior Version Recipe Guides

Coming Soon!

All methods are common across the ReactNative, Kotlin, and iOS SDKs. Please refer to the SDK Common Methods for documentation on all available methods.

Updated 5 months ago

What’s Next