Android Mobile SDK
Introduction
Arkose Labs' mobile SDKs let you wrap our solution with Android 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 Android. If you are developing in iOS, see the Mobile SDK for iOS page.
The Arkose Mobile SDK v1:
-
Wraps Arkose's Advanced Enforcement Challenge in native Android OS “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 Google Play Store guidelines for ease of integration.
-
Is fully compatible with new Enforcement Challenge-API (EC-API) releases.
-
Supports minimum version Android OS 6.0.
Mobile SDK High Level Design


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 Android works with Android 6.0 and up.
All existing detection and challenge features on our web solutions are also available on the Mobile SDKs. All new ones are automatically added; you don't need to update your application every time we release a new Web platform. All challenge updates can be done without updating the SDKs or releasing a new version of your application.
Security
The Arkose Labs Mobile SDKs are Arkose Labs Security reviewed and comply with Google Play 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 the steps below to set up Arkose Labs Mobile SDK for Android in Android Studio in your host application. This applies to both Arkose Detect and Arkose Protect.
Prerequisites
-
A host Android 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
Set up development file
-
Under
src/main
, create alibs
folder. -
Copy your
.aar
file tosrc/main/libs
-
In the app level
build.gradle
file, add this line to itsdependencies
block.
implementation fileTree(dir: "libs", include: ["*.aar"])
- In the toolbar, click on File. Then in its menu click Sync Project with Gradle Files.
Import and add Arkose code to your application
- Import the necessary SDK classes. Add the below code in your main file, right after you import your
android
andandroidx
classes and before your class definition statements.
import com.arkoselabs.sdk.ArkoseConfig;
import com.arkoselabs.sdk.ArkoseLabs;
import com.arkoselabs.sdk.Listener.OnCompleteListener;
import com.arkoselabs.sdk.Listener.OnErrorListener;
import com.arkoselabs.sdk.Listener.OnFailedListener;
import com.arkoselabs.sdk.Listener.OnHideListener;
import com.arkoselabs.sdk.Listener.OnReadyListener;
import com.arkoselabs.sdk.Listener.OnResetListener;
import com.arkoselabs.sdk.Listener.OnShowListener;
import com.arkoselabs.sdk.Listener.OnShownListener;
import com.arkoselabs.sdk.Listener.OnSuppressListener;
import com.arkoselabs.sdk.Listener.OnResizeListener;
import com.arkoselabs.sdk.Model.ALSDK_Animation;
import com.arkoselabs.sdk.Model.ArkoseECResponse;
- In the main screen activity section (Under
src/main/java
), add anArkoseConfig
object in theonClick()
method of the Login Button element to interact with the SDK. Configure the parameters (API_URL_BASE
,API_KEY
, etc. as shown in this code) used to transfer data .
final ArkoseConfig arkoseConfig = ArkoseConfig.builder()
.API_URL_BASE(getResources().getString(R.string.API_URL_BASE))
.API_KEY(getResources().getString(R.string.API_KEY))
.API_FILE(getResources().getString(R.string.API_FILE))
.loading(true) // setting this to false will not show the default loading spinner
.DATA("") // encrypted data (optional)
.language("") // can set language here. Default is 'en'
.enableBackButton(true) // to disable/enable device back button in the EC or detection frame. Default is 'true'
.viewFrameAnimation(ALSDK_Animation.SCALE_CENTER.ordinal()) // this to set animation of how the EC frame will be loaded. You can use ALSDK_Animation.<AnimStyle>.ordinal() OR can set your own custom animation by putting value R.anim.<CustomAnimStyle>
.build();
-
-
If you want to add your own custom animation then the value of
viewFrameAnimation
will beR.anim.<CustomAnimStyle>
. TheCustomAnimStyle
is your animation xml file. -
We provide a number of inbuilt animations in the Mobile SDK. Use the desired animation style by replacing the
<AnimStyle>
inALSDK_Animation.<AnimStyle>.ordinal()
parameter. **ordinal()
method returns the ordinal of this enumeration constant (its position in its enum declaration, where the initial constant is assigned an ordinal of zero).- BLINK
- FADE
- SCALE_CENTER
- SEQUENTIAL
- SLIDE_DOWN
- SLIDE_LEFT
- SLIDE_RIGHT
- SLIDE_UP
- ZOOM_IN
- ZOOM_OUT
-
If the animation parameter is not set, no animation will be shown.
-
-
Just below the
ArkoseConfig
object definition , add a call to the library methodShowEnforcementChallenge(arkoseConfig)
with theArkoseConfig
object as its parameter. This will run Arkose Detect (when running Arkose Protect, it also runs Arkose’s Enforcement Challenge). Fill in the method definitions with what you want to happen when that method is invoked as described in the comments. Note there are separate code examples for Arkose Detect and Arkose Protect.
ArkoseLabs.getActivityClient(this).ShowEnforcementChallenge(arkoseConfig)
.addOnSuccessListener(new OnCompleteListener < ArkoseECResponse > () {
@Override
public void onComplete(ArkoseECResponse arkoseEnforcementChallengeResponse) {
// invoked On Enforcement Challenge success
}
})
.addOnFailureListener(new OnFailedListener < ArkoseECResponse > () {
@Override
public void onFailed(ArkoseECResponse arkoseEnforcementChallengeResponse) {
// invoked on Enforcement Challenge failed
}
})
.addOnErrorListener(new OnErrorListener<ArkoseECResponse>() {
@Override
public void onError(ArkoseECResponse arkoseECResponse) {
// invoked on getting error while loading EC
}
})
.addOnResizeListener(new OnResizeListener<ArkoseECResponse>() {
@Override
public void onResize(ArkoseECResponse arkoseECResponse) {
// Provides the width and height of the visible EC from an SDK call
// While you cannot set the width and height values yourself,
// you can make use of their new values from the resizing
// as you'd like, such as putting them in a log entry.
}
})
.addOnReadyListener(new OnReadyListener() {
@Override
public void onReady() {
//Do Something on ready callback received
}
})
.addOnShowListener(new OnShowListener() {
@Override
public void onShow() {
//Do Something on show callback received
}
})
.addOnShownListener(new OnShownListener() {
@Override
public void onShown() {
//Do Something on shown callback received
}
})
.addOnHideListener(new OnHideListener() {
@Override
public void onHide() {
//Do Something on hide callback received
}
})
.addOnResetListener(new OnResetListener() {
@Override
public void onReset() {
//Do Something on reset callback received
}
})
.addOnSuppressListener(new OnSuppressListener() {
@Override
public void onSuppress() {
//Do Something on suppress callback received
}
});
ArkoseLabs.getActivityClient(this).ShowEnforcementChallenge(arkoseConfig)
.addOnSuccessListener(new OnCompleteListener < ArkoseECResponse > () {
@Override
public void onComplete(ArkoseECResponse arkoseEnforcementChallengeResponse) {
// invoked On Detection success
}
})
.addOnErrorListener(new OnErrorListener<ArkoseECResponse>() {
@Override
public void onError(ArkoseECResponse arkoseECResponse) {
// invoked on getting error while loading detection
}
})
.addOnReadyListener(new OnReadyListener() {
@Override
public void onReady() {
//Do Something on ready callback received
}
})
.addOnShowListener(new OnShowListener() {
@Override
public void onShow() {
//Do Something on show callback received
}
.addOnHideListener(new OnHideListener() {
@Override
public void onHide() {
//Do Something on hide callback received
}
})
.addOnSuppressListener(new OnSuppressListener() {
@Override
public void onSuppress() {
//Do Something on suppress callback received
}
});
- In
main/res/values/strings.xml
, add this code anywhere in between<resources>
and</resources>
. Replace all the instances ofvalue
with whatever actual value you want its associated configuration parameter to have.
<string name="API_URL_BASE">value</string>
<string name="API_KEY" tools:ignore="TypographyDashes">value</string>
<string name="API_FILE">value</string>
Build the revised project
-
Go to the Build menu and click on Clean Project.
-
Go to the Build menu and click on Rebuild Project.
Run and test the app
-
Run your Android application.
-
- If running Arkose Protect, the view shows an Arkose Labs Enforcement Challenge.
- If running Arkose Detect, the view runs Arkose Labs Detect.
-
If running Arkose Protect, verify the challenge.
-
When the verification or detection is successful, the
onComplete
event returns a response token. The following sample code shows what this should look like and what to do with the token. Note there are separate code samples for Arkose Detect and Arkose Protect.
public void onComplete(ArkoseECResponse arkoseECResponse) {
String userResponseToken = arkoseECResponse.getResponse().toString();
// Get value of the token
String userResponseToken = arkoseECResponse.getResponse().getString("token");
Log.i(TAG,"Arkose EC complete: " + userResponseToken);
// sendToBackendServer(userResponseToken);
}
public void onComplete(ArkoseECResponse arkoseECResponse) {
String userResponseToken = arkoseECResponse.getResponse().toString();
// Get value of the token
String userResponseToken = arkoseECResponse.getResponse().getString("token");
Log.i(TAG,"Arkose Detection complete: " + userResponseToken);
// sendToBackendServer(userResponseToken);
}
ArkoseConfig
Configuration
ArkoseConfig
ConfigurationNote that Arkose Detect is part of our overall Arkose Protect detection and enforcement 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 Arkose Detect and Arkose Protect, although perhaps in different ways as specified.
Configuration Object | Type | Description | Applicable Product |
---|---|---|---|
| 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 Note that Arkose Detect is part of our overall Arkose Protect detection and enforcement platform. Thus the names of some methods and variables refer only to enforcement when actually dealing with detection as well. | Arkose Detect |
| Public Method | Method that starts the Arkose Labs detection when using Arkose Detect and enforcement when using Arkose Protect. Before calling this method, the model object ( This method adds two listeners:
| Arkose Detect |
| Function | Listener function invoked when the SDK has been loaded. | Arkose Detect |
| 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. | Arkose Detect |
| 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. | Arkose Detect |
| 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. | Arkose Protect |
| Function | Listener function invoked when b. For Arkose Detect, a session detection has been successfully completed. A Response Object is passed to this function. | Arkose Detect |
| 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. | Arkose Detect |
| 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 Arkose Detect is analyzing the user intent. | Arkose Detect |
| Function | Listener function invoked after the Enforcement resets. Typically occurs after a challenge has been successfully answered. | Arkose Protect |
| Function | Listener function invoked when an error occurs when loading the challenge or detection. A Response Object is passed to this function. | Arkose Detect |
| 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. | Arkose Protect |
| 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. | Arkose Protect |
Enforcement Challenge Configuration Parameters / strings.xml
strings.xml
You can change the following Enforcement Challenge configuration parameters by specifying their values in the strings.xml
file.
EC Configuration Parameters | Type | Description |
---|---|---|
| String | Base URL of Arkose Labs EC platform as supplied by Arkose Labs. |
| String | Public key for your account. |
| String | JavaScript file name of Arkose Labs EC as supplied by Arkose Labs. |
| String | Mainly used to share any client encrypted data blobs with the Arkose Labs Platform. It is optional. Default: |
| String | Not applicable to Arkose Detect. Language setting for the EC. Default: "en" |
strings.xml
Example
strings.xml
Example<resources xmlns:tools="http://schemas.android.com/tools">
<string name="app_name">Demo App</string>
<!--For Arkose Enforcement Challenge-->
<string name="API_URL_BASE">https://api.arkoselabs.com/v2</string>
<string name="API_KEY" tools:ignore="TypographyDashes">11111111-1111-1111-1111-111111111111</string>
<string name="API_FILE">api.js</string>
</resources>
Logging and Troubleshooting
Prerequisites
-
Install the Android Debug Bridge (adb) binary or driver on the machine where the logs will go.
-
An Android phone or Android emulator. On it, under Settings > Developer, enable the USB Debugging option
Steps
On the machine where the logs will go:
-
Download the SDK platform for your platform (Windows / Mac) from SDK Platform Tools release notes | Android Developers
-
Unzip the folder and check it contains an
adb.exe
file. -
From the command prompt, enter the path where
adb
is located on the machine. This image shows an example of what you get after you enter the path.


-
On your Android device, enable USB debugging:
-
At Phone>Settings>About Phone>, tap Build Number seven times. You should see a message saying that you are now a developer.
-
On the device, go to Developer options and turn on USB debugging.
-
Connect the device to the system and trust/allow the system.
-
To test if
adb
is working properly:-
Use a USB cable to connect your Android device to your computer.
-
At the computer’s command prompt, run the command
adb devices
to show the devices connected to the system.
-
-


- To start verbose logging in the terminal window, at the computer’s command prompt, run
adb logcat -s ArkoseLabsShowEnforcementChallenge:v
If instead you want to save the logs, runadb logcat -d > <path-where-you-want-to-save-file>/<filename>.txt
Ctrl+C stops the logging.
adb logcat
Options
adb logcat
Optionsadb logcat
has several command options. These include:
-
adb logcat
: Prints log data to the screen. -
adb logcat *:V
: Lowest priority, filter to only show Verbose level log entries. -
adb logcat --help
: Shows alllogcat
options and arguments. -
adb logcat -c
: Clears the logs . -
adb logcat -s <TAG>:<PRIORITY>
:-
-s
: Sets default filter to silent. -
<TAG>
: A log component tag (or*
for all). -
<PRIORITY>
can be:-
V
: Verbose (default for<TAG>
) -
D
: Debug (default for*
) -
I
: Info -
W
: Warn -
E
: Error -
F
: Fatal -
S
: Silent (suppress all output)
-
-
Updated 20 days ago