Guides

React Native SDK <3.3.0

Suggest Edits

SDK Requirements for Versions Prior to 3.3.0


🚧

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

Installation via npm CLI

To install the SDK via npm CLI, add the command npm i neuroid-reactnative-sdk to your project.

Installation via Package.json

To install the SDK via Package.json, add it as a dependency in 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 should receive either your Production, or Testing key.
  • RNOptions which is an object with the following keys:
    • usingReactNavigation which is a Boolean parameter used 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');

  // 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 following collection options.

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

  • startSession(userID:String): StartSessionResult
    • 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("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()

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

  • start(): Bool
    • 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("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).

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;

🚧

Calling registerPageTargets Correctly

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 Advanced Device Library

NeuroID offers an Advanced Device Library that will collect additional signals.

Installing the Library

Instead of installing the standard NeuroID React-Native SDK, install only the NeuroID React-Native AdvanceDevice SDK by either:

  1. Installing via npm npm i neuroid-reactnative-sdk-advanced-device or
  2. Adding "neuroid-reactnative-sdk-advanced-device":"X.X.X" to your package.json file and then running yarn/npm install.

For iOS

You will need to run pod install in the iOS folder of your project.

For Android

To use the AdvanceDevice SDK you will need to update the app-level build.gradle inside the Android Project of your React-Native App in two spots, the repositories and dependencies sections (see below).

// Use this block ONLY for Gradle versions 7 or higher  
android {  
...  
	repositories {  
  	...  
  	maven { url 'https://maven.fpregistry.io/releases' }  
  	maven { url 'https://jitpack.io' }  
	}  
}

...
dependencies {
    implementation ("com.fingerprint.android:pro:2.5.0") {
        exclude group: 'org.jetbrains.kotlin', module: 'kotlin-stdlib'
    }
}

You will also need to add this line to your ProGuard file if you are obfuscating any variant of the app (debug, release, etc.). 

-keep class com.neuroid.** { *; }

Using the Advanced Device Library

To use the AdvanceDevice SDK in your React Native app you need to make the following adjustments to the setup instructions above.

  • Update all your import NeuroID from 'neuroid-reactnative-sdk' to be import NeuroID from 'neuroid-reactnative-sdk-advanced-device';

If 3.1.0 - 3.3.0:

  • Locate your NeuroID.startSession("yourSessionID") command
  • Replace it with NeuroID.startSession("yourSessionID", true) or NeuroID.startSession(nil, true).
    • Passing a true parameter indicates you would like to enable AdvancedDevice tracking.

If prior to 3.1.0:

  • Locate your NeuroID.getInstance()?.start() command.
  • Replace it with NeuroID.getInstance()?.start(true).
    • Passing a true parameter indicates you would like to enable AdvancedDevice tracking
var startedResult = await NeuroID.startSession("yourSessionID", true);
log(`NeuroID","NeuroID started ${startedResult.started} with session ID ${startedResult.sessionID}`);

await NeuroID.start(true);

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>
  );
}

❗️

Required for setScreenName in versions 3.1.0 and prior

If your SDK version is prior to 3.1.0,setScreenName must be called after calling start.

NeuroID does not start collecting events until AFTER the start method is called. setScreenName is an event that NeuroID requires to be captured for a valid session.

setScreenName will throw an exception when called prior to calling the start method.


Marking Attempted Logins

If NeuroID is configured for a login page then use the attemptedLogin command whenever the login is attempted (through button click or biometric). This should be done regardless of login success. Optionally, you can include the attempted userID. See full API documentation. 

await NeuroID.attemptedLogin("myLoginID")

// Identifier Not Required
await NeuroID.attemptedLogin()

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}
   />

React Native SDK Next Steps

  • Contact your NeuroID representative to verify your integration is complete.

Updated 8 months ago