Available for the following Plan types:
FullStory Enterprise*
FullStory Advanced*
FullStory Business*
FullStory Free
*with the following add-on:
FullStory for Mobile Apps
Available to the following User roles:
Admin
Architect
Standard
Building Within Android Studio
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 execute and this may lead to crashes in the app.
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 Project
build.gradle
(by default located in the root folder), and - The App/Module
build.gradle
(by default located in theapp/
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 modern app to review, please contact FullStory Support and reference this document.
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.
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.38.0).
buildscript { repositories {
... maven { url "https://maven.fullstory.com" } } dependencies { ... classpath 'com.fullstory:gradle-plugin-local:<PLUGIN VERSION>'
}
}
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 {
...
Add the Plugin Properties
Replace <PLUGIN PROPERTIES>
with the available properties below:
Property | Options | Description |
---|---|---|
org |
Required |
Your Org ID |
enabledVariants |
Default: Options: varies |
Specify which Build Variants to be applied |
logcatLevel |
Default: Options: |
Capture Logcat messages at or above the specified level |
logLevel |
Default: Options: |
Capture FS.log() messages at or above the specified level |
recordOnStart (optional) |
Default: Options: |
Prevent FullStory from starting data capture on App Startup |
addDependencies (optional) |
Default: Options: |
Prevent FullStory Gradle Plugin from Auto-adding Gradle Dependencies |
serverUrl (optional) |
Default: Options: varies |
Specify the server url to route FullStory traffic through |
Your Org ID
Add your Org ID, which can be obtained by logging into FullStory. 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. For additional help finding your Org ID, check out this article.
Additionally, when you login to your FullStory account, your Org ID can be found in the URL of your browser.
https://app.fullstory.com/ui/<ORG_ID>/home
Specify which Build Variants to be applied
By default, FullStory is only applied to the release
variant of your app. If your build variant contains the word “release”, we will add our instrumentation code to the 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:
enabledVariants 'all'
If you want FullStory to be applied to specific variants, you can also use a regular expression like so:
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.
Capture Logcat and FS.log()
Messages
By default, FullStory will not capture logcat messages. Logcat messages, however, can capture frustration signals, such as error clicks. To change this behavior and capture frustration signals, update your logcatLevel
flag.
logcatLevel 'error'
By default, FullStory will capture any Log statements sent via FS.log()
API above and at 'info'
level in your application. To change this behavior, update your logLevel
flag.
logLevel 'error'
Any message sent below the specified level will not be sent to FullStory. For example, if 'info'
level is specified, 'debug'
and 'log'
messages will not be sent. Available options:
'off'
- no logging'error'
- error'warn'
- warning'info'
- info'debug'
- debug-
'log'
- verbose
Prevent FullStory from starting data capture on App Startup
By default, FullStory will start data capture on app startup. If you want to only start data capture once certain conditions are met, you can set recordOnStart
flag to false
, which will prevent data capture until FS.restart()
API is explicitly invoked.
recordOnStart false
Prevent FullStory Gradle Plugin from Auto-adding Gradle Dependencies
By default, FullStory Gradle Plugin will automatically add the correct AAR files to the project. If you do not want the Plugin to do this, you can set addDependencies
flag to false
.
addDependencies 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.38.0
will output:
FullStory: skipping auto-adding 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.38.0@aar'` manually to your application project's `dependencies`
If you are using a FullStory release prior to 1.23.0
, you will need to pass in -PfsAddGradleDependency=false
in the command line or set it as a project property in gradle.properties
as fsAddGradleDependency=false
.
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 {
...
}
In your AndroidManifest.xml
, under the <application>
tag, add android:name="App"
as below:
<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() {
...
}
In your AndroidManifest.xml
, under the <application>
tag, add android:name="App"
as below:
<application
android:name="App"
...
Permission requirements
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'
...
}
Additional topics
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>
.
FSOnReadyListener
You can implement FSOnReadyListener
and override onReady
to get notified of session data when FullStory is fully initialized and ready to be used.
If you're using Java:
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);
}
}
}
If you're using Kotlin:
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. 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.