Android SDK: Basic Integration

Singular Android SDK
Download
Singular Android SDK version 12.1.2 (see Change Log)
Compatibility

Android 4.0.1 (Ice Cream Sandwich) and higher

  • The SDK uses the device's Android Advertising ID for devices that use Play Store version 4. For older devices, the SDK uses the Android ID.
  • The latest version of the SDK has not been tested with Android versions older than 4.0.1.
Sample App Review our sample app for an example of a complete SDK integration based on best practices.
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Advanced Options

 

Adding the SDK to Your Project

To add the SDK using Gradle:

  1. Add the Singular SDK repository to the project/build.gradle file:

    repositories {
            mavenCentral()
    maven { url 'https://maven.singular.net/' } }
  2. Add the Singular library to the dependencies list in app/build.gradle:

    dependencies {
        implementation 'com.google.android.gms:play-services:6.5.87'
        implementation fileTree(dir: 'libs', include: ['*.jar'])
        implementation 'com.android.support:appcompat-v7:21.0.3'
        ...
        implementation 'com.singular.sdk:singular_sdk:12.1.1'
        ...
    }
  3. If you have disabled transitive dependencies for the Singular SDK, add 'com.android.installreferrer:installreferrer:2.2' and 'com.google.android.gms:play-services-appset:16.0.0' to your app's build.gradle.

  4. If your app doesn't implement Google Play Services API 17.0.0 or higher, add the following dependency to the app's build.gradle file:

    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'

Note: Users of Gradle 1.x-2.x should use "compile" instead of "implementation" to add dependencies.

To add the SDK if you don't use Gradle:

Downloading the SDK Manually
  1. Download the SDK from the link at the top of the page.
  2. Unzip the SDK package and add Singular.aar into the libs folder in your Android project's libs directory. If it doesn't exist, create a directory called libs in your project folder (usually at <project>/app/libs).
Adding the SDK Using Maven

Add our maven repository to your project's pom.xml:

<project ...>
<repositories>
    <repository>
      <id>singular.net</id>
      <url>http://maven.singular.net/</url>
    </repository>
 </repositories>
</project>

Add the dependency:

<dependency>
    <groupId>com.singular.sdk</groupId>
    <artifactId>singular_sdk</artifactId>
    <version>12.0.2</version>
</dependency>
Adding the SDK Using Eclipse

You can use the Eclipse AAR plugin: gradle-eclipse-aar-plugin

If you don't want to use the plugin, follow these steps:

  1. Unzip singular_sdk-12.0.2.aar.
  2. Rename classes.jar to singular_sdk-12.0.2.jar (this is the main SDK jar).
  3. Add the 'com.android.installreferrer:installreferrer:2.2' library to your project in any way you prefer.
  4. Copy the BIND_GET_INSTALL_REFERRER_SERVICE permission from the AndroidManifest.xml contained in the AAR to your AndroidManifest.xml
  5. copy the CHECK_LICENSE permissions from the AndroidManifest.xml contained in the AAR to your AndroidManifest.xml
Adding the SDK Using Proguard

Add the following lines of code to your proguard.config file:

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Uncomment this line in case your are calling the 'revenue' function using the Google billing library
#-keep public class com.android.billingclient.** { *; }

Setting Up Prerequisites

Adding Permissions

Add these permissions under the <manifest> tag in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />

If your app build is targeting Android 12/API level 31 or higher, add permissions to access the Google Advertising ID:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Note: If you're integrating the Kids SDK, you shouldn't add this permission.

Caution: If your app has the android.permission.GET_TASKS permission, the app may be initialized before it is actually opened by the user. This may initialize the Singular SDK and cause discrepancies in install time. To prevent the problem, remove the permission if it's not needed, or move the Singular SDK initialization call somewhere else in the code, making sure it is called only after the user opens the app for the first time.

Importing the Singular Library

To import the Singular library, add the following code:

import com.singular.sdk.*;

Initializing the Singular SDK

Note: Remember to remain compliant with the various privacy laws enacted in regions where doing business, including but not limited to GDPR, CCPA and COPPA when implementing the Singular SDKs. For more information, see SDK Opt-In and Opt-Out Practices.

The SDK initialization code should be called every time your app is opened. It is a prerequisite to all Singular attribution functionality, and it also sends a new user session to Singular. Sessions are used to calculate user retention.

1. Constructing the SingularConfig Object

Before you can initialize the SDK, you have to create a SingularConfig object. This object will contain:

  1. Your SDK Key and SDK Secret (to retrieve them, log into your Singular account and go to Developer Tools > SDK Keys).
  2. Optionally, any SDK preferences you may want to set.

To create a basic SingularConfig object use this code:

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")

However, you will probably want to add settings to enable various capabilities offered by Singular.

To add settings, you will use the SingularConfig object's ".with" methods. For example:

// Configure the SDK to pass the user ID to Singular
// and set the session timeout to 120 seconds
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
    .withCustomUserId(UserId)
    .withSessionTimeoutInSec(120)

Read the rest of this SDK guide to learn about the various settings available.

SingularConfig Method Reference

Here are all the available ".with" methods.

Method

Description

Learn More

.withCustomUserId(String customId)

Send the user ID to Singular

Setting the User ID

.withSingularLink(getIntent(), SingularLinkHandler handler)

Enable deep linking with Singular Links

Implementing Deep Links

.withDDLTimeoutInSec (long timeout)

Set the length of time Singular searches for a deferred deep link when the app is first opened

.withDDLHandler (DeferredDeepLinkHandler handler)

Enable deep linking with legacy tracking links (instead of the newer Singular Links)

.withOpenURI (URI openURI)

Fetch the URI from the intent (to process deep links if the app is opened through a link that doesn't originate from Singular)

 

.withGlobalProperty(String key, String value, boolean overrideExisting)

Set a global property to a given value. The key and value will be sent to Singular with any event/session sent from the app.

Adding Global Properties

.withSessionTimeoutInSec (long timeout)

Set the session timeout

Modify Session Timeout

.withFCMDeviceToken(String token)

Sets the FCM token to be sent on the first session

Uninstall Tracking 

.withLoggingEnabled ()

Enable logging

 

.withLogLevel (int level)

Configure the logging level (default is Log.ERROR)

 

2. Initializing Singular

After creating the SingularConfig object, initialize Singular using the init method, passing the config object.

We recommend calling init in the onCreate of the main activity as well as any activity that will be opened directly by a deep link.

Notes:

  • The init method can be called at every point in the app but must get called before any event is reported.
  • You have to initialize Singular inside any activity that will be opened by a deep link (see Implementing deep links). Therefore, we don't recommend initializing Singular in the application's onCreate. If Singular is initialized on the application level and then again inside an activity, it will cause duplicate sessions in the Singular database.
Singular.init Method
Description Initialize the SDK with configuration options set in the SingularConfig object.
Signature

public static boolean init(Context context, SingularConfig config)

Note:

  • From the application class, you can pass this or getApplicationContext() as the context.
  • To get the application context from inside an activity, call currentActivity.getApplicationContext().
Usage Example
@Override
protected void onCreate(Bundle savedInstanceState) {
    ...
    Singular.init(context, config);
    ...
}

Optional: Setting the User ID

The Singular SDK can send a user ID from your app to Singular. This can be a username, email address, randomly generated string, or whichever identifier you use as a user ID.

Singular uses the user ID in user-level data exports as well as internal BI postbacks (if you configure such postbacks).

There are two ways to send the user ID to Singular:

  • Recommended: If you know the user ID when the app opens, set the user ID in the SingularConfig object before initializing the SDK. This makes the user ID available to Singular from the very first session.

    SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
        .withCustomUserId("custom_user_id");
    Singular.init(context, config);
  • Alternatively, you can call the setCustomUserId method at any point in the run.

The user ID persists until you unset it using unsetCustomUserId or until the app is uninstalled. Closing/restarting the app does not unset the user ID.

In many cases, you will want to call setCustomUserId when the user logs in to your service, and call unsetCustomUserId if the user logs out.

Singular.setCustomUserID Method
Description Send the user ID to Singular.
Signature public void setCustomUserId(string customUserId)
Usage Example
Singular.setCustomUserId("custom_user_id");
Singular.unsetCustomUserID Method
Description Unset the user ID that has been sent to Singular.
Signature public void unsetCustomUserId()
Usage Example
Singular.unsetCustomUserId();