Basic Integration

New: Video Guide

Watch this video for a detailed view of the integration process. We recommend that you use both the video and the written guide below.

Before You Begin: SDK Prerequisites

Follow the steps in Integrating a Singular SDK: Planning and Prerequisites.

These steps are prerequisites for any Singular SDK integration.


Install the SDK

Adding the SDK Using Gradle

Note: Starting with Gradle 7, Android suggests using centralized repository declarations in settings.gradle over project or module level build.gradle declarations.

  1. Add the Singular SDK repository to the settings.gradle file:

    setting.gradle
    dependencyResolutionManagement {
         repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
         repositories {
              google()
              mavenCentral()
              maven{ url = uri("https://maven.singular.net/") }
         }
    }

    OR in older Gradle versions, Add the Singular SDK repository to the project/build.gradle file:

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

    app/build.gradle
    dependencies {
        ...
        implementation 'com.google.android.gms:play-services:6.5.87'
        implementation 'com.singular.sdk:singular_sdk:12.7.1'
        ...
    }

    Additionally, add the following to support the Samsung Galaxy Store's install referrer if your app is distributed through the Samsung Galaxy Store:

    app/build.gradle
    dependencies {
         ...
         implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
         ...
    }
  3. If you have disabled transitive dependencies for the Singular SDK, add the following to your app/build.gradle:

    app/build.gradle
    dependencies {
        ...
        implementation 'com.android.installreferrer:installreferrer:2.2'
        implementation 'com.google.android.gms:play-services-appset:16.0.0'
        ...
    }
     
  4. If your app doesn't implement Google Play Services API 17.0.0 or higher, add the following dependency to the app/build.gradle file:

    app/build.gradle
    dependencies {
         ...
         implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'
         ...
    }

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

Adding the SDK Without 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 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:

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.7.1</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.7.1.aar.
  2. Rename classes.jar to singular_sdk-12.7.1.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

Requirements if using Proguard

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

proguard.config
-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.** { *; }

Adding Required Permissions

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

AndroidManifest.xml
<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" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
Exclude the com.google.android.gms.permission.AD_ID permission if you're integrating the Kids SDK.

To support Samsung Galaxy Store's install referrer add the following:

AndroidManifest.xml
<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

Integrate the SDK

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

Importing the Singular Library

To import the Singular library, add the following import to your MainActivity file:

Java (MainActivity.java) Kotlin (MainActivity.kt)
import com.singular.sdk.*;

Initializing the Singular SDK

Initializing the Singular SDK with a Private Function

To enable session tracking and attribution, the Singular SDK must be initialized each time your app launches. We recommend creating a private method, initSingularSDK(), and calling it from your MainActivity’s onCreate() method.

Follow these steps:

  1. Add the Function: Place the following method inside your MainActivity class (or any entry-point Activity).
  2. Insert Credentials: Replace "SDK KEY" and "SDK SECRET" with your Singular SDK key and secret from your Singular dashboard.
  3. Update the SingularConfig object: Before initializing the SDK, you must create a SingularConfig object. Optionally, any SDK preferences you may want to set should be set here. Use the SingularConfig Method Reference below to see the options:

    SingularConfig Method Reference: See all available ".with" options

    The table below lists all the available ".with" methods for the SingularConfig object to add options and features to your app.

    You will find details about each feature in the sections below or under Advanced Options.

    Method

    Description

    .withFacebookAppId(String facebookAppID)

    Configure the Facebook App ID. Required for "Meta Install Referrer" attribution.

    See "Where can I find an app's Facebook App ID?"

    .withCustomUserId(String customId)

    Send the user ID to Singular.

    .withSingularLink(getIntent(), SingularLinkHandler handler)

    Enable deep linking with Singular Links.

    .withDDLTimeoutInSec (long timeout)

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

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

    .withSessionTimeoutInSec (long timeout)

    Set the session timeout.

    .withFCMDeviceToken(String token)

    Sets the FCM token to be sent on the first session.

    .withLoggingEnabled ()

    Enable logging.

    .withLogLevel (int level)

    Configure the logging level (default is Log.ERROR).

  4. Call the Function: Invoke initSingularSDK() in onCreate() after UI setup but before logging events.

Here’s the basic implementation:

Java - MainActivity Kotlin - MainActivity
private void initSingularSDK() {
    // Configure Singular with SDK key and secret
    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

    try {
        Singular.init(getApplicationContext(), config);
        Log.d("Singular", "SDK initialized successfully");
    } catch (Exception e) {
        Log.e("Singular", "SDK initialization failed: " + e.getMessage());
    }
}

Example Usage in MainActivity

Java - MainActivity Kotlin - MainActivity
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Initialize Singular SDK
    initSingularSDK();

    // Proceed with your app setup (e.g., UI initialization)
}

Key Details

  • Placement: Add this method in your MainActivity, not the Application class, to ensure proper session tracking.
  • Error Handling: The try-catch block logs initialization errors (e.g., invalid credentials) without crashing your app.
  • Deep Linking (Optional): To handle deep links (e.g., URLs that launch your app), see our Supporting Deep Links article for the extended setup.
  • Supporting META Install Referrer Attribution: Add the config.withFacebookAppId("FacebookAppID") configuration option to enable "Meta Install Referrer" attribution.

Pro Tip: If your app supports multiple entry points (e.g., deep links), ensure initSingularSDK() is called in each relevant Activity’s onCreate() to guarantee consistent behavior.