Android SDK

This document will guide you through the process of adding AppSpector SDK to your project and tailoring it to your needs. Its simplified but sufficient for a quick setup version can be found in "Setup Guide" section on your project page on our website.

GitHub release

Installation

To start using AppSpector SDK, visit our site and add a new app (https://app.appspector.com).
It will generate a unique API key for your debug sessions. Navigate to app settings and copy it.

Setting SDK up with Gradle

In project build.gradle file:

buildscript {
  repositories {
      maven {
          url "https://maven.appspector.com/artifactory/android-sdk"
      }
  }
  
  dependencies {
      classpath "com.appspector:android-sdk-plugin:$latestVersion"
  }
}

In app build.gradle file:

apply plugin: 'com.android.application'
//aplly appspector plugin after application plugin
apply plugin: 'com.appspector.sdk'

repositories {
    maven {
        url "https://maven.appspector.com/artifactory/android-sdk"
    }
}

dependencies {
    implementation "com.appspector:android-sdk:$latestVersion"
}

Configuration

AppSpector uses modules called monitors to track different app activities and gather stats.
We provide a bunch of monitors out of the box which could be used all together or in any combinations.

To start AppSpector debug session, you need to build an instance of AppSpector and provide your API key.

You can start AppSpector with all available default monitors using:

AppSpector
            .build(this)
            .withDefaultMonitors()
            .run("YOUR_API_KEY");

AppSpector
            .build(this)
            .withDefaultMonitors()
            .run("YOUR_API_KEY")

Or you can choose specific monitors :

AppSpector
            .build(this)
            .addHttpMonitor()
            .addLogMonitor()
            .addEnvironmentMonitor()
            .addScreenshotMonitor()
            .addSQLMonitor()
            .addPerformanceMonitor()
            .addLocationMonitor()
            .run("YOUR_API_KEY");

AppSpector
            .build(this)
            .addHttpMonitor()
            .addLogMonitor()
            .addEnvironmentMonitor()
            .addScreenshotMonitor()
            .addSQLMonitor()
            .addPerformanceMonitor()
            .addLocationMonitor()
            .run("YOUR_API_KEY")

SDK start/stop

AppSpector start is two step process.
When you link with AppSpector framework it starts to collect data immediately after load. When you call run method - AppSpector opens a connection to the backend and from that point you can see your session on the frontend.

You can manually control AppSpector state by calling start and stop methods.
stop tells AppSpector to disable all data collection and close current session.
start starts it again using config you provided at load. This will be a new session, all activity between stop and start calls will not be tracked.

AppSpector.shared().stop();
AppSpector.shared().start();

AppSpector.shared().stop()
AppSpector.shared().start()

Custom device name

You can assign a custom name to your device to easily find needed sessions in the sessions list. To do this you have to add the desired name as a value for AppSpector.METADATA_KEY_DEVICE_NAME key to the metadata dictionary:

AppSpector
            .build(this)
            .withDefaultMonitors()
            .addMetadata(AppSpector.METADATA_KEY_DEVICE_NAME, "YOUR_DEVICE_NAME")
            .run("YOUR_API_KEY");

AppSpector
            .build(this)
            .withDefaultMonitors()
            .addMetadata(AppSpector.METADATA_KEY_DEVICE_NAME, "YOUR_DEVICE_NAME")
            .run("YOUR_API_KEY")

Getting session URL

Sometimes you may need to get URL pointing to current session from code. Say you want link crash in your crash reporter with it, write it to logs or display in your debug UI. To get this URL you have to add a session start callback:

AppSpector.shared().setSessionUrlListener(new SessionUrlListener() {
  @Override
  public void onReceived(@NonNull String sessionUrl) {
    // Save url for future use...
  }
});

AppSpector.shared()?.setSessionUrlListener { 
  // Save url for future use...
}

Disable background data collection

By default, AppSpector SDK is active until the application is killed by Android OS, even if no activities left.
It may lead to unnecessary data collection and long sessions for inactive apps.
We provide API to disable data collection for a case when the app has no started activities.

AppSpector
            .build(this)
            .collectDataInBackground(false) // Set this flag to disable data collection if no activities left
            .withDefaultMonitors()
            .run("YOUR_API_KEY");

AppSpector
            .build(this)
            .collectDataInBackground(false) // Set this flag to disable data collection if no activities left
            .withDefaultMonitors()
            .run("YOUR_API_KEY")

Using OkHttp interceptor instead of AppSpector Gradle Plugin

If you don't want to use AppSpector Gradle Plugin you could use an alternative way to intercept HTTP requests and responses. You can manually add AppSpectorOkHttp3Interceptor to your OkHttpClient (Or AppSpectorOkHttp2Interceptor for old version of OkHttpClient). Also, don't forget to remove AppSpector plugin from your app/build.gradle file.

new OkHttpClient.Builder()
    .addInterceptor(new AuthenticationInterceptor()) // for example, it adds auth token to you request
    .addInterceptor(new AppSpectorOkHttp3Interceptor()) // it will track your requests and responses
    .build()

OkHttpClient.Builder()
    .addInterceptor(AuthenticationInterceptor())
    .addInterceptor(AppSpectorOkHttp3Interceptor())
    .build()

Feedback

Let us know what you think or what improvements you would like to see: [email protected].