HumanDetect™ SDK Integration

Learn how to integrate with the UnifyID HumanDetect™ iOS SDK.

Setup

Before you begin, you’ll want to make sure the following prerequisites are met and that you’ve installed CocoaPods.

Prerequisites

  • Swift 5.1 or greater
  • iOS 10.0 or greater

CocoaPod Installation

The HumanDetect iOS SDK is installed through CocoaPods, a dependency manager for iOS projects. To install CocoaPods:

$ sudo gem install cocoapods
$ pod init

Please refer to CocoaPods Guides - Getting Started for additional information.

To download the SDK directly, find us on GitHub at github.com/UnifyID/unifyid-ios-sdk and check Releases.

Install the HumanDetect SDK Pod

Once CocoaPods is set up, you’ll want to add the HumanDetect SDK pod to your project:

  1. Add the HumanDetect SDK dependency to your Podfile:
     pod 'UnifyID/HumanDetect'
    
  2. Add a post install hook to ensure all dependent projects are built with library evolution support:
     # Enable library evolution support on all dependent projects.
     post_install do |pi|
         pi.pods_project.targets.each do |t|
             t.build_configurations.each do |config|
                 config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
             end
         end
     end
    
  3. Install the pod:
     $ pod install
    
  4. Open your project using the workspace file.

Integration

1. Initialize the SDK

Don’t have an SDK Key yet? Learn how to create your first project.

Initialize an instance of the SDK in your root object or app delegate:

import UnifyID

let unifyid : UnifyID = { try! UnifyID(
    sdkKey: "https://xxx@config.unify.id"
)}()

Your SDK Key resembles a URL (as shown above) and is found in the Settings section of the UnifyID Developer Dashboard.

2. Start Data Capture

Once the SDK is initialized, you’ll access HumanDetect functionality through its humanDetect instance:

import HumanDetect
let humanDetect = unifyid.humanDetect

HumanDetect does not automatically start gathering data from the device. Instead, starting passive data capture is triggered explicitly by your app:

humanDetect.startPassiveCapture()

A minimum duration of 2 seconds is needed to be able to gather enough data to generate a token. Therefore, it’s recommended to start capturing data in advance of requesting a token.

3. Generate a Token

When your app needs to determine if the user is a human or a bot, make a synchronous call to getPassive(identifier:).

identifier is an optional value you can provide. It’s a String that does not need to be unique, and can be used in a variety of ways:

  • An identifier for the user
  • A nonce to uniquely identify the attempt
  • Any other value to increase token security

When verifying a token via the API, this same identifier will be returned to you.

switch humanDetect.getPassive(identifier: "any-string") {
case .success(let humanDetectToken):
    // Send humanDetectToken.token to your backend and
    // verify it with the Token Verification API
    // to determine human vs. bot
case .failure(let error):
    // Handle or present the error
}

.failure

Token generation can fail for several reasons, and your app should handle them appropriately. Common reasons include:

  1. Insufficient data was captured.
  2. Data was captured, but the device is too still and human possession cannot be verified.

For certain types of errors, it may be best to handle them like situations where token verification results in a bot determination. For others, it may make more sense to bypass bot detection entirely and notify your system.

For a full list of errors, refer to the HumanDetect iOS SDK Reference.

.success

On success, getPassive(identifier:) returns an instance of HumanDetectToken.

Important: A HumanDetectToken being returned does not mean that UnifyID has found the user to be a human. Tokens are also returned for bot behavior, so using the Token Verification API is a necessary next step.

Once you have a HumanDetectToken instance, you’ll want to send its token attribute (a String) to your backend for verification. This could be sent with an existing call to your API or be shared separately. Either way, we strongly encourage you to only verify tokens from your backend server. Handling verification directly from your mobile app is not recommended, as it requires you to publish your private API Key to your app.

Once your backend has the token, you’re ready to verify the token and check the result.

Verify Your Token

Updated: