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>

Manually 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("SDK KEY", "SDK SECRET")
.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.

@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... //other code if any
}

@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:

Event Example

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

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");

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("SDK KEY", "SDK SECRET");
    Singular.init(this, config);
    SingularJSInterface singularJSInterfaceInstance = 
        new SingularJSInterface(this);
    singularJSInterfaceInstance.setWebViewId(R.id.webview);
    myWebView.addjavascriptInterface(singularJSInterfaceInstance,
        "SingularInterface");
}

Collecting the OAID (Open Advertising ID)

In countries that do not use Google Play, Android devices do not have a Google Advertising ID (GAID, also called AIFA in Singular). Instead, the devices may offer an identifier called OAID (Open Advertising Identifier) that can be used to track sessions and events coming from the device.

OAID is currently offered on devices by Huawei and by brands that belong to the Mobile Security Alliance (MSA).

For your app to collect the OAID, you first have to integrate the MSA SDK and Huawei OAID SDK. You need to integrate both SDKs to be able to collect the OAID on all the platforms that offer it.

Then, to tell the Singular SDK to use OAID for tracking, add a call to withOAIDCollection in the config object before initializing Singular.

SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
    .withOAIDCollection();
Singular.init(context, config);

The Singular SDK will automatically detect if the device has an OAID as well as which OAID SDK should be used to collect the identifier.

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:

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

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

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("SDK KEY","SDK 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(IMEIString);