This is the Android SDK of Adjust™. You can read more about Adjust™ at adjust.com.
Read this in other languages: English, 中文, 日本語, 한국어.
- Deep linking overview
- Standard deep linking scenario
- Deferred deep linking scenario
- Reattribution via deep links
- Push token (uninstall tracking)
- Attribution callback
- Ad revenue tracking
- Session and event callbacks
- User attribution
- Device IDs
- Pre-installed trackers
- Offline mode
- Disable tracking
- Event buffering
- Background tracking
- GDPR right to be forgotten
- I'm seeing the "session failed (Ignoring too frequent session...)" error
- Is my broadcast receiver capturing the install referrer?
- Can I trigger an event at application launch?
There are Android example apps inside the example-app-java
and example-app-kotlin
directories, as well as example app that uses web views inside the example-webbridge
directory and Android TV example app inside the example-app-tv
directory. You can open the Android project to see these examples on how the Adjust SDK can be integrated.
These are the minimum required steps to integrate the Adjust SDK in your Android app. We assume that you are using Android Studio for your Android development. The minimum supported Android API level for the Adjust SDK integration is 9 (Gingerbread).
If you are using Maven, add the following to your build.gradle
file:
implementation 'com.adjust.sdk:adjust-android:4.18.0'
implementation 'com.android.installreferrer:installreferrer:1.0'
If you would prefer to use the Adjust SDK inside web views in your app, please include this additional dependency as well:
implementation 'com.adjust.sdk:adjust-android-webbridge:4.17.0'
You can also add the Adjust SDK and web view extension as JAR files, which can be downloaded from our releases page.
Since the 1st of August of 2014, apps in the Google Play Store must use the Google Advertising ID to uniquely identify devices. To enable the Google Advertising ID for our SDK, you must integrate Google Play Services. If you haven't done this yet, please add dependency to the Google Play Services library by adding the following dependecy to your dependencies
block of app's build.gradle
file:
implementation 'com.google.android.gms:play-services-analytics:16.0.4'
Note: The Adjust SDK is not tied to any specific version of the play-services-analytics
part of the Google Play Services library. You can use the latest version of the library, or any other version you need.
The Adjust SDK requires the following permissions. Please add them to your AndroidManifest.xml
file if they are not already present:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
If you are not targeting the Google Play Store, you must also add the following permission:
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
If you are using Proguard, add these lines to your Proguard file:
-keep public class com.adjust.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
int SUCCESS;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
java.lang.String getId();
boolean isLimitAdTrackingEnabled();
}
-keep public class com.android.installreferrer.** { *; }
If you are not publishing your app in the Google Play Store, use the following com.adjust.sdk
package rules:
-keep public class com.adjust.sdk.** { *; }
In order to correctly attribute an app install to its source, Adjust needs information about the install referrer. We can achieve this in two different ways: either by using the Google Play Referrer API or by collecting the Google Play Store intent with a broadcast receiver.
Important: Google introduced the Google Play Referrer API to provide a more reliable and secure way to obtain install referrer information and to aid attribution providers in the fight against click injection. We strongly advise you to support this in your application. The Google Play Store intent is a less secure way of obtaining install referrer information. For now it exists in parallel with the new Google Play Referrer API, but will be deprecated in the future.
In order to support the Google Play Referrer API in your app, please make sure that you have followed our chapter on adding the SDK to your project correctly and that you have following line added to your build.gradle
file:
implementation 'com.android.installreferrer:installreferrer:1.0'
Please follow the directions for your Proguard settings carefully. Confirm that you have added all the rules mentioned in it, especially the one needed for this feature:
-keep public class com.android.installreferrer.** { *; }
This feature is supported if you are using Adjust SDK v4.12.0 or above.
You should capture the Google Play Store INSTALL_REFERRER
intent with a broadcast receiver. If you are not using your own broadcast receiver to receive the INSTALL_REFERRER
intent, add the following receiver
tag inside the application
tag in your AndroidManifest.xml
.
<receiver
android:name="com.adjust.sdk.AdjustReferrerReceiver"
android:permission="android.permission.INSTALL_PACKAGES"
android:exported="true" >
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>
We use this broadcast receiver to retrieve the install referrer and pass it to our backend.
If you are using a different broadcast receiver for the INSTALL_REFERRER
intent, follow these instructions to properly ping the Adjust broadcast receiver.
First, we'll set up basic session tracking.
If you are integrating the SDK into a native app, follow the directions for a Native App SDK. If you are integrating the SDK for usage inside web views, please follow the directions for a Web Views SDK below.
We recommend using a global Android Application class to initialize the SDK. If you don't have one in your app, follow these steps:
-
Create a class that extends the
Application
. -
Open the
AndroidManifest.xml
file of your app and locate the<application>
element. -
Add the attribute
android:name
and set it to the name of your new application class.In our example app, we use an
Application
class namedGlobalApplication
. Therefore, we configure the manifest file as:<application android:name=".GlobalApplication" <!-- ... --> </application>
-
In your
Application
class, find or create theonCreate
method. Add the following code to initialize the Adjust SDK:import com.adjust.sdk.Adjust; import com.adjust.sdk.AdjustConfig; public class GlobalApplication extends Application { @Override public void onCreate() { super.onCreate(); String appToken = "{YourAppToken}"; String environment = AdjustConfig.ENVIRONMENT_SANDBOX; AdjustConfig config = new AdjustConfig(this, appToken, environment); Adjust.onCreate(config); } }
Replace {YourAppToken}
with your app token. You can find this in your dashboard.
Next, you must set the environment
to either sandbox or production mode:
String environment = AdjustConfig.ENVIRONMENT_SANDBOX;
String environment = AdjustConfig.ENVIRONMENT_PRODUCTION;
Important: Set the value to AdjustConfig.ENVIRONMENT_SANDBOX
if (and only if) you or someone else is testing your app. Make sure to set the environment to AdjustConfig.ENVIRONMENT_PRODUCTION
before you publish the app. Set it back to AdjustConfig.ENVIRONMENT_SANDBOX
if you start developing and testing it again.
We use this environment to distinguish between real traffic and test traffic from test devices. Keeping the environment updated according to your current status is very important!
After you have obtained the reference to your WebView
object:
- Call
webView.getSettings().setJavaScriptEnabled(true)
, to enable Javascript in the web view - Start the default instance of
AdjustBridgeInstance
by callingAdjustBridge.registerAndGetInstance(getApplication(), webview)
- This will also register the Adjust bridge as a Javascript Interface to the web view
After these steps, your activity should look like this:
public class MainActivity extends Activity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
WebView webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);
webView.setWebChromeClient(new WebChromeClient());
webView.setWebViewClient(new WebViewClient());
AdjustBridge.registerAndGetInstance(getApplication(), webview);
try {
webView.loadUrl("file:///android_asset/AdjustExample-WebView.html");
} catch (Exception e) {
e.printStackTrace();
}
}
}
After you complete this step, you will have successfully added the Adjust bridge to your app. The Javascript bridge is now enabled to communicate between Adjust's native Android SDK and your page, which will be loaded in the web view.
In your HTML file, import the Adjust Javascript files which are located in the root of the assets folder. If your HTML file is there as well, import them like this:
<script type="text/javascript" src="adjust.js"></script>
<script type="text/javascript" src="adjust_event.js"></script>
<script type="text/javascript" src="adjust_config.js"></script>
Once you add your references to the Javascript files, use them in your HTML file to initialise the Adjust SDK:
let yourAppToken = '{YourAppToken}';
let environment = AdjustConfig.EnvironmentSandbox;
let adjustConfig = new AdjustConfig(yourAppToken, environment);
Adjust.onCreate(adjustConfig);
Replace {YourAppToken}
with your app token. You can find this in your dashboard.
Next, set your environment
to the corresponding value, depending on whether you are still testing or are in production mode:
let environment = AdjustConfig.EnvironmentSandbox;
let environment = AdjustConfig.EnvironmentProduction;
Important: Set your value to AdjustConfig.EnvironmentSandbox
if (and only if) you or someone else is testing your app. Make sure you set the environment to AdjustConfig.EnvironmentProduction
just before you publish the app. Set it back to AdjustConfig.EnvironmentSandbox
if you start developing and testing again.
We use this environment to distinguish between real traffic and test traffic from test devices. Keeping it updated according to your current status is very important!
Note: This step is very important. Please make sure that you implement it properly in your app. Completing this step correctly ensures that the Adjust SDK can properly track sessions in your app.
-
Add a private class that implements the
ActivityLifecycleCallbacks
interface. If you don't have access to this interface, your app is targeting an Android API level lower than 14. You will have to manually update each activity by following these instructions. If you haveAdjust.onResume
andAdjust.onPause
calls on each of your app's activities, you should remove them. -
Edit the
onActivityResumed(Activity activity)
method and add a call toAdjust.onResume()
. Edit theonActivityPaused(Activity activity)
method and add a call toAdjust.onPause()
. -
Add the
onCreate()
method with the Adjust SDK is configured and callregisterActivityLifecycleCallbacks
with an instance of the createdActivityLifecycleCallbacks
class.import com.adjust.sdk.Adjust; import com.adjust.sdk.AdjustConfig; public class GlobalApplication extends Application { @Override public void onCreate() { super.onCreate(); String appToken = "{YourAppToken}"; String environment = AdjustConfig.ENVIRONMENT_SANDBOX; AdjustConfig config = new AdjustConfig(this, appToken, environment); Adjust.onCreate(config); registerActivityLifecycleCallbacks(new AdjustLifecycleCallbacks()); } private static final class AdjustLifecycleCallbacks implements ActivityLifecycleCallbacks { @Override public void onActivityResumed(Activity activity) { Adjust.onResume(); } @Override public void onActivityPaused(Activity activity) { Adjust.onPause(); } //... } }
If your app minSdkVersion
in gradle is between 9
and 13
, consider updating it to at least 14
to simplify the integration process. Consult the official Android dashboard to find out the latest market share of the major versions.
To provide proper session tracking, certain Adjust SDK methods are called every time an activity resumes or pauses (otherwise the SDK might miss a session start or end). In order to do so, follow these steps for each Activity of your app:
- In your Activity's
onResume
method, callAdjust.onResume()
. Create the method if needed. - In your Activity's
onPause
method, callAdjust.onPause()
. Create the method if needed.
After these steps, your activity should look like this:
import com.adjust.sdk.Adjust;
public class YourActivity extends Activity {
protected void onResume() {
super.onResume();
Adjust.onResume();
}
protected void onPause() {
super.onPause();
Adjust.onPause();
}
}
Repeat these steps for every Activity in your app. Don't forget to repeat these steps whenever you create a new activity in the future. Depending on your coding style, you might want to implement this in a common superclass of all your activities.
An account manager must activate the Adjust SDK Signature. Contact Adjust support ([email protected]) if you are interested in using this feature.
If the SDK signature has already been enabled on your account and you have access to App Secrets in your Adjust Dashboard, please use the method below to integrate the SDK signature into your app.
An App Secret is set by calling setAppSecret
on your config instance:
Native App SDK |
AdjustConfig config = new AdjustConfig(this, appToken, environment);
config.setAppSecret(secretId, info1, info2, info3, info4);
Adjust.onCreate(config); |
Web View SDK |
let adjustConfig = new AdjustConfig(yourAppToken, environment);
adjustConfig.setAppSecret(secretId, info1, info2, info3, info4);
Adjust.onCreate(adjustConfig); |
You can increase or decrease the amount of logs that you see during testing by calling setLogLevel
on your config instance with one of the following parameters:
Native App SDK |
config.setLogLevel(LogLevel.VERBOSE); // enable all logs
config.setLogLevel(LogLevel.DEBUG); // disable verbose logs
config.setLogLevel(LogLevel.INFO); // disable debug logs (default)
config.setLogLevel(LogLevel.WARN); // disable info logs
config.setLogLevel(LogLevel.ERROR); // disable warning logs
config.setLogLevel(LogLevel.ASSERT); // disable error logs
config.setLogLevel(LogLevel.SUPRESS); // disable all logs |
Web View SDK |
adjustConfig.setLogLevel(AdjustConfig.LogLevelVerbose); // enable all logs
adjustConfig.setLogLevel(AdjustConfig.LogLevelDebug); // disable verbose logs
adjustConfig.setLogLevel(AdjustConfig.LogLevelInfo); // disable debug logs (default)
adjustConfig.setLogLevel(AdjustConfig.LogLevelWarn); // disable info logs
adjustConfig.setLogLevel(AdjustConfig.LogLevelError); // disable warning logs
adjustConfig.setLogLevel(AdjustConfig.LogLevelAssert); // disable error logs
adjustConfig.setLogLevel(AdjustConfig.LogLevelSuppress); // disable all logs |
If you want to disable all of your log output, set the log level to suppress, and use the constructor for config object (which gets boolean parameters indicating whether or not suppress log level should be supported):
Native App SDK |
AdjustConfig config = new AdjustConfig(this, appToken, environment, true);
config.setLogLevel(LogLevel.SUPRESS);
Adjust.onCreate(config); |
Web View SDK |
let adjustConfig = new AdjustConfig(yourAppToken, environment, true);
adjustConfig.setLogLevel(AdjustConfig.LogLevelSuppress);
Adjust.onCreate(adjustConfig); |
Build and run your Android app. In your LogCat
viewer, set the filter tag:Adjust
to hide all other logs. After your app has launched you should see the following Adjust log: Install tracked
.
If you are using Adjust tracker URLs with deeplinking enabled, it is possible to receive information about the deeplink URL and its content. Users may interact with the URL regardless of whether they have your app installed on their device (standard deep linking scenario) or not (deferred deep linking scenario). In the standard deep linking scenario, the Android platform natively offers the possibility for you to receive deep link content information. The Android platform does not automatically support deferred deep linking scenario; in this case, the Adjust SDK offers the mechanism you need to get the information about the deep link content.
If a user has your app installed and you want it to launch after they engage with an Adjust tracker URL with the deep_link
parameter in it, enable deeplinking in your app. This is done by choosing a desired unique scheme name. You'll assign it to the activity you want to launch once your app opens following a user selecting the tracker URL in theAndroidManifest.xml
file. Add the intent-filter
section to your desired activity definition in the manifest file and assign an android:scheme
property value with the desired scheme name:
<activity
android:name=".MainActivity"
android:configChanges="orientation|keyboardHidden"
android:label="@string/app_name"
android:screenOrientation="portrait">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="adjustExample" />
</intent-filter>
</activity>
If you want your app to launch once the tracker URL is selected, use the assigned scheme name in the Adjust tracker URL's deep_link
parameter. A tracker URL without any information added to the deeplink could look something like this:
https://app.adjust.com/abc123?deep_link=adjustExample%3A%2F%2F
Don't forget: you must url encode the deep_link
parameter value in the URL.
With the app set as described above, your app will launch along with the MainActivity
intent when a user selects the tracker URL. Inside the MainActivity
class, you will automatically receive the information about the deep_link
parameter content. Once you receive this content, it will not be encoded (even though it was encoded in the URL).
The activity setting of your android:launchMode
within the AndroidManifest.xml
file will determine the delivery location of the deep_link
parameter content within the activity file. For more information about the possible values of the android:launchMode
property, check out Android's official documentation.
Deeplink content information within your desired activity is delivered via the Intent
object, via either the activity's onCreate
or onNewIntent
methods. Once you've launched your app and have triggered one of these methods, you will be able to receive the actual deeplink passed in the deep_link
parameter in the click URL. You can then use this information to conduct some additional logic in your app.
You can extract deeplink content from either two methods like so:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Intent intent = getIntent();
Uri data = intent.getData();
// data.toString() -> This is your deep_link parameter value.
}
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
Uri data = intent.getData();
// data.toString() -> This is your deep_link parameter value.
}
Deferred deeplinking scenario occurs when a user clicks on an Adjust tracker URL with a deep_link
parameter contained in it, but does not have the app installed on the device at click time. When the user clicks the URL, they will be redirected to the Play Store to download and install your app. After opening it for the first time, deep_link
parameter content will be delivered to your app.
The Adjust SDK opens the deferred deep link by default. There is no extra configuration needed.
If you wish to control if the Adjust SDK will open the deferred deep link, you can do it with a callback method in the config object.
Native App SDK |
AdjustConfig config = new AdjustConfig(this, appToken, environment);
// Evaluate the deeplink to be launched.
config.setOnDeeplinkResponseListener(new OnDeeplinkResponseListener() {
@Override
public boolean launchReceivedDeeplink(Uri deeplink) {
// ...
if (shouldAdjustSdkLaunchTheDeeplink(deeplink)) {
return true;
} else {
return false;
}
}
});
Adjust.onCreate(config); After the Adjust SDK receives the deep link information from our backend, the SDK will deliver you its content via the listener and expect the If you return |
Web View SDK |
let adjustConfig = new AdjustConfig(yourAppToken, environment);
adjustConfig.setDeferredDeeplinkCallback(function (deeplink) {});
Adjust.onCreate(adjustConfig); In this deferred deep linking scenario, there is one additional setting you can set on the config object. Once the Adjust SDK gets the deferred deep link information, you have the possibility to choose whether our SDK opens the URL or not. Set this option by calling the // ...
function deferredDeeplinkCallback(deeplink) {}
let adjustConfig = new AdjustConfig(yourAppToken, environment);
adjustConfig.setOpenDeferredDeeplink(true);
adjustConfig.setDeferredDeeplinkCallback(deferredDeeplinkCallback);
Adjust.start(adjustConfig); Remember that if you do not set the callback, the Adjust SDK will always attempt to launch the URL by default. |
Adjust enables you to run re-engagement campaigns with deeplinks. For more information, please check our official docs.
If you are using this feature, you need to make one additional call to the Adjust SDK in your app for us to properly reattribute your users.
Once you have received the deeplink content in your app, add a call to the Adjust.appWillOpenUrl(Uri, Context)
method. By making this call, the Adjust SDK will send information to the Adjust backend to check if there is any new attribution information inside of the deeplink. If your user is reattributed due to a click on the Adjust tracker URL with deeplink content, you will see the attribution callback triggered in your app with new attribution info for this user.
Here's how the call to Adjust.appWillOpenUrl(Uri, Context)
should look:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Intent intent = getIntent();
Uri data = intent.getData();
Adjust.appWillOpenUrl(data, getApplicationContext());
}
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
Uri data = intent.getData();
Adjust.appWillOpenUrl(data, getApplicationContext());
}
Note: Adjust.appWillOpenUrl(Uri)
method is marked as deprecated as of Android SDK v4.14.0. Please use Adjust.appWillOpenUrl(Uri, Context)
method instead.
Note for web view: This call can also be made from the web view with the function Adjust.appWillOpenUrl
in Javascript like so:
Adjust.appWillOpenUrl(deeplinkUrl);
You can use Adjust to track any event in your app. Suppose you want to track every tap on a button. To do so, you'll create a new event token in your dashboard. Let's say that the event token is abc123
. In your button's onClick
method, add the following lines to track the click:
Native App SDK |
AdjustEvent adjustEvent = new AdjustEvent("abc123");
Adjust.trackEvent(adjustEvent); |
Web View SDK |
let adjustEvent = new AdjustEvent('abc123');
Adjust.trackEvent(adjustEvent); |
If your users can generate revenue by tapping on advertisements or making in-app purchases, you can track those revenues too with events. Let's say a tap is worth one Euro cent. You can track the revenue event like this:
Native App SDK |
AdjustEvent adjustEvent = new AdjustEvent("abc123");
adjustEvent.setRevenue(0.01, "EUR");
Adjust.trackEvent(adjustEvent); |
Web View SDK |
let adjustEvent = new AdjustEvent('abc123');
adjustEvent.setRevenue(0.01, 'EUR');
Adjust.trackEvent(adjustEvent); |
This can be combined with callback parameters.
When you set a currency token, Adjust will automatically convert the incoming revenues into a reporting revenue of your choice. Read more about currency conversion here.
If you want to track in-app purchases, please make sure to call trackEvent
only if the purchase is finished and the item has been purchased. This is important in order avoid tracking revenue that was not actually generated.
You can read more about revenue and event tracking at Adjust in the event tracking guide.
You can also add an optional order ID to avoid tracking duplicate revenues. By doing so, the last ten order IDs will be remembered and revenue events with duplicate order IDs are skipped. This is especially useful for tracking in-app purchases. You can see an example below.
Native App SDK |
AdjustEvent adjustEvent = new AdjustEvent("abc123");
adjustEvent.setRevenue(0.01, "EUR");
adjustEvent.setOrderId("{OrderId}");
Adjust.trackEvent(adjustEvent); |
Web View SDK |
let adjustEvent = new AdjustEvent('abc123');
adjustEvent.setRevenue(0.01, 'EUR');
adjustEvent.setOrderId('{OrderId}');
Adjust.trackEvent(event); |
It's possible to verify the in-app Purchases made in your app using Adjust's Purchase Verification, a server side receipt verification tool. Click the link to find out more.
In addition to the data points the Adjust SDK collects by default, you can use the Adjust SDK to track and add as many custom values as you need (user IDs, product IDs, etc.) to the event or session. Custom parameters are only available as raw data and will not appear in your Adjust dashboard.
You should use callback parameters for the values you collect for your own internal use, and partner parameters for those you share with external partners. If a value (e.g. product ID) is tracked both for internal use and external partner use, we recommend you track it with both callback and partner parameters.
You can register a callback URL for your events in your dashboard. We will send a GET request to that URL whenever the event is tracked. You can add callback parameters to that event by calling addCallbackParameter
to the event instance before tracking it. We will then append these parameters to your callback URL.
For example, if you've registered the URL http://www.example.com/callback
, then you would track an event like this:
Native App SDK |
AdjustEvent adjustEvent = new AdjustEvent("abc123");
adjustEvent.addCallbackParameter("key", "value");
adjustEvent.addCallbackParameter("foo", "bar");
Adjust.trackEvent(adjustEvent); |
Web View SDK |
let adjustEvent = new AdjustEvent('abc123');
adjustEvent.addCallbackParameter('key', 'value');
adjustEvent.addCallbackParameter('foo', 'bar');
Adjust.trackEvent(adjustEvent); |
In this case we would track the event and send a request to:
http://www.example.com/callback?key=value&foo=bar
Adjust supports a variety of placeholders, for example {gps_adid}
, which can be used as parameter values. In the resulting callback, we would replace the placeholder (in this case) with the Google Play Services ID of the current device. Please note that we don't store any of your custom parameters. We only append them to your callbacks. If you haven't registered a callback for an event, we will not even read these parameters.
You can read more about URL callbacks (including a full list of available values) in our callbacks guide.
When your parameters are activated in the Adjust dashboard, you have the option to transmit them to your network partners.
This works similarly to the callback parameters mentioned above; add them by calling the addPartnerParameter
method to your event instance.
Native App SDK |
AdjustEvent adjustEvent = new AdjustEvent("abc123");
adjustEvent.addPartnerParameter("key", "value");
adjustEvent.addPartnerParameter("foo", "bar");
Adjust.trackEvent(adjustEvent); |
Web View SDK |
let adjustEvent = new AdjustEvent('abc123');
adjustEvent.addPartnerParameter('key', 'value');
adjustEvent.addPartnerParameter('foo', 'bar');
Adjust.trackEvent(adjustEvent); |
You can read more about special partners and these integrations in our guide to special partners.
You can add custom string identifiers to each event you want to track. This identifier will later be reported in your event success and/or event failure callbacks. This lets you keep track of which event was successfully tracked. Set this identifier by calling the setCallbackId
method on your event instance:
Native App SDK |
AdjustEvent adjustEvent = new AdjustEvent("abc123");
adjustEvent.setCallbackId("Your-Custom-Id");
Adjust.trackEvent(adjustEvent); |
Web View SDK |
let adjustEvent = new AdjustEvent('abc123');
adjustEvent.setCallbackId('Your-Custom-Id');
Adjust.trackEvent(adjustEvent); |
Session parameters are saved locally and sent in every event and session of the Adjust SDK. When you add any of these parameters, we will save them so you don't need to add them every time. Adding the same parameter twice will have no effect.
These session parameters can be called before the Adjust SDK is launched (to make sure they are sent on install). If you need to send them with an install, but can only obtain the needed values after launch, it's possible to delay the first launch of the Adjust SDK to allow for this behavior.
You can save any callback parameters registered for events to be sent in every event or session of the Adjust SDK.
The session callback parameters' interface is similar to the one for event callback parameters. Instead of adding the key and its value to an event, add them via a call to Adjust.addSessionCallbackParameter(String key, String value)
:
Native App SDK |
Adjust.addSessionCallbackParameter("foo", "bar"); |
Web View SDK |
Adjust.addSessionCallbackParameter('foo', 'bar'); |
Session callback parameters merge together with the callback parameters you add to an event. Callback parameters added to an event take precedence over session callback parameters, meaning that if you add a callback parameter to an event with the same key to one added from the session, the value that prevails is the callback parameter added to the event.
It's possible to remove a specific session callback parameter by passing the desired key to the method: Adjust.removeSessionCallbackParameter(String key)
.
Native App SDK |
Adjust.removeSessionCallbackParameter("foo"); |
Web View SDK |
Adjust.removeSessionCallbackParameter('foo'); |
If you wish to remove all keys and their corresponding values from the session callback parameters, you can reset with the method Adjust.resetSessionCallbackParameters()
.
Native App SDK |
Adjust.resetSessionCallbackParameters(); |
Web View SDK |
Adjust.resetSessionCallbackParameters(); |
In the same way that session callback parameters are sent in every event or session of the Adjust SDK, there are also session partner parameters.
These are transmitted to network partners for all of the integrations activated in your Adjust dashboard.
The session partner parameters interface is similar to the event partner parameters interface. Instead of adding the key and its value to an event, add it by calling Adjust.addSessionPartnerParameter(String key, String value)
:
Native App SDK |
Adjust.addSessionPartnerParameter("foo", "bar"); |
Web View SDK |
Adjust.addSessionPartnerParameter('foo', 'bar'); |
The session partner parameters will be merged with the partner parameters added to an event. The partner parameters added to an event take precedence over the session partner parameters. This means that when adding a partner parameter to an event with the same key to one added from the session, the value that prevails is the partner parameter added to the event.
It's possible to remove a specific session partner parameter by passing the desiring key to the method Adjust.removeSessionPartnerParameter(String key)
.
Native App SDK |
Adjust.removeSessionPartnerParameter("foo"); |
Web View SDK |
Adjust.removeSessionPartnerParameter('foo'); |
If you wish to remove all keys and their corresponding values from the session partner parameters, reset it with the method Adjust.resetSessionPartnerParameters()
.
Native App SDK |
Adjust.resetSessionPartnerParameters(); |
Web View SDK |
Adjust.resetSessionPartnerParameters(); |
Delaying the start of the Adjust SDK allows your app some time to obtain session parameters (such as unique identifiers) to be sent on install.
Set the initial delay time in seconds with the method setDelayStart
in the config instance:
Native App SDK |
adjustConfig.setDelayStart(5.5); |
Web View SDK |
adjustConfig.setDelayStart(5.5); |
In this example, this will prevent the Adjust SDK from sending the initial install session and any event created for 5.5 seconds. After the time expireds (or if you call Adjust.sendFirstPackages()
during that time) every session parameter will be added to the delayed install session and events; the Adjust SDK will resume as usual.
The maximum delay start time of the adjust SDK is 10 seconds.
Once you have integrated the Adjust SDK into your project, you can take advantage of the following features:
Push tokens are used for Audience Builder and client callbacks; they are also required for uninstall and reinstall tracking.
To send us the push notification token, add the following call to Adjust once you have obtained your token (or whenever its value changes):
Native SDK |
Adjust.setPushToken(pushNotificationsToken, context); This updated signature with We do, however, still support the previous signature of the same method without the |
Web View SDK |
Adjust.setPushToken(pushNotificationsToken); |
You can register a listener to be notified of tracker attribution changes. Due to the different sources we consider for attribution, we cannot provide this information synchronously.
Please see our attribution data policies for more information.
With the config instance, add the attribution callback before you start the SDK:
Native App SDK |
AdjustConfig config = new AdjustConfig(this, appToken, environment);
config.setOnAttributionChangedListener(new OnAttributionChangedListener() {
@Override
public void onAttributionChanged(AdjustAttribution attribution) {}
});
Adjust.onCreate(config); |
Web View SDK |
function attributionCallback(attribution) {}
// ...
let adjustConfig = new AdjustConfig(yourAppToken, environment);
adjustConfig.setAttributionCallback(attributionCallback);
Adjust.onCreate(adjustConfig); |
The listener function is called after the SDK receives the final attribution data. Within the listener function, you'll have access to the attribution
parameter. Here is a quick summary of its properties:
trackerToken
the tracker token string of the current attribution.trackerName
the tracker name string of the current attribution.network
the network grouping level string of the current attribution.campaign
the campaign grouping level string of the current attribution.adgroup
the ad group grouping level string of the current attribution.creative
the creative grouping level string of the current attribution.clickLabel
the click label string of the current attribution.adid
the Adjust device identifier string.
Note: This feature is available only in the native SDK v4.18.0 and above.
You can track ad revenue information with Adjust SDK by invoking the following method:
Native App SDK |
Adjust.trackAdRevenue(source, payload); |
Parameters of the method which you need to pass are:
source
-String
object which indicates the source of ad revenue info.payload
-JSONObject
object which contains ad revenue JSON.
Currently we support the below source
parameter values:
AD_REVENUE_MOPUB
- representing MoPub mediation platform (for more information, check integration guide)
You can register a listener to be notified when events or sessions are tracked. There are four listeners: one for tracking successful events, one for tracking failed events, one for tracking successful sessions, and one for tracking failed sessions. Add as many listeners as you need after creating the config object like so:
Native App SDK |
AdjustConfig config = new AdjustConfig(this, appToken, environment);
// Set event success tracking delegate.
config.setOnEventTrackingSucceededListener(new OnEventTrackingSucceededListener() {
@Override
public void onFinishedEventTrackingSucceeded(AdjustEventSuccess eventSuccessResponseData) {
// ...
}
});
// Set event failure tracking delegate.
config.setOnEventTrackingFailedListener(new OnEventTrackingFailedListener() {
@Override
public void onFinishedEventTrackingFailed(AdjustEventFailure eventFailureResponseData) {
// ...
}
});
// Set session success tracking delegate.
config.setOnSessionTrackingSucceededListener(new OnSessionTrackingSucceededListener() {
@Override
public void onFinishedSessionTrackingSucceeded(AdjustSessionSuccess sessionSuccessResponseData) {
// ...
}
});
// Set session failure tracking delegate.
config.setOnSessionTrackingFailedListener(new OnSessionTrackingFailedListener() {
@Override
public void onFinishedSessionTrackingFailed(AdjustSessionFailure sessionFailureResponseData) {
// ...
}
});
Adjust.onCreate(config); |
Web View SDK |
function eventSuccessCallback(eventSuccessResponseData) {}
function eventFailureCallback(eventFailureResponseData) {}
function sessionSuccessCallback(sessionSuccessResponseData) {}
function sessionFailureCallback(sessionFailureResponseData) {}
// ...
let adjustConfig = new AdjustConfig(yourAppToken, environment);
adjustConfig.setEventSuccessCallback(eventSuccessCallback);
adjustConfig.setEventFailureCallback(eventFailureCallback);
adjustConfig.setSessionSuccessCallback(sessionSuccessCallback);
adjustConfig.setSessionFailureCallback(sessionFailureCallback);
Adjust.onCreate(adjustConfig); |
The listener function is called after the SDK tries to send a package to the server. Within the listener function you have access to a response data object specifically for the listener. Here is a quick summary of the success session response data object fields:
message
message string from the server (or the error logged by the SDK).timestamp
timestamp string from the server.adid
a unique string device identifier provided by Adjust.jsonResponse
the JSON object with the reponse from the server.
Both event response data objects contain:
eventToken
the event token string, if the package tracked was an event.callbackId
the custom defined callback ID string set on the event object.
And both event and session failed objects also contain:
willRetry
boolean which indicates whether there will be a later attempt to resend the package.
Like we described in the attribution callback section, this callback is triggered whenever the attribution information changes. Access your user's current attribution information whenever you need it by making a call to the following method of the Adjust
instance:
Native App SDK |
AdjustAttribution attribution = Adjust.getAttribution(); |
Web View SDK |
let attribution = Adjust.getAttribution(); |
Note: You can only make this call using the Adjust SDK v4.11.0 or above.
Note: Current attribution information is only available after our backend tracks the app install and triggers the attribution callback. It is not possible to access a user's attribution value before the SDK has been initialized and the attribution callback has been triggered.
The Adjust SDK offers you the possibility to obtain device identifiers.
Certain services (such as Google Analytics) require you to coordinate advertising IDs and client IDs in order to prevent duplicate reporting.
Native App SDK |
If you need to obtain the Google Advertising ID, there is a restriction; it can only be read in a background thread. If you call the function Adjust.getGoogleAdId(this, new OnDeviceIdsRead() {
@Override
public void onGoogleAdIdRead(String googleAdId) {}
}); |
Web View SDK |
To obtain the device's Google Advertising device identifier, it's necessary to pass a callback function to Adjust.getGoogleAdId(function(googleAdId) {
// ...
}); |
If you need to obtain the Amazon Advertising ID, call the following method on Adjust
instance:
Native App SDK |
String amazonAdId = Adjust.getAmazonAdId(context); |
Web View SDK |
let amazonAdId = Adjust.getAmazonAdId(); |
For each device with your app installed on it, our backend generates a unique Adjust device identifier (known as an adid). In order to obtain this identifier, call the following method on Adjust
instance:
Native App SDK |
String adid = Adjust.getAdid(); |
Web View SDK |
let adid = Adjust.getAdid(); |
Note: You can only make this call in the Adjust SDK in v4.11.0 and above.
Note: Information about the adid is only available after our backend tracks the app instal. It is not possible to access the adid value before the SDK has been initialized and the installation of your app has been successfully tracked.
If you want to use the Adjust SDK to recognize users whose devices came with your app pre-installed, follow these steps:
-
Create a new tracker in your dashboard.
-
Open your app delegate and set the default tracker of your config:
Native App SDK adjustConfig.setDefaultTracker("{TrackerToken}");
Web View SDK adjustConfig.setDefaultTracker('{TrackerToken}');
-
Replace
{TrackerToken}
with the tracker token you created in step one. Please note that the dashboard displays a tracker URL (includinghttp://app.adjust.com/
). In your source code, you should specify only the six or seven-character token and not the entire URL. -
Build and run your app. You should see a line like the following in your LogCat:
Default tracker: 'abc123'
You can put the Adjust SDK in offline mode to suspend transmission to our servers (while retaining tracked data to be sent later). While in offline mode, all information is saved in a file. Please be careful not to trigger too many events while in offline mode.
Activate offline mode by calling setOfflineMode
with the parameter true
.
Native App SDK |
Adjust.setOfflineMode(true); |
Web View SDK |
Adjust.setOfflineMode(true); |
Conversely, you can deactivate offline mode by calling setOfflineMode
with false
. When the Adjust SDK is put back into online mode, all saved information is sent to our servers with the correct time information.
Unlike disabling tracking, this setting is not remembered between sessions. This means the SDK is in online mode whenever it starts, even if the app was terminated in offline mode.
You can disable the Adjust SDK from tracking any activities of the current device by calling setEnabled
with parameter false
. This setting is remembered between sessions.
Native App SDK |
Adjust.setEnabled(false); |
Web View SDK |
Adjust.setEnabled(false); |
You can check to see if the Adjust SDK is currently enabled by calling the function isEnabled
. It is always possible to activatе the Adjust SDK by invoking setEnabled
with the enabled parameter as true
.
If your app makes heavy use of event tracking, you might want to delay some network requests in order to send them in one batch every minute. You can enable event buffering with your config instance:
Native App SDK |
adjustConfig.setEventBufferingEnabled(true); |
Web View SDK |
adjustConfig.setEventBufferingEnabled(true); |
The default behaviour of the Adjust SDK is to pause sending network requests while the app is in the background. You can change this in your config instance:
Native App SDK |
adjustConfig.setSendInBackground(true); |
Web View SDK |
adjustConfig.setSendInBackground(true); |
In accordance with article 17 of the EU's General Data Protection Regulation (GDPR), you can notify Adjust when a user has exercised their right to be forgotten. Calling the following method will instruct the Adjust SDK to communicate the user's choice to be forgotten to the Adjust backend:
Native App SDK |
Adjust.gdprForgetMe(context); |
Web View SDK |
Adjust.gdprForgetMe(); |
Upon receiving this information, Adjust will erase the user's data and the Adjust SDK will stop tracking the user. No requests from this device will be sent to Adjust in the future.
Please note that even when testing, this decision is permanent. It is not reversible.
This error typically occurs when testing installs. Uninstalling and reinstalling the app is not enough to trigger a new install. The servers will determine that the SDK has lost its locally aggregated session data and ignore the erroneous message, given the information available on the servers about the device.
This behavior can be cumbersome during testing, but is necessary in order to have the sandbox behavior match production as much as possible.
You can reset your app's session data for any device directly from the Adjust Dashboard using our Testing Console if you have Editor-level access (or higher) to the app.
Once the device has been correctly forgotten, the Testing Console will return Forgot device
. If the device was already forgotten (or if the values were incorrect) the link will return Advertising ID not found
.
Forgetting the device will not reverse the GDPR forget call.
If your current package gives you access, you can also inspect and forget a device using our Developer API.
If you followed the instructions in the guide, the broadcast receiver should be configured to send the install referrer to our SDK and to our servers.
You can test this by manually triggering a test install referrer. Replace com.your.appid
with your app ID and run the following command with the adb tool that comes with Android Studio:
adb shell am broadcast -a com.android.vending.INSTALL_REFERRER -n com.your.appid/com.adjust.sdk.AdjustReferrerReceiver --es "referrer" "adjust_reftag%3Dabc1234%26tracking_id%3D123456789%26utm_source%3Dnetwork%26utm_medium%3Dbanner%26utm_campaign%3Dcampaign"
If you already use a different broadcast receiver for the INSTALL_REFERRER
intent and followed this guide, replace com.adjust.sdk.AdjustReferrerReceiver
with your broadcast receiver.
You can also remove the -n com.your.appid/com.adjust.sdk.AdjustReferrerReceiver
parameter so that all the apps in the device will receive the INSTALL_REFERRER
intent.
If you set the log level to verbose
, you should be able to see the log from reading the referrer:
V/Adjust: Referrer to parse (adjust_reftag=abc1234&tracking_id=123456789&utm_source=network&utm_medium=banner&utm_campaign=campaign) from reftag
And a click package added to the SDK's package handler:
V/Adjust: Path: /sdk_click
ClientSdk: android4.6.0
Parameters:
app_token abc123abc123
click_time yyyy-MM-dd'T'HH:mm:ss.SSS'Z'Z
created_at yyyy-MM-dd'T'HH:mm:ss.SSS'Z'Z
environment sandbox
gps_adid 12345678-0abc-de12-3456-7890abcdef12
needs_attribution_data 1
referrer adjust_reftag=abc1234&tracking_id=123456789&utm_source=network&utm_medium=banner&utm_campaign=campaign
reftag abc1234
source reftag
tracking_enabled 1
If you perform this test before launching the app, you won't see the package being sent. The package will be sent once the app is launched.
Important: We encourage you to not use the adb
tool for testing this particular feature. In order to test your full referrer content (in case you have multiple parameters separated with &
), with adb
you will need to encode that content in order to get it into your broadcast receiver. If you don't encode it, adb
will cut your referrer after the first &
sign and deliver wrong content to your broadcast receiver.
If you would like to see how your app receives an unencoded referrer value, we would encourage you to try our example app and alter the content being passed so that it fires with intent inside of the onFireIntentClick
method inside of the MainActivity.java
file:
public void onFireIntentClick(View v) {
Intent intent = new Intent("com.android.vending.INSTALL_REFERRER");
intent.setPackage("com.adjust.examples");
intent.putExtra("referrer", "utm_source=test&utm_medium=test&utm_term=test&utm_content=test&utm_campaign=test");
sendBroadcast(intent);
}
Feel free to alter the second parameter of putExtra
method with content of your choice.
Triggering an event at this time might not do what you expect. Here's why:
The onCreate
method on the global Application
class is called not only at application launch, but also when a system or application event is captured by the app.
Our SDK is prepared for initialization at this time, but has not actually started. This will only happen when an activity takes place, i.e., when a user actually launches the app.
Triggering an event at this time would start the Adjust SDK and send the events, even though the app was not launched by the user - at a time that depends on factors external to the app.
Triggering events at application launch will thus result in inaccuracies in the number of installs and sessions tracked.
If you want to trigger an event after the install, use the attribution callback.
If you want to trigger an event when the app is launched, use the onCreate
method for the given activity.
The Adjust SDK is licensed under the MIT License.
Copyright (c) 2012-2019 Adjust GmbH, http://www.adjust.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.