Apple SDK Common API Reference

This page documents the Arkose Apple SDK types shared by every integration path: SwiftUI (ArkoseView), UIKit, and the deprecated ArkoseChallengeView. Unless noted otherwise, these APIs are available from v2.1.0 and above; items introduced in v3.0.0 are marked. For SDK versions below v2.1.0, see the Legacy API Reference.

ArkoseManager

ArkoseManager class provides public methods to integrate the application with Arkose Bot Manager.

• public static func initialize(with configuration: ArkoseConfig, withPrewarm: Bool = false)
  Initializes the SDK with the configuration parameters. Pass withPrewarm: true (recommended for ArkoseView; available from v3.0.0) to prepare the challenge immediately. Call on the main thread.
• public static func initialize(with configuration: ArkoseConfig, withPrewarm: Bool = false, onChallengeCallback: @escaping (ArkoseChallengeCallbackEvent) -> Void)
  v3.0.0, iOS 13+ overload that additionally registers a one-shot pre-warm outcome observer (a single .onReady on success, or a single .onError after retries are exhausted), invoked on the main thread. A later initialize(...) replaces it. The callback-less overload above preserves the iOS 12 floor.
• public static func update(with configuration: ArkoseConfig)
  Updates SDK with the configuration parameters.
• public static func deinitialize()
  Releases the pre-warmed resources and returns the SDK to an uninitialized state (v3.0.0). Re-initialize before presenting another challenge.
• UIKit-only methods - showEnforcementChallenge, createEnforcementChallenge, runEnforcement, forceDismissEnforcementChallenge - and patch(with:) are documented in the UIKit API Reference.
• public static var logLevel: LogLevel
  Sets log level for the SDK. All messages logged by ArkoseLabsKit framework will have [ArkoseLabsKit] text for easy identification. Valid LogLevel values are: info,warn,error.

ArkoseConfig.Builder

Arkose Enforcement Challenge configuration parameters can be updated using ArkoseConfig.Builder class. The public methods to specify these parameters are listed below:

• public init(withAPIKey apiKey: String)

  Initialize the Builder instance with the public key of your account

• public func with(apiBaseUrl: String) -> Builder
  Base URL of Arkose Enforcement Challenge platform as supplied by Arkose Labs.

• public func with(blob: String) -> Builder
  Specify any encrypted data blobs to share with Arkose Bot Manager. It is optional.

• public func with(language: String) -> Builder
  Specify any language setting for the Enforcement Challenge, the default value is en. It is optional.

• public func with(userAgent: String) -> Builder
  Specify any userAgent setting for ease of testing forced Enforcement Challenge for a session, the default value is inbuilt WebView’s userAgent. It is optional. Please talk with your CSM (Customer Success Manager) about your intended usage and request backend configuration.

• public func with(clientAPIRetryCount: Int) -> Builder
  Specify the number of retries when network issues are triggered when the client app tries to connect to the apiBaseUrl.

  The retry only works for “onError” events with error codes below. When the configured number of retries is exhausted, the last error code is returned.

  • Challenge load error.
  • API_REQUEST_ERROR
  • API_REQUEST_TIMEOUT

Default: 0. It is optional.

• public func with(styleTheme: String) -> Builder
  Specify style theme name for Enforcement Challenge. It is optional.

• public func with(timeoutInSecondsUntilReady: Int) -> Builder
  Configurable WebView session timeout in seconds. Developers can now set a timeout for all API calls within a session. A timeout exception will be thrown if the WebView is still loading when the timeout is reached. The timeout resets to the default value after onReady is called.
  Default: 0. It is optional.

• public func with(challengeBackgroundConfig: ChallengeBackgroundConfig) -> Builder

  Specify the background configuration for the Challenge Alert Screen, including background color, blur effect, and WebView transparency. It is optional.

  Example:

ArkoseConfig.ChallengeBackgroundConfig(
      isOpaque: false, // true = opaque challenge webview background; false = transparent
      blurEffect: false, // true = add blur to challenge webview background; false = transparent background
      backgroundColor: UIKitColor(uiColor: .red) // Sets challenge background color. Use UIKitColor for Storyboard apps; SwiftUIColor for SwiftUI apps
 )

• public func with(showActivityIndicatorOnReset: Bool) -> Builder

  A boolean to control the enablement of the loading spinner animation during a challenge reset. The default value is true. If this parameter is not set, the loading spinner animation is shown. It is optional.

• public func build() -> ArkoseConfig
  Builds and returns an instance of ArkoseConfig

ArkoseConfig

An instance of ArkoseConfig contains all the configuration parameters, use ArkoseConfig.Builder to class to construct an instance of ArkoseConfig

ArkoseActionConfig

A structure containing localized String for the title of the Cancel button and localized String for the accessibilityHint of the Cancel Button. If set to nil, the Cancel button will not be displayed in the view.
Example structure can be as follows:

ArkoseActionConfig(
  title: "Cancel",
  accessibilityHint: "Double tap to cancel the challenge"
)

LogLevel

LogLevel is an enumeration to control the logs generated by the framework. The valid values are:

• info
  Log messages with severity level of info and above
• warn
  Log messages with severity level of warn and above
• error
  Log messages with severity level of error only

ArkoseChallengeDelegate

ArkoseChallengeDelegate is a protocol to be implemented by the application and passed in showEnforcementChallenge function call to receive notification about different events during Enforcement Challenge View lifecycle.

All notifications are applicable to both Arkose Bot Manager detection and enforcement components unless explicitly specified.

• func onReady()
  onReady callback is invoked when the Enforcement or detection is ready.

• func onShow()
  onShow callback is invoked when the Enforcement is running and our detection component is analysing 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).
  Applicable to enforcement only.

• func onShown()
  onShown callback is invoked when the Enforcement Challenge is displayed for the first time.
  Deprecated since Arkose SDK v2.14.0.
  Applicable to enforcement only.

• func onShown(response: [String: Any?])
  onShown callback is invoked when the Enforcement Challenge is displayed for the first time.
  Applicable to enforcement only.
  A Response Object is passed to this function.

• func onSuppress()
  onSuppress callback is invoked when either an Enforcement Challenge is suppressed (i.e. A session was classified as not requiring a challenge) or detection is running and our detection component is analyzing the user intent.
  Deprecated since Arkose SDK v2.14.0.

• func onSuppress(response: [String: Any?])
  onSuppress callback is invoked when either an Enforcement Challenge is suppressed (i.e. A session was classified as not requiring a challenge) or detection is running and our detection component is analyzing the user intent.
  A Response Object is passed to this function.

• func onHide()
  onHide callback is 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.
  Deprecated since Arkose SDK v2.14.0.

• func onHide(response: [String: Any?])
  onHide callback is 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.
  A Response Object is passed to this function.

• func onReset()
  onReset callback is invoked after the Enforcement Challenge is reset. Typically occurs after a challenge has been successfully answered.
  Applicable to enforcement only.

• func onResize(widthValue: CGFloat, heightValue: CGFloat)
  onResize callback is invoked on a resizing event which provides the new width and height values of the EC due to an SDK call.
  Deprecated since Arkose SDK v2.14.0.

• func onResize(response: [String: Any?])
  onResize callback is 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 which includes the width and height values of the EC.

• func onCompleted(response: [String: Any?])
  onCompleted callback is 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.

• func onError(response: [String: Any?])
  onError callback is invoked when an error occurs when loading the challenge or detection.

• func onWarning(response: [String: Any?])
  onWarning callback is invoked when an issue occurs which needs to be shared with the app as a warning, based on which App can take custom actions, when loading the challenge or detection.

  A Response Object is passed to this function.

• func onFailed(response: [String: Any?])
  onFailed callback is invoked when a challenge has failed (the user has failed the challenge multiple times and is not allowed to continue the session). SDK now supports the recoverable flag in the onFailed callback, giving you better control over UI dismissal based on error types. To provide the best experience for your users, check the recoverable flag in the response object:

  • If recoverable is true: Keep the Enforcement Challenge open-it provides users with an option to retry, ensuring they can resolve the issue without restarting.
  • If recoverable is false or missing: You can execute your dismissal logic immediately, preventing users from getting stuck.

let isRecoverable: Bool = (response["recoverable"] as? Bool) ?? false
if !isRecoverable {
   // Safe to Dismiss
}

• A Response Object is passed to this function.
  Applicable to enforcement only.

• func onPrepareForReset(completion: @escaping () -> Void)

  Invoked when the user clicks the reset button. This is the ideal time to get and update new data, such as a session blob. Use ArkoseManager.update(with:) to apply the new configuration before calling the completion handler.

  Warning: You must call the completion handler. If this is not called, the challenge will not reset.

  Parameters

  • completion: The closure that must be called to continue the reset process.

• func onForceDismissCompleted()
  onForceDismissCompleted callback is invoked by the SDK to notify your application that a programmatic dismissal operation has completed successfully. Please see section Programmatic Dismissal of Enforcement Challenge, to understand more about how to programmatically close the EC.

  • Default Implementation
    The protocol ArkoseChallengeDelegate provides a default empty implementation, so you only need to implement this method if you want to perform specific actions when dismissal completes.

public extension ArkoseChallengeDelegate {
    func onForceDismissCompleted() {}
}