Android SDK: Advanced Options

Singular Android SDK
Download
Singular Android SDK version 9.2.10
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

 

Uninstall Tracking

To enable uninstall tracking for your Android app, first configure the app in the Singular platform as detailed in Setting Up Uninstall Tracking. Then follow the instructions below.

Note: Google deprecated the GCM APIs in April 2018. Use FCM for uninstall tracking.

Enabling Uninstall Tracking Using Firebase Cloud Messaging (FCM)

1. Integrate with FCM:

To track uninstalls, you can use the services of the Firebase Cloud Messaging (FCM) platform. If you are not already using FCM follow Google's instructions on how to Set up a Firebase Cloud Messaging client app on Android.

GCM Requirements ( source )

FCM clients require devices running Android 4.1 or higher that also have the Google Play Store app installed, or an emulator running Android 4.1 with Google APIs. Note that you are not limited to deploying your Android apps through the Google Play Store.

Users/devices who are not running on supported versions of Android will not be available for Singular uninstall tracking.

2. Update the AndroidManifest.xml File:

Update your AndroidManifest.xml file to add the necessary intent filter for your app (replace MyFirebaseMessagingService with your class that implements the Firebase Service):

<service android:name=".java.MyFirebaseMessagingService"
android:exported="false">
    <intent-filter>
        action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

3. Register and Send the FCM Device Token:

Finally, set the FCM device token after your SingularConfig is initialized in OnCreate(), as follows:

Singular.setFCMDeviceToken(String fcmDeviceToken);

Collecting the Install Referrer on Older Devices

Note: Google is deprecating the install_referrer intent broadcast. See: Still Using InstallBroadcast? Switch to the Play Referrer API by March 1, 2020

The install referrer is Singular's most accurate tool to determine attribution, in addition to helping Singular detect and analyze fraud attempts. It is an identifier provided by the Google Play Store that points to the ad that the user clicked on before installing the app.

On devices that have the latest version of the Google Play Store, the Singular SDK collects the install referrer value automatically (since Singular is integrated with the latest Google Play Referrer API).

To collect the install referrer on older devices:

If you have an existing install referrer receiver:

Chances are your app already has a BroadcastReceiver that receives the INSTALL_REFERRER from Android.

If so, just go into the BroadcastReceiver's onReceive method and add the following line:

new SingularInstallReceiver().onReceive(context, intent);

For example, if your existing receiver is called MyCustomInstallReceiver, it should look as follows:

public class MyCustomInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Pass install referrer information on to Singular
        new SingularInstallReceiver().onReceive(context, intent);
        // ...
    }
}

If there is no other install referrer receiver:

If you don't have any install referrer receiver in your app, you can let the Singular SDK register the only receiver simply by adding the following to your <application> tag in your manifest file:

<receiver android:exported="true" android:name="com.singular.sdk.SingularInstallReceiver">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

Managing Sessions

For Android API 14 (Ice Cream Sandwich) and above, the Singular SDK can handle session management automatically. If your app's minSdkVersion is 14 or higher, no additional configuration is required for session management.

Modifying the Session Timeout

By default, if the app runs in the background for 60 seconds or more before returning to the foreground, the SDK registers a new session.

To change the timeout value, use withSessionTimeoutInSec(<timeout in seconds>) in SingularConfig before initializing the SDK.

For example:

// Set the session timeout to 120 seconds
SingularConfig config = new SingularConfig(apiKey, secretKey)
.withSessionTimeoutInSec(120); 

Manual Session Management

If your app's minSdkVersion is below 14, you need to manage sessions manually by calling the Singular's SDK two session-handling methods, onActivityPaused and onActivityResumed, from each of your activities.

Note: If you have a custom common base activity class from which all other activities are derived, you can place these calls to onActivityResumed and onActivityPaused in the common activity's "onResume and onPause methods.
Singular.onActivityResumed Method
Description Call this method inside the activity's onResume method to manage the Singular session.
Signature public static void onActivityResumed()
Usage Example
@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... //other code if any
}
Singular.onActivityPaused Method
Description Call this method inside the activity's onPause method to manage the Singular session.
Signature public static void onActivityPaused()
Usage Example
@Override
protected void onPause() {
    super.onPause();
    Singular.onActivityPaused();
    .... //other code if any
}

Using the JavaScript Interface

Singular provides a JavaScript interface that you can use in order to call Singular from within javaScript code in your app.

For example, if you set up the JavaScript interface, you can send events to Singular from JavaScript code as follows:

SingularInterface.event('event');
SingularInterface.event('test',
JSON.stringify({"a1":"bar", "a2":"boo", "a3":"baz"}));

The interface supports the following SDK methods:

  • setCustomUserID
  • unsetCustomUserID
  • event
  • revenue

Enabling the JavaScript Interface

To enable the JavaScript interface, add the following lines of code to your main activity, where "myWebView" is the name of your webview.

SingularJSInterface singularJSInterfaceInstance = new SingularJSInterface(this);
singularJSInterfaceInstance.setWebViewId(R.id.webview);
myWebView.addjavascriptInterface(singularJSInterfaceInstance, "SingularInterface");
Notes:
  • If you have more than one webview, do this for each one.
  • We recommend placing the code in the onCreate method of your application.

Your onCreate method may look like this:

public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    WebView myWebView = (WebView) this.findViewById(R.id.webview);
    WebSettings webSettings = myWebView.getSettings();
    webSettings.setjavaScriptEnabled(true);
    myWebView.loadUrl("file:///android_asset/index.html");

    SingularConfig config = new SingularConfig(apiKey, secret);
    Singular.init(this, config);
    SingularJSInterface singularJSInterfaceInstance = 
        new SingularJSInterface(this);
    singularJSInterfaceInstance.setWebViewId(R.id.webview);
    myWebView.addjavascriptInterface(singularJSInterfaceInstance,
        "SingularInterface");
}

Collecting the IMEI Number

If your app is offered in countries that do not use Google Play, devices do not have a Google Advertising ID. In this case, you may want to collect the device IMEI (International Mobile Equipment Identity) instead.

Note: If you use Google Play Services, you should not collect the IMEI number because it's a violation of the Google Play service agreement.

To collect the IMEI number:

  1. Add the android.permission.READ_PHONE_STATE permission to the app's AndroidManifest.xml file:

    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
  2. Add code like the following to fetch the device's IMEI number:

    TelephonyManager telephonyManager = (TelephonyManager)getSystemService(Context.TELEPHONY_SERVICE);
    
    String imei = null;
    
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        imei = telephonyManager.getImei();
    } else {
        imei = telephonyManager.getDeviceId();
    }

To send the IMEI number to Singular, use one of the following methods:

  • Recommended: Set the IMEI number in SingularConfig using withIMEI before you initialize the Singular SDK, as in the following example. This makes the IMEI number available to Singular from the very first session.

    SingularConfig config = new SingularConfig("apikey","secret").withIMEI("537769845792516");
    Singular.init(context, config);
  • To set the IMEI number at any point in the code after the SDK initialization, call setIMEI.
Singular.setIMEI Method
Description Send the device's IMEI number to Singular.
Signature public void setIMEI(string IMEIString)
Usage Example
Singular.setIMEI(IMEIString);

GDPR Compliance

The Singular SDK provides several methods to help you comply with GDPR policies and let Singular know about user consent or non-consent for tracking.

Singular.trackingOptIn Method
Description Notify Singular of user consent (opt-in) for tracking.
Usage Example
Singular.trackingOptIn();
Singular.trackingUnder13 Method
Description Notify Singular that a user is a minor (under 13).
Usage Example
Singular.trackingUnder13();
Singular.stopAllTracking Method
Description

Stop all tracking activities for this user on this app.

Note: Calling this method effectively disables the SDK, even after the app restarts (the state is persistent)! The only way to re-enable tracking is by calling resumeAllTracking().
Usage Example
Singular.stopAllTracking();
Singular.resumeAllTracking Method
Description Resume tracking for this user on this app.
Usage Example
Singular.resumeAllTracking();
Singular.isAllTrackingStopped Method
Description Check the tracking status for this user on this app. Returns true if tracking has been stopped using StopAllTracking() and not resumed.
Usage Example
Singular.isAllTrackingStopped();

 

Was this article helpful?
0 out of 0 found this helpful