Getting Started with Android Data Capture

 

As you're implementing the instructions below, you may find it useful to reference a sample app with FullStory integrated. We have an example of the SDK being implemented into an Android app here.

For modern Android apps

In modern Android application architecture, there are typically two build.gradle files that need to be modified when adding any Gradle plugins. These are:

• The root build.gradle (by default located in the root folder), and
• The app-specific build.gradle (by default located in the app/ folder).

The root build.gradle declares script plugin locations and classpaths. You’ll modify this file to point to the FullStory repository and add the FullStory plugin’s classpath (similar to how the Android Gradle plugin is declared).

In the app-specific build.gradle, you’ll apply the plugin and then declare a fullstory script block to configure some additional properties. This is analogous to how the Android application plugin is applied and the android configuration block is used for property declarations.

As you’re implementing the instructions below, you may find it useful to reference a sample app with a completed FullStory installation. If you would like a sample legacy app to review, please contact FullStory Support and reference this document.

Note: Beginning with Android Studio 3.5, the Apply Changes feature is enabled by default and cannot be disabled. We recommend building your APK via the command-line gradle task, instead of from within Android Studio. When building from within Android Studio, we cannot guarantee that the FullStory tasks will properly run. 

Add the FullStory maven plugin to your build script

Paste the highlighted lines into the Gradle Scripts section of your root build.gradle, ensure that you replace <THE PLUGIN VERSION> with the correct version of the FullStory Android plugin. You can find the latest release notes here (this is currently 1.28.0)

buildscript {
  repositories {
    ...
    maven { url "https://maven.fullstory.com" }
  }
  dependencies {
    ...
    classpath 'com.fullstory:gradle-plugin-local:<THE PLUGIN VERSION>'
    // NOTE: Do not place your application dependencies here; they belong
    // in the individual module build.gradle files
  }
}
 

Apply the FullStory plugin

Paste the highlighted lines into your app-specific build.gradle:

If your gradle file adds plugins via plugin id:

plugins {
  id 'com.android.application'
  id 'fullstory'
}
fullstory {
  org '<YOUR ORG ID HERE>'
}
android {
  ...

If your gradle file applies plugins:

apply plugin: 'com.android.application'
apply plugin: 'fullstory'
fullstory {
 org '<YOUR ORG ID HERE>'
}
android {
 ...

Replace <YOUR ORG ID HERE> with your ORG ID, which you can obtain by logging into the FullStory application. Navigate to Settings > Data Capture and Privacy > FullStory Setup, where you should see a line that looks like the following:window['_fs_org'] = 'XXXXX'; . This string is your ORG ID.

Using FullStory in library modules

The FullStory Android plugin supports libraries inside of multi-module applications, but does not support being applied to a stand-alone library. If you want to reference FullStory APIs from a library module within a multi-module app, set the repository and dependency as follows:

apply plugin: 'com.android.library'
repositories {
  maven { url "https://maven.fullstory.com" }
  ...
}
dependencies {
  implementation 'com.fullstory:instrumentation-full:<THE PLUGIN VERSION>@aar'
  ...
}

Instrumenting Debug Versions

By default, FullStory is only applied to the release variant of your app. That is, if your build variant contains the word “release”, we will add our instrumentation code to that APK after it is built.

To apply FullStory to all variants, including those used at debug time, add the following line below the org line:

org '<YOUR ORG ID HERE>'
enabledVariants 'all'

If you want FullStory to be applied to specific variants, you can also use a regular expression like so:

org '<YOUR ORG ID HERE>'
enabledVariants 'debug|release'

The variant name is constructed from the product flavor and build type (see example here). The FullStory build plugin will match the variant name case-insensitively.

Subclass from Application

FullStory requires that you enable MultiDex. If your minSdkVersion is set to 21 or higher, Multidex is enabled by default. Subclass from application class android.app.Application. If your minSdkVersion is lower than 21, you will need to subclass from androidx.multidex.MultiDexApplication instead.

If you're using Java:

If you do not have an Application class, create one, and in your App.java:

import android.app.Application;
public class App extends Application {
...
}

And set android:name="App" in your AndroidManifest.xml for <application> tag:

<application
android:name="App" ….

If you're using Kotlin:

If you do not have an Application class, create one, and in your App.kt:

import android.app.Application
class App: Application() {
...
}

And set android:name="App" in your AndroidManifest.xml for <application> tag:

<application
android:name="App" ….

FSOnReadyListener

public class MainActivity extends AppCompatActivity implements FSOnReadyListener{
    @Override
    public void onReady(FSSessionData sessionData) {
        // Use either sessionData.getCurrentSessionURL()
        // or FS.getCurrentSessionURL() here to retrieve session URL
        String sessionUrlfromData = sessionData.getCurrentSessionURL();
        String sessionUrl = FS.getCurrentSessionURL();
    }
}

class MainActivity : AppCompatActivity(), FSOnReadyListener {
     override fun onReady(sessionData: FSSessionData?) {
          Log.d("MainActivity", "SessionURL is: "+ FS.getCurrentSessionURL())
     }
}

Permission requirements

Add the following permissions, if not already added to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Optional Configurations

By default, FullStory will capture any Log statements above and at 'info' level in your application. This means that any FS.log() message sent below the 'info' level, including 'off,' 'log,' and 'debug,' will not be sent to FullStory. To change this behavior, update yourlogLevel configuration to a lower level when you apply the FullStory plugin. Options include:

• 'off' - no logging
• 'log' - verbose
• 'debug' - debug
• 'info' - info
• 'warn' - warning
• 'error' - error

logLevel 'error'

New in 1.11.1

FullStory will also disable logging logcat messages by default. Logcat messages can capture error clicks. To change this behavior and capture frustration signals, update yourlogcatLevel configuration settings. 

For legacy Android apps

Legacy Android apps that have been migrated from Eclipse to Android Studio have a single monolithic build.gradle file, rather than distinct root and app build.gradle files. As such, the FullStory installation process is identical to the process for modern apps, except that all modifications take place in the single build.gradle file. If you would like a sample legacy app to review, please contact FullStory Support and reference this document.

Identifying users and passing custom data to FullStory

On the Web, FullStory offers the FS.identify and FS.setUserVars JavaScript functions to enable you to enrich your FullStory data with additional variables for use in searches, segments, and integrations. This functionality is replicated on Android to allow you to pass user information to FullStory directly from your native app. The methods behave identically to their JavaScript counterparts linked above. The parameters are simply the Java equivalents of the original JavaScript parameters: FS.identify takes a String and an optional Map<String, Object>, while FS.setUserVars takes a Map<String, Object>.

Preventing FullStory from automatically capturing data on startup

Added in version: 1.5.1
By default, FullStory will automatically request a session and start capturing data on app startup. If you need to only start capturing data from the app once certain conditions are met, then you can use the new RecordOnStart feature. Configuring FullStory to not RecordOnStart will prevent data capture until you explicitly invoke FS.restart.

To prevent FullStory from capturing data on start, in the FullStory plugin configuration (where you set your org id), set the following:

fullstory {
  org '<YOUR ORG ID HERE>'
  recordOnStart false
}

Added in version1.11.0

Prevent the FullStory Gradle Plugin from Auto-adding Gradle Dependencies

By default, the FullStory gradle plugin will automatically add the correct maven repository and AAR file to the project. If you do not want the plugin to do this, pass in -PfsAddGradleDependency=falsein the command line or set it as a project property in gradle.properties as fsAddGradleDependency=false. When this is passed in, the FullStory plugin will output information to assist you in manually configuring the necessary pieces. For example, building with 1.11.0 will output:

FullStory: detected `fsAddGradleDependency=false`, skipping auto-adding gradle dependencies 
FullStory: you must add `maven { url "https://maven.fullstory.com"} `manually to your root project's `allprojects.repositories` 
FullStory: you must add `implementation 'com.fullstory:instrumentation-full:1.11.0@aar'`manually to your application project's `dependencies`

Additional topics

FullStory for Mobile Apps Privacy rules

For more information about configuring privacy rules and masking, please consult our FullStory for Mobile Apps Privacy Rules guide.

Turning mobile data capture on or off

Mobile data capture can be toggled on or off from Settings > Data Capture and Privacy > Mobile Data Capture. This applies across your entire FullStory account.

Configuring domain allowlisting for WebViews

If your application makes use of WebViews, you must explicitly allowlist any domain you wish to capture within a WebView. For security and privacy reasons, you should only allowlist domains which are under your control. Wildcards and subdomains are supported using the same scheme as Web domain settings. The key difference between the Web and Mobile settings is that while domain allowlisting is optional on Web, it is mandatory on Mobile if you wish to capture content within WebViews. If your application doesn’t use WebViews or you don’t care to capture within WebViews, you can safely ignore this section.

These settings can be configured from Settings > Data Capture and Privacy > Mobile Data Capture.