iOS Mobile SDK

Introduction

Arkose Labs' mobile SDK lets you wrap our solution with iOS native function calls. This guarantees seamless integration of your mobile apps with Arkose's full interactive challenges on detection and enforcement, and does so without the extended wait times for separate mobile solutions.

This page covers the Mobile SDK for iOS. If you are developing in Android, see the Mobile SDK for Android page.

The Arkose Mobile SDK for iOS v1:

  • Wraps Arkose's Advanced Enforcement Challenge in native iOS “web views”.

  • Has 1-to-1 feature availability between web and mobile solutions.

  • Integrates with your apps through native functions.

  • Handles errors through callback events.

  • Complies with Arkose Internal Security guidelines.

  • Complies with Apple App Store guidelines for ease of integration.

  • Is fully compatible with new API releases.

  • Supports minimum version iOS 13.0.

Mobile SDK High Level Design

25042504

Mobile SDK Builds Availability

The Arkose Labs Mobile SDKs are available via the Mobile SDK’s Support page. Please talk with your CSM (Customer Success Manager) about your intended usage and to request access.

Compatibility

The Arkose Labs Mobile SDK for iOS works with iOS 13.0 and up.

All existing detection and challenge features on our web solution are also available on the Mobile SDKs. All new ones are automatically added; you don't need to update your application every time we have a new release of our Web platform.

Security

The Arkose Labs Mobile SDKs are Arkose Labs Security reviewed and comply with Apple App Store guidelines.

Performance

We created the Arkose Labs Mobile SDKs with stability and performance in mind. Their use has no significant impact on the host application’s performance.

Installation

Follow these steps to set up Arkose Labs Mobile SDK for iOS in Xcode in your host application. This applies to both Arkose Detect and Arkose Protect.

Prerequisites

  • A host iOS application. You must be able to build and run this application.

  • For the full end-to-end Arkose setup, you must also complete the standard Arkose Server-Side setup instructions.

Steps

Mobile SDK Setup In Xcode

  1. In Xcode, open your Host application.

  2. From the Project Navigator area, select the folder with your project’s name.

  3. From the project’s xcodeproj details, select Target.

  4. Scroll to Frameworks, Libraries, and Embedded Content and drag and drop ALSDK.XCFramework into this section. (or add it as shown in the video)

  5. In the Project Navigator, find the Frameworks folder and verify ALSDK is inside it.

  6. Click on Build Phases to display that tab. Find the Link Binary with Libraries section and confirm it contains the XCFramework.

  7. In your project’s directory, add the Config.plist file from the Arkose Labs SDK. Confirm Config.plist is now visible in the Project Navigator.

  8. Select Config.plist to open it.

  9. Perform a Clean task.

  10. Perform a Build.

Import and add Arkose code to your application

  1. In your host application’s code, import ArkoseLabsKit and os by adding these lines:
import ArkoseLabsKit
import os
  1. To the content view definition, add the WebEventDelegate and associated callback methods. Use the appropriate code for Arkose Protect and Arkose Detect.
, WebEventDelegate { 
// Add the above line to the ContentView structure conformance definition
// at the end, replacing the last { in it
//
// Add the below methods within the ContentView structure definition  
// (i.e. the below lines go above the closing } for the above line)

   func onReady() {
        //Do something on ready callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onReady EVENT")
    }
    
    func onShow() {
        //Do something on show callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onShow EVENT")
    }
    
    func onShown() {
        //Do something on shown callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onShown EVENT")
    }
    
    func onSuppress() {
        //Do something on suppress callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onSuppress EVENT")
    }
    
    func onHide() {
        //Do something on hide callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onHide EVENT")
    }
    
    func onReset() {
        //Do something on reset callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onReset EVENT")
    }
    
    func onCompleted(response: [String: Any?]) {
        //Do something on completed callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onCompleted EVENT \(response)")
    }
    
    func onError(response: [String: Any?]) {
        //Do something on error callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onError EVENT \(response)")
    }
    
    func onFailed(response: [String: Any?]) {
        //Do something on failed callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onFailed EVENT \(response)")
    }

    func onResize(widthValue: CGFloat, heightValue: CGFloat) {
        // Do something in response to a resizing event. 
        // While you cannot set widthValue and heightValue yourself, 
        // you can make use of their new values from the resizing 
        // as you'd like, such as putting them in a log entry.
        AL_Log.info("onResize EVENT")
    }
, WebEventDelegate { 
// Add the above line to the ContentView structure conformance definition
// at the end, replacing the last { in it
//
// Add the below methods within the ContentView structure definition  
// (i.e. the below lines go above the closing } for the above line)

   func onReady() {
        //Do something on ready callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onReady EVENT")
    }
    
    func onShow() {
        //Do something on show callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onShow EVENT")
    }
        
    func onSuppress() {
        //Do something on suppress callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onSuppress EVENT")
    }
    
    func onHide() {
        //Do something on hide callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onHide EVENT")
    }
        
    func onCompleted(response: [String: Any?]) {
        //Do something on completed callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onCompleted EVENT \(response)")
    }
    
    func onError(response: [String: Any?]) {
        //Do something on error callback received.
        //Here it makes a log entry that it was triggered.
        AL_Log.info("onError EVENT \(response)")
    }
  1. To run the Arkose Labs Platform on a view, call the public method ALWebView().
    1. Pass in setup parameters. (See the Configuration section later on this page).
      1. If running Arkose Protect, set the challenge’s language through the apiLang parameter, which defaults to "en" for English.
      2. Optionally, set the apiKey parameter to the Public Key for your account to override the default key value as set in the Config.plist file.
      3. Set the webEventDelegate parameter to self.
ALWebView(
  apiBlob: "",
  apiLang: "en", //Has no effect unless using Arkose Protect
  apiKey: "",
  webEventDelegate: self)

Build the revised project

  1. Perform a Clean.

  2. Perform a Build.

Run and test the application

  1. Run your modified iOS application.

  2. If running Arkose Global Protect:
    a. On the integrate screen, confirm you now see an Arkose Labs Enforcement Challenge.
    b. Verify the challenge.

  3. On a successful verification, the onCompleted event returns a token as part of the response JSON object.

  4. Send the token to your back-end server for verification.

Configuration

WebEventDelegate and ALWebView

Configuration ObjectTypeDescription
ALWebViewPublic methodMethod used to start the Arkose Labs Platform.

Before this method is called, the model object must be initialized with these three additional configuration parameters detailed in this table.

- webEventDelegate (should be assigned to “receiving component”)

- apiLang

- apiBlob
WebEventDelegatePublic delegate componentLets clients receive callbacks from Arkose Labs Platform
apiLangStringApplies only to Arkose Protect.

Language setting for the Enforcement Challenge.

Default: "en"
apiBlobStringOptional. Mainly used to share any client encrypted data blobs with the Arkose Labs Platform.

Default: ""
apiKeyStringOptional. The API_KEY added in Config.plist can be overridden with this value if needed.

Default: ""
resetSessionPublic methodOptional method to reset the current session for the Arkose Labs Platform. This creates a new session.
Events CallbackTypeDescription EventApplicable Product
onReadyEventReceives the onReady event callback from the API server.

Invoked when the Enforcement or Arkose Detect is ready. The Enforcement or detection cannot be triggered before this event. You may want to disable the UI you are protecting until this event has been triggered.
Arkose Detect
Arkose Protect
onShowEventListener function invoked when the Enforcement is running and Arkose Detect is analyzing the user intent. The function is also invoked when an Enforcement Challenge or detection is re-displayed (e.g. if the user closes the EC or detection view and tries to continue). Note that the close button only appears when in Lightbox mode.Arkose Detect
Arkose Protect
onShownEventFunction only invoked the when the Enforcement Challenge is displayed for the first time.Arkose Protect
onSuppressEventListener function invoked when either an Enforcement Challenge is suppressed (i.e. A session was classified as not requiring a challenge) or detection is running and Arkose Detect is analyzing the user intent.Arkose Detect
Arkose Protect
onHideEventListener function invoked when the EC or detection view is hidden. For example, this happens after an EC or detection is completed or if the user clicks the close button. Note that the close button only appears when in Lightbox mode.Arkose Detect
Arkose Protect
onResetEventFunction invoked after the Enforcement resets. Typically occurs after a challenge has been successfully answered.Arkose Protect
onCompletedEventListener function invoked when a session is classified as not needing a challenge or a detection has been successfully completed.

A Response Object is passed to this function.
Arkose Detect
Arkose Protect
onErrorEventFunction invoked when an error occurs when loading the challenge or detection.

A Response Object is passed to this function.
Arkose Detect
Arkose Protect
onFailedEventFunction invoked when a challenge has failed (the user has failed the challenge multiple times and is not allowed to continue the session).

A Response Object is passed to this function.
Arkose Protect
onResizeEventFunction invoked on a resizing event which provides the new width and height values of the EC due to an SDK call.

A Response Object is passed to this function.
Arkose Protect

Configuration Parameters / config.plist

You can change the following configuration parameters by specifying their values in the config.plist file.

Configuration ParametersTypeDescription
API_URL_BASEStringBase URL of Arkose Labs Platform as supplied by Arkose Labs.
API_KEYStringPublic key for your account.
API_FILEStringName of JavaScript file of Arkose Labs Platform as supplied by Arkose Labs.

Config.plist Example

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>VERIFICATION_URL</key>
    <string></string>
    <key>API_KEY</key>
    <string>11111111-1111-1111-1111-111111111111</string>
    <key>API_URL_BASE</key>
    <string>https://client-api.arkoselabs.com/v2</string>
    <key>API_FILE</key>
    <string>api.js</string>
</dict>
</plist>

Logging and Troubleshooting

We use Apple’s Unified Logging to maintain the Mobile SDK logs. Our subsystem’s name is com.arkoselabs.ios

Our log levels are:

  • debug
  • info
  • error

To set the log level for com.arkoselabs.ios, use the following command, replacing <level> with whichever one of the three defined log level values you want to be the new level.

$ sudo log config --mode "level:<level>" --subsystem com.arkoselabs.sdk

Viewing Logs

To view the logs, use either Console.app or Instruments.app

Console.app

  1. Open Console.app

  2. From the top right search, select subsystem as the search type.

  3. Enter a subsystem value of com.arkoselabs.ios

  4. When the app runs, all log entries at the set log level and higher will be visible on the Console.app.

Instruments.app

  1. Open Instruments.app

  2. From the Profiling Template modal menu, select Logging.

  3. Before running the app, in Instruments.app click the Recording button.

  4. Run the QuickStart app.

  5. Stop recording by clicking the Instruments.app Recording button again.

  6. In the Instruments.app top right corner, in the search bar, enter the subsystem name as com.arkoselabs.ios

  7. All log entries at the set log level and higher are visible in a tabulated format in the Instruments.app UI’s bottom half.

Reading Logs

15741574

A log entry contains:

  • Timestamp: It has several formats, depending on the amount of time:

    • mm:ss.sss.sss until mm is more than 1h (most use cases)
    • h:mm:ss.sss.sss when h is 1 to 9
    • hh:mm:ss.sss.sss when hh is at least 10.
  • Type/Level: One of debug, info, or error

  • Process Name

  • Subsystem: Arkose Mobile SDK entries will always have com.arkoselabs.ios here

  • Category: As defined by Arkose Labs

  • Thread Name

  • Message: A user readable message as specified by the developer