Android SDK Common API Reference
This page documents the configuration objects, builder parameters, and callback listeners shared by both Android integration paths: Jetpack Compose and XML/View-based.
ArkoseConfig Configuration
ArkoseConfig ConfigurationNote that Arkose’s detection component is part of our overall Arkose Bot Manager platform. Thus the names of some methods and variables refer only to enforcement when actually dealing with detection as well. Unless otherwise specified, the configuration components apply to both detection and enforcement components, although perhaps in different ways as specified.
| Configuration Object | Type | Description | Applicable Component |
|---|---|---|---|
ArkoseConfig (or) ArkoseConfigCompose | Public component | Enables a consistent public parameter data model for the View in which it is called. An initialized model object later passed as parameters to the showEnforcementChallenge() Arkose Labs Mobile SDK. Note that detection is part of our overall Arkose Bot Manager platform. Thus the names of some methods and variables refer only to enforcement when actually dealing with detection as well. | Detection Enforcement |
showEnforcementChallenge | Public Method | Method that starts the Arkose Labs detection when using our detection component and enforcement when using Arkose’s enforcement component. Before calling this method, the model object (ArkoseConfig) must be initialized with the additional configuration parameters. This method adds two listeners: addOnCompletedListener: Invoked on completion of verification. Overrides the onCompleted method with a response. addOnFailureListener: Invoked when Enforcement Challenge verification fails. Overrides the onFailed method with a response. | Detection Enforcement |
createEnforcementChallenge | Public Method | Method that creates the Arkose Labs object without invoking the display function. Before calling this method, the model object (ArkoseConfig) must be initialized with the additional configuration parameters given in the next table. These values are set in the strings.xml file. This method is used in conjunction with getEnforcementChallengeFragment method to allow embedding into the parent app activity as a fragment. | Detection Enforcement |
OnLoadedListener | Function | Listener function invoked when the SDK has been loaded. | Detection Enforcement |
OnReadyListener | Function | Listener function invoked when the Enforcement or Detection 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. | Detection Enforcement |
OnShowListener | Function | Listener function invoked when the Enforcement or Detection is completed. 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. | Detection Enforcement |
OnShownListener | Function | Listener function invoked when the Enforcement Challenge or Detection is displayed. The function is only invoked the first time an Enforcement Challenge is displayed. | Enforcement |
OnCompletedListener | Function | Listener function invoked when either: a. For our enforcement component, a session is classified as not needing a challenge or a challenge has been successfully completed. b. For our detection component, a session detection has been successfully completed. A Response Object is passed to this function. | Detection Enforcement |
OnHideListener | Function | Listener 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. | Detection Enforcement |
OnSuppressListener | Function | Listener function invoked when: a. The Enforcement Challenge is suppressed (i.e. A session was classified as not requiring a challenge). b. The Detection is running and is analyzing the user intent. | Detection Enforcement |
OnResetListener | Function | Listener function invoked after the Enforcement resets. Typically occurs after a challenge has been successfully answered. | Enforcement |
OnErrorListener | Function | Listener function invoked when an error occurs when loading the challenge or detection. A Response Object is passed to this function. | Detection Enforcement |
OnWarningListener | Function | Listener function 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. | Detection Enforcement |
OnFailedListener | Function | Listener function 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. ArkoseManager.createEnforcementChallenge() 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 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. | Enforcement |
OnResizeListener | Function | Listener function invoked when a challenge is loaded. It provides the width and height of the visible EC from an SDK call. A Response Object is passed to this function. | Enforcement |
OnViewFramePositionListener | Function | Listener function invoked when a challenge is loaded. It allows the parent APP to set the view frame window attributes as desired by calling the getWindow() function on the ArkoseECResponse parameter. E.g. arkoseECResponse.getWindow().getAttributes().gravity = Gravity.BOTTOM; A Response Object is passed to this function. | Enforcement |
Enforcement Challenge Configuration Parameters
You can change the following Enforcement Challenge configuration parameters by specifying their values in the ArkoseConfig object.
| EC Configuration Methods | Description |
|---|---|
Builder apiBaseUrl(String apiBaseUrl) | Base URL of Arkose Labs EC platform as supplied by Arkose Labs. |
Builder apiKey(String apiKey) | Public key for your account. |
Builder apiFile(String apiFile) | JavaScript file name of Arkose Labs EC as supplied by Arkose Labs. |
Builder blobData(String blobData) | Mainly used to share any client encrypted data blobs with Arkose Bot Manager. It is optional. Default: "" |
Builder language(String language) | Not applicable to our detection component. Language setting for the EC. It is optional. Default: "en" |
Builder userAgent(String userAgent) | Specify any userAgent setting for ease of testing forced Enforcement Challenge for a session. It is optional. Please talk with your CSM (Customer Success Manager) about your intended usage and request backend configuration. Default: (inbuilt webview’s userAgent string) |
Builder loading(Boolean val) | Specify whether loading spinner is shown or not. Default: true |
Builder enableBackButton(Boolean val) | Specify whether device back button dismisses EC dialog or not. If this configuration is enabled, and the user uses the back button, onHide listener is triggered and EC dialog is dismissed. Default: true |
Builder setDismissChallengeOnTouchOutside(Boolean val) | Specify whether touching outside of EC dialog will dismiss the EC dialog or not. If this configuration is enabled, and user touches outside of the EC dialog, onHide listener is triggered and EC dialog is dismissed. Default: true |
Builder setClientAPIRetryCount(int count) | 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 It is optional. Default: 0 |
Builder setStyleTheme(String styleTheme) | Style theme setting for the EC. It is optional. Default: "" |
Builder setTimeoutUntilReady(int timeoutInSeconds) | SDK timeout in seconds (optional, positive integer). Introduced configurable WebView session timeouts. Developers can now set a timeout for all API calls within a session called before onReady. If the WebView is still loading when the timeout is reached, a timeout exception will be thrown. Once the WebView successfully loads and the onReady callback is triggered, the timeout automatically resets to its default value. Default: 0 |
Builder setAccessibilityTextScaleCap(int accessibilityTextScaleCap) | Accessibility Text Scale Cap (optional, positive integer); 0 means unset (maintains default Android accessibility behaviour). A new configuration option to help you manage text scaling behaviour in the challenge interface, that allows you to control how Android's system accessibility font size settings affect the challenge display. The same cap also bounds the Cancel / Reset button labels. How it works: Set a value (e.g., 150) to cap text scaling at a specific percentage Leave unset to maintain Android's default accessibility behaviour Adjust the value to balance your design requirements with user accessibility needs Use case: If you're experiencing issues where Android's maximum font size settings are causing display problems in the challenge interface (such as text scaling to 200%), you can use this parameter to maintain consistent rendering while still supporting accessibility where appropriate. Default: 0 |
(XML) Builder setInlineRunOnTrigger(Boolean val) (Compose) inlineRunOnTrigger | Enables preloading of the enforcement challenge to onReady state, giving the application full control over when the challenge is presented to the user. When set to true, the SDK initializes and warms up the WebView in the background without displaying the challenge. The challenge is then presented on demand by calling ArkoseManager.runTriggeredInline(arkoseChallenge) (XML) or ArkoseManagerCompose.runTriggeredInline() (Compose) after the onReady callback fires. Do NOT use with showEnforcementChallenge() or enable loading = true alongside this flag. Available from v2.18.0 (XML) and v2.20.0 (Compose inline mode). Default: false |
(XML) Builder showLoaderOnReset(Boolean val) (Compose) showLoaderOnReset | Controls whether a loading spinner is shown over the challenge while it reloads during a Reset triggered from the In-SDK Cancel / Reset buttons. When set to false, the spinner is suppressed, but the challenge is still briefly covered to block interaction during the reload. See Reset loader (showLoaderOnReset) for details. Available from v2.22.0. Default: true |
Updated 2 days ago