Guides

(OLD) iOS SDK

Suggest Edits

SDK Requirements

  • For >= v3.4.0 the minimum iOS version supported is iOS 13.
    • For >= v3.0.2 the minimum iOS version supported is iOS 12.
    • For <= v3.0.1 the minimum iOS version supported is iOS 11.
  • A minimum of 5MB of installation space.
  • The installation process can use either Cocoapods or the Swift Package Manager. See below for details.
    • Cocoapods requires Ruby version 3+.
  • The following URLs should be whitelisted:

Installation

Reference the following examples of successful NeuroID SDK integrations.

📱
iOS Storyboard Installation
Open Recipe
📱
iOS SwiftUI v3.3.0+
Open Recipe

View Prior Version Recipe Guides

Add the NeuroID SDK to the Project

For Cocoapods installations

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

For Swift Package Manager installations

Start up Xcode and add the package using the following menu option (File -> Add Package Dependencies).

You will see the Swift Package Manager screen. Search for https://github.com/Neuro-ID/neuroid-ios-sdk.git using the search field in the upper right hand corner. You should see the neuro-ios-sdk package. In the Dependency rule field, choose "Exact Version" and enter the latest version (version 3.4.2 is the first version to support Swift Package manager, to see all available versions, please visit Release Versions). In the "Add To Project" field, choose your project that you want to add the NeuroID SDK to.

Once these are set, click on the Add Package button. You will now see a screen that will ask you to choose a product to add the NeuroID SDK package to. Select the appropriate target in the "Add to Target" selection drop down.

Click on the Add package button. This will clear the product selection screen and return you to Xcode. You can start integration of the NeuroID SDK.

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 two parameters:

  • clientKey which is either your Production or Testing key.
  • 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+.
// 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", isAdvancedDevice: true)

// 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, completionCallback: (StartSessionResult) -> Void)
    • 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
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()


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

Identify after Start sessions - the following commands are relevant:

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

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.

Note: This command is only available in SDK v3.3.0+.

// Command API
NeuroID.startAppFlow(
  siteID:String, 
  userID:String?, 
  completionCallback: (StartSessionResult) -> Void
)

// Example Usage with Identifier at start
NeuroID.startAppFlow(
  "form_neuro101",
  "myIdentityID"
) { startResult in
 print("Session is started: \(startResult.started) with ID: \(startResult.sessionID)")
}

// Example Usage with Identifier after start
NeuroID.startAppFlow(
  "form_neuro101"
) { startResult in
 
 // startResult.sessionID will be empty
 print("Session is started: \(startResult.started) with ID: \(startResult.sessionID)")
   
 // At a later point (either in this callback or on a different page) call setUserID to set
 // the `identityID`
 NeuroID.setUserID("myIdentityID")
}

// Example for an additional flow after calling startAppFlow and starting a session
NeuroID.startAppFlow(
  "form_neuro102"
) { startResult in
 
 // startResult.sessionID will be the previously set ID (either from the previous startAppFlow
 //  or from the setUserID command)
 print("Session is started: \(startResult.started) with ID: \(startResult.sessionID)")
}

iOS SDK Next Steps

Prior Version Recipe Guides

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

Updated 5 months ago

What’s Next