Guides

React Native SDK 4.1.x

Suggest Edits

Requirements

  • Requires React Native 0.76 to 0.85
  • The React Native SDK utilizes our native iOS and Android SDKs. Please see each of their respective requirements
  • To integrate with NeuroID's services, you must whitelist the following domains:
    • https://scripts.neuro-id.com/ - The subdomain that is hosting the NeuroID JavaScript assets
    • https://advanced.neuro-id.com/ - The legacy subdomain that is hosting the device and network assets
    • https://dn.neuroid.cloud/ - The upgraded subdomain that is hosting the device and network assets
    • https://receiver.neuroid.cloud/ - The subdomain that is receiving behavior events via POSTs

❗️

React-Router is Not Supported

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

🚧

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.

See our Managed Workflow with Expo-Go Instructions for more information.

Installation

Reference the following Recipe for an example of a successful NeuroID SDK integration.

📱
React Native Installation
Open Recipe

Install with npm or yarn

Install the SDK using your favorite package manager. To see available versions, please visit Release Versions.

npm install neuroid-reactnative-sdk --save

yarn add neuroid-reactnative-sdk

Configuration

1. Import the SDK

Add the import for NeuroID to each view you will be tracking:

import NeuroID from 'neuroid-reactnative-sdk';

2. Create a Configuration

Create a dictionary that has the following keys that can be used to configure the NeuroID SDK:

ParameterTypeRequiredDescription
usingReactNavigationBoolNoIndicates if you are using the @react-navigation package
isAdvancedDeviceBoolNoEnables Device and Network Intelligence features
advancedDeviceKeyStringNoAdvanced device key issued on an as-needed basis; omit if one was not issued to you
useAdvancedDeviceProxyBoolNoIndicates whether the Device and Network Intelligence proxy should be used
const configuration = {
  usingReactNavigation: true,
  isAdvancedDevice: true
}

3. Configure the SDK

To configure the SDK call NeuroID.configure(). 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. The configure method takes 2 parameters:

  • clientKey which should receive either your Production, or Testing key
  • RNOptions which is an object with the following keys:

Pass the configuration object to NeuroID.configure(_:)

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

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

Device & Network Intelligence

To enable the Device & Network Intelligence features for the NeuroID SDK, set isAdvancedDevice to true

const configuration = {
  usingReactNavigation: true,
  isAdvancedDevice: true
}

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.

Start Data Collection

You must choose one of the following collection options.

Identify at Start

For 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.
    • Note: Calling startSession a second time will end the previous session and begin a new one.
  • 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.
// e.g. When a Sign Up button is pressed
const sessionStarted = await NeuroID.startSession("identity_id")
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()

Identify after Start

For Identify after Start sessions, the following commands are relevant:

  • start(completionCallback: (Bool) -> Unit)
    • Note: Calling startSession a second time will end the previous session and begin a new one.
  • setUserID(userID:String)
  • stop()
// 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("identity_id")
 

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

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

Registering Page Targets

The React-Native screen rendering implementation for both iOS and Android requires that the NeuroID SDK be called on each page you want to capture user behavior from. To do this, call the registerPageTargets method in the onLayout callback for the highest View containing the elements being monitored. See LN 9-12, 15 below.

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;

🚧

TheregisterPageTargets method must be called in the onLayout callback.

If you call the registerPageTargets method in a different spot there is a chance the UI elements will not have finished rendering, leading to the SDK not registering those targets.

For example, 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.

📘

Combining registerPageTargets and setScreenName withsetupPage can be used to combine

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

This is recommended if you are registering targets and setting a screen name but is not required and you can call the methods separately if you prefer.

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 Common Methods

Signal Collection

The NeuroID Mobile SDK silently captures user interactions in a manner that does not block the main thread. All user interactions captured omit any text entered by the user. The SDK never collects sensitive user data.

Examples of iOS interactions we capture:

  • UIViewController life cycle: viewDidLoad, viewWillAppear, viewWillDisappear
  • UITextField, UITextView notifications: textDidBeginEditingNotification, textDidChangeNotification, textDidEndEditingNotification
  • UIControl touch events: touchDown, touchUpInside, touchUpOutside

Examples of Android interactions we capture:

  • Activities/Fragments life cycle: onStart(), onResume(), onPaused(), onDestroyed, onFragmentAttached(), onFragmentDetached()
  • UI widgets/Containers/Views: EditText, Spinner, Button, CheckBox, RadioButton, RadioGroup, Switch, RecyclerView, WebView
  • Events: TOUCH_MOVE, TOUCH_START, TOUCH_END, FOCUS, WINDOW_BLUR, INPUT

Setting the Screen Name

Every time a new screen is presented to the user, use the setScreenName method to associate all captured data with that screen.

This should be done in the Parent View element's onLayout callback prop.

Note: It is important to do this after starting the NeuroID SDK and before each screen renders.


function MyForm(): JSX.Element {
  const [name, setName] = useState("");
 
  const setupPage = async () => {
    await NeuroID.setScreenName('my_form_screen_name');
  };

  return (
    <View onLayout={setupPage}>
    	<Text>Name:</Text>
    	<TextInput
        placeholder={"Name"}
        accessibilityLabel={"Name"}
        value={name}
        onChangeText={(v:string)=>setName(v)}
        testID={"Name"}
        id={"Name"}
      />
          
          
      <Button title={"Submit Application"} onPress={()=>NeuroID.stop()} />
    </View>
  );
}

Optimizing Your Installation with Field Identifiers

While the NeuroID Mobile SDK installation should already be collecting signals, we recommend one additional step to ensure the best experience when viewing and understanding the data, particularly in the customer portal.

For each input field in your application, we recommend setting a field identifier ( contentDescription attribute (or id field in XML) for Android, accessibilityIdentifier for iOS, or testID/accessibilityLabel attribute for React Native).

The field identifier is used by the SDK in order to name and group interactions.

If you do not set a field identifier the SDK will attempt to do it using fallback placeholders. If no fallback can be found a auto-generated identifier will be assigned.

  • Note: If the element is not a native UI element in iOS or Android the element will be ignored. (for example, a custom Pressable without a testID will not be captured)

See example below.

  <TextInput
    	testID="name"
			accessibilityLabel="name"
    	onChangeText={t => setText(t)}
    	defaultValue={text}
   />

Updated 5 days ago

What’s Next

Contact your NeuroID representative to verify your integration is complete.