Skip to main content

Integrating the Android SDK

Beta release

Beta release

The Sauce Mobile Beta SDK is in beta. The artifact names and the API are final; this documentation can still change. Share feedback with your Sauce Labs representative.

Integrating the Sauce Mobile Beta SDK into your app can help you better understand how your app performs on real devices. It tells you when and how people use your app and provides any metrics you may need to optimize your user experience and code.

Both Java and Kotlin apps are supported. The Android artifact is com.saucelabs.mobilebeta:sauce-mobile-beta-android and the Java package is com.testfairy.

Crash reporting

The SDK does not install a crash handler. Crash reporting is provided by Backtrace (Sauce Labs Error Reporting), and the two SDKs are designed to run in the same app. If you run both SDKs, initialize Backtrace first and follow Using Sauce Mobile Beta with Backtrace.

Requirements​

  • Android API level 16 or later. When you also ship Backtrace, use Backtrace's minimum (minSdk 21).
  • Gradle with access to https://maven.saucelabs.com. The SDK is not served from Maven Central or jcenter.

Installation​

1. Add the Maven Repository​

Add https://maven.saucelabs.com to settings.gradle (projects created with recent versions of Android Studio). The content filter is optional. It tells Gradle to look up only the com.saucelabs.mobilebeta group in this repository. Projects that already declare https://maven.testfairy.com can keep it: both hosts serve the same repository.

// settings.gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven.saucelabs.com'
            content { includeGroup 'com.saucelabs.mobilebeta' }
        }
    }
}

If your project declares repositories in the root build.gradle instead of settings.gradle, add the repository there:

// PROJECT_ROOT/build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://maven.saucelabs.com' }
    }
}

2. Add the Dependency​

Add the SDK to your app module's build.gradle (for example app/build.gradle). Pin the exact version. See Upgrading.

dependencies {
    implementation "com.saucelabs.mobilebeta:sauce-mobile-beta-android:2.3.0"
}

The SDK provides beta-testing capabilities: session recording, tester feedback, remote logs and update prompts. Prefer a beta or debug-only dependency, such as debugImplementation or a betaImplementation flavor configuration, so that store builds do not ship it. See Sauce Mobile Beta SDK in Production.

3. Initialize the SDK​

Initialize the SDK in the onCreate method of an Application subclass: set the server endpoint, then call beginWithoutCrashHandler. Replace <sauce-mobile-beta-token> and <server-endpoint> with your values.

Both values are in Organization Settings > SDK Settings on your Mobile App Distribution dashboard, under the organization that owns the app. Only Account Owners and Org Admins can open that page. See Organization Settings.

  • SDK App Token: the organization-wide token your app starts sessions with. Regenerating it invalidates the previous token for every build that still carries it.
  • Server Endpoint: the URL the SDK sends session data to, in the form https://<host>/services/. It is specific to your region or private instance, so copy it exactly. If it reads Not configured, contact Sauce Labs support before you ship a build.

Pass the endpoint to setServerEndpoint before beginWithoutCrashHandler. The SDK's built-in default server is no longer in service: an app that skips this call starts no sessions.

import android.app.Application;
import com.testfairy.TestFairy;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        // If you use Backtrace, initialize it before this line.
        TestFairy.setServerEndpoint("<server-endpoint>");
        TestFairy.beginWithoutCrashHandler(this, "<sauce-mobile-beta-token>");
    }
}

Register the class in AndroidManifest.xml:

<application
    android:name=".MyApplication"
    ...>
</application>

beginWithoutCrashHandler is the recommended entry point: it starts a session, never installs a crash handler, and forces the enableCrashReporter option to false, even if you pass true through the options overload beginWithoutCrashHandler(context, appToken, options). The plain begin(...) overloads also start a session without a crash handler.

When you run both SDKs, pass the Backtrace client to setBacktraceClient before beginWithoutCrashHandler, so that the SDK writes the sauce.correlation_id it generates for every session to Backtrace. The order, the SDK-managed attributes, and a complete Application example are in Using Sauce Mobile Beta with Backtrace.

ProGuard and R8 (Optional)​

The AAR bundles its consumer ProGuard rules, so Gradle applies them to your app automatically when minification is enabled. You do not need to add rules for the SDK. The rules also keep the Backtrace members the SDK reaches by reflection (addAttribute, getAttributes and the database field of BacktraceBase), so the session link survives R8 in release builds. If your app replaces the bundled rules, keep those entries.

Upgrading​

Always pin an exact version, such as 2.3.0, and update it deliberately. Do not use version wildcards such as 2.+: they can pull in a build you have not tested.

To upgrade, change the version string in build.gradle and rebuild. 2.3.0 is served from https://maven.saucelabs.com under the coordinate com.saucelabs.mobilebeta:sauce-mobile-beta-android:2.3.0.

How to Identify Users (Optional)​

The following example identifies users by email address.

TestFairy.setUserId("john@example.com");

Read Identifying Your Users for more identification options.

Additional Permissions (Optional)​

The SDK can record additional insights that require specific permissions. Below is a list of permissions required for each metric:

Logs - android.permission.READ_LOGS (Optional)​

To automatically upload device logs (logcat) to your account, add the permission android.permission.READ_LOGS. Check the Log collection under the Insights in Build Settings. You can do it after the app is uploaded or the first session performed.

Tracking Battery Usage - android.permission.BATTERY_STATS (Optional)​

Add the android.permission.BATTERY_STATS permission to automatically upload the battery status to your account. It tracks the general battery status and when the device is connected or disconnected from a charger.

Tracking Phone Signal - android.permission.READ_PHONE_STATE (Optional)​

To automatically upload a phone signal to your account, add the android.permission.READ_PHONE_STATE permission. The phone signal graph shows the GSM Signal Strength, with valid values (0-31, 99). 0 equals -113 dBm or less, and 31 equals -51 dBm or more. For more information, read GSM standard TS 27.007, section 8.5

Tracking WiFi Signal - android.permission.ACCESS_WIFI_STATE (Optional)​

To automatically upload the wifi status to your account, add the android.permission.ACCESS_WIFI_STATE permission: it tracks the wifi signal.

Troubleshooting​

The SDK is served from maven.saucelabs.com (and from maven.testfairy.com, which serves the same repository), not jcenter. If Gradle reports a Could not GET error for a jcenter.bintray.com URL, or Could not find com.saucelabs.mobilebeta:sauce-mobile-beta-android:2.3.0, add the repository as described in step 1 of the installation section.