Getting Started with Android Data Capture

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 Project build.gradle (by default located in the root folder), and
• The App/Module 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; feel free to review the Android Shoppe Demo.

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.

Setup

1. Add the Fullstory maven repositories

If your application uses settings.gradle for plugin management

Use the configuration shown below in your settings.gradle:

  pluginManagement {
    repositories {
      ...
      maven { url "https://maven.fullstory.com" }
    }
  }
  dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
      ...
      maven { url "https://maven.fullstory.com" }
    }
  }
  rootProject.name = "My Application"
  include ':app'

If your application does not use settings.gradle for plugin management

Do not add the above code (or remove if already added) to your settings.gradle and instead use the configuration shown below in your root build.gradle:

buildscript {
    repositories {
      ...
      maven { url "https://maven.fullstory.com" }
    }
  }

2. In the Root Project build.gradle, add the Fullstory plugin

Paste the highlighted lines into the buildscript section, ensure that you replace <PLUGIN VERSION> with the latest version of the Fullstory Android plugin. You can find the latest release notes here (this is currently 1.66.0).

buildscript {
    dependencies {
      ...
      classpath 'com.fullstory:gradle-plugin-local:<PLUGIN VERSION>'
    }
  }

3. In the App/Module build.gradle, apply the Fullstory plugin

Paste the highlighted lines:

If your gradle file adds plugins via plugin id:

plugins {
    id 'com.android.application'
    id 'fullstory'
  }

  fullstory {
    org "<ORG ID>"
    <PLUGIN PROPERTIES>
  }

  android {
    ...

If your gradle file applies plugins:

apply plugin: 'com.android.application'
  apply plugin: 'fullstory'

  fullstory {
    org "<ORG ID>"
    <PLUGIN PROPERTIES>
  }

  android {
    ...

4. Add the Plugin Properties

Replace <PLUGIN PROPERTIES> with your configuration settings. See Android Configuration in the Developer Guide for a complete reference of all available options.

At minimum, you'll need to set your OrgID (required). You may also want to configure logging options, specify which build variants include Fullstory, control when recording starts, and customize other behaviors.

5. 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.
 

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 {
    ...
  }

In your AndroidManifest.xml, under the <application> tag, add android:name="App" as below:

<application
  android:name="App"
    ...

Kotlin:

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

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

In your AndroidManifest.xml, under the <application> tag, add android:name="App" as below:

<application
  android:name="App"
    ...

6. Declare App Permissions

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

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

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:<PLUGIN VERSION>@aar'
    ...
  }

If using Jetpack Compose, also add this to your dependencies:

implementation 'com.fullstory:compose'

Using Fullstory's Advanced Features

Identifying users and passing custom data to Fullstory

The FS.identify and FS.setUserVars enables you to enrich your Fullstory data with additional variables for use in searches, segments, and integrations. This functionality allows you to pass user information to Fullstory directly from your mobile app. The parameters are: FS.identify takes a String and an optional Map<String, Object>, while FS.setUserVars takes a Map<String, Object>.

Fullstory Initialization Callback

public class App extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          FS.setReadyListener(new FSSessionReadyListener());
      }

      private static class FSSessionReadyListener implements FSOnReadyListener {
          @Override
          public void onReady(FSSessionData sessionData) {
              String sessionUrl = sessionData.getCurrentSessionURL();
              Log.d("FullStory", "Session URL is: " + sessionUrl);
          }
      }
  }

class App : Application() {
      override fun onCreate() {
          super.onCreate()
          FS.setReadyListener(FSSessionReadyListener())
      }

      private class FSSessionReadyListener : FSOnReadyListener {
          override fun onReady(sessionData: FSSessionData) {
              Log.d("FullStory", "Session URL is: ${sessionData.currentSessionURL}")
          }
      }
  }

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. 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.

Note:  Fullstory SDK can capture contents of WKWebView (iOS) /WebView (Android) but not SFSafariViewController (iOS) /Chrome Custom Tabs (Android). Fullstory for Web may be used to capture contents of SFSafariViewController/Chrome Custom Tabs, but they will be displayed as separate sessions

Troubleshooting Missing Assets

Requires version 1.64.1+.

If ignoreUploadErrors was set to true and the network calls during the build process could not communicate with our servers, sessions will be missing some Assets (Images, Stylesheets, Fonts, etc.) during playback. To remedy this, run the new fullstoryBackfill gradle task on the original apk or aab file.

1. Navigate to the root of your application's source.
2. Run ./gradlew fullstoryBackfill -Pfile=path/to/apkOrAab.
3. Verify that playback now includes the previously missing Assets. Also confirm that calls to map.json are no longer resulting in 403 on your Browser Network Inspector.

Fullstory API

For information on usage, visit our developer docs.