Guides

iOS SDK <3.3.0

Suggest Edits

SDK Requirements for Versions Prior to 3.30

Installation

Reference the following examples of successful NeuroID SDK integrations.

📱
iOS SwiftUI 3.1.0 to < 3.3.0
Open Recipe
📱
iOS SwiftUI < 3.1.0
Open Recipe

Add the NeuroID SDK to the Project (via CocoaPods)

Add the NeuroID SDK Pod to your projects Podfile pinned to the version you wish to use.

To always be on the latest version, you can point directly to the NeuroID Github repository and set the tag to latest. To see available versions, please visit Release Versions.

target 'Your App Name' do
   # Point to specific Pods version
   pod 'NeuroID', "X.X.X" 

   # Point to latest version via github
   pod 'NeuroID', :git => 'https://github.com/Neuro-ID/neuroid-ios-sdk.git', :tag => 'latest'
end

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. This method takes the parameterclientKey which is either your Production or Testing key.

// Add this import to each ViewController you will be tracking
import NeuroID

...

// This should be called once, from your app delegate (in iOS Storyboards)
//  or your @main/App struct '.onAppear' block (in SwiftUI)  
NeuroID.configure(clientKey: "your_api_key_goes_here")

// Add this import to each ViewController you will be tracking
import NeuroID

...

// This should be called once, from your app delegate (in iOS Storyboards)
//  or your @main/App struct '.onAppear' block (in SwiftUI)  
NeuroID.configure(clientKey: "your_api_key_goes_here")

// Set the site ID
NeuroID.setSiteId(siteId: "form_neuro101")

// Set the environment as production or not
// false - declares the environment as development or testing
// true  - declares the environment as production
NeuroID.setEnvironmentProduction(false)

🚧

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
}

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): 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.

Note: The commands shown below are only available in SDK v3.1.0 and later.

// e.g. When a Sign Up button is pressed
NeuroID.startSession("myIdentityID") { 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 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
NeuroID.start() { started in
 print("Session is started: \(started)")
                 
// Optional - Call setUserID immediately after start
 NeuroID.setUserID("myIdentityID")
}

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

// e.g. When a Submit button is pressed and the session is complete
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).

iOS SDK Advance Device Library

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

Installing the Library

In your project Podfile on the line following pod "NeuroID", add pod "NeuroID/AdvancedDevice" and re-run pod install.

target 'Your App Name' do
    pod 'NeuroID'
  	pod 'NeuroID/AdvancedDevice'
end

Using the Library

To use the AdvanceDevice SDK in your iOS app you need to make the following adjustment to the setup instructions above.

iOS SDK 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
let startedResult = NeuroID.startSession("yourSessionID", true)
print("NeuroID started \(startedResult.started) with session ID \(startedResult.sessionID)")

iOS SDK prior to 3.1.0

  • Locate your NeuroID.start() command.
  • Replace it with NeuroID.start(true).
    • Passing a true parameter indicates you would like to enable AdvancedDevice tracking
NeuroID.start(true)

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 {
        do {
            try NeuroID.setScreenName(screen: "UserDetails");
        } catch {
            print("NeuroID SDK is not started")
            return false
        }
    }
    // ...
}

// AppLaunch.swift
NeuroID.start()

// The user detail view
// UserDetails.swift
func viewWillAppear(false){
    do {
        try NeuroID.setScreenName(screen: "UserDetails");
    } catch {
        print("NeuroID SDK is not started")
        return false
    }
    super()
}

❗️

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. 

NeuroID.attemptedLogin("myLoginID")

// Identifier Not Required
NeuroID.attemptedLogin()

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"

iOS SDK Next Steps

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

Updated 2 months ago