iOS SDK 4.1.x

Requirements

Requires iOS 15 or later
A minimum of 20MB of installation space and 10MB of memory
Installation using either:
- Swift Package Manager
- CocoaPods (requires Ruby v3+)
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

Installation

The NeuroID iOS can be installed using Swift Package Manager (SPM) or CocoaPods. SPM is the recommended installation method. Reference the following Recipes for examples of successful NeuroID SDK integrations.

📱

iOS Storyboard Installation

Open Recipe

📱

iOS SwiftUI v3.3.0+

Open Recipe

Install with Swift Package Manager (SPM)

Start Xcode and select File > Add Package Dependencies
On the Swift Package Manager screen, use the search field in the upper right-hand corner to search for https://github.com/Neuro-ID/neuroid-ios-sdk. You should see the neuro-ios-sdk package in the list.
In the Dependency Rule field, choose "Exact Version" and enter the latest version. To see all available versions, visit Release Versions.
In the Add To Project field, choose the project you want to add the NeuroID SDK to.
Next, click the Add Package button.
In the Package Products pop-up, select the appropriate target in from the Add to Target dropdown and click the Add Package button. This will clear the product selection screen and return you to Xcode.

You are now ready to integrate and configure the NeuroID SDK.

Configuration

Configure the SDK once during application startup before beginning data collection.

1. Import the SDK

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

import NeuroID

2. Create a Configuration

NeuroID provides separate client keys for production and one for testing environments. The setup for both environments is the same, only differentiated by the key.

Parameter	Type	Required	Description
`clientKey`	String	Yes	Required client key issued by NeuroID
`isAdvancedDevice`	Bool	No	Enables Device and Network Intelligence features
`advancedDeviceKey`	String	No	Optional advanced device key issued on an as-needed basis; omit if one was not issued to you
`useAdvancedDeviceProxy`	Bool	No	Indicates whether the Device and Network Intelligence proxy should be used

At a minimum, provide the client key issued by NeuroID:

let configuration = NeuroID.Configuration(
  clientKey: "CLIENT_KEY"
)

3. Configure the SDK

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

NeuroID.configure(configuration)

This should be called once during app startup, from your app delegate (in iOS Storyboards) or your @main/App struct .onAppear block (in SwiftUI).

🚧
Method Swizzling and Overrides
The SDK uses method swizzling to capture view lifecycles. In the event that you override one of the following functions: viewWillAppear, viewWillDisappear, viewDidLoad, or dismiss, you must call super in the override function.
For example:
override func viewDidLoad() {
  super.viewDidLoad()
  
  // Your Code Here
}

Device & Network Intelligence

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

let configuration = NeuroID.Configuration(
  clientKey: "CLIENT_KEY",
  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.

Starting 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) -> Void)
- 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
NeuroID.startSession("identity_id") { startResult in
 print("Session is started: \(startResult.started) with ID: \(startResult.sessionID)")
}

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


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

Identify after Start

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

start(completionCallback: (Bool) -> Void)
- Note: Calling start a second time will end the previous session and begin a new one.
identify(_ userID: String)
stop()

// e.g. When a Sign Up button is pressed
NeuroID.start() { started in
 print("Session is started: \(started)")
                 
// Optional - Call identify immediately after start
 NeuroID.identify("identity_id")
}

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

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

iOS 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

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.

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

// YourAppNameApp.swift
NeuroID.start()

//UserDetails.swift
var body: some View {
  // Your Code
  // ...
  .onAppear {
    NeuroID.setScreenName("UserDetails")
  }
  // ...
}

// AppLaunch.swift
NeuroID.start()

// The user detail view
// UserDetails.swift
func viewWillAppear(false){
  NeuroID.setScreenName("UserDetails")
  super()
}

Excluding Views

In circumstances where you want to completely exclude a view and its subviews from any signal/event capturing, pass your views to the excludeView function, as shown below.

let myView = UIView()

// Any subviews in the view passed in will also not be tracked.
NeuroID.excludeViewByTestID(excludedView: myView.id)

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.

See examples below.

TextField("Email", text: $input)
    .accessibilityIdentifier("emailField")
    .accessibilityLabel("emailField")

let emailTextField = UITextView()
emailTextField.id = "emailField"