Android integration guide

Note

When updating from an older version of Plot, make sure no old references to the Plot Projects plugin are in the AndroidManifest. No need to define services of Plot Projects plugin yourself. You do need to register the notification filter and handler yourself when you have one.

To integrate Plot Projects Android Plugin, a few steps have to be performed. This guide starts from a blank activity (How to create a blank activity) and is designed for Android Studio 3.2.1 with Gradle 4.6. Existing projects can follow this but additional configuration may be required.

Step 1: Integrating the Plot Projects Maven repository

Previously, you had to download and add the plugin manually by going into the dashboard and downloading the plugin under the "Developer Tools" page, even though this is still possible, we automated this process by creating a Maven repository that allows you to include our plugin with ease. This guide only explains how to use the Maven repository.

To allow the Plot Projects Android plugin to be found, add the Plot Projects Maven repository to your build.gradle:

allprojects {
    repositories {
        google()
        jcenter()

        // allow gradle to find the Plot Projects Plugin
        maven {
            url 'https://maven-repo.plotprojects.com'
        }
    }
}

Step 2: Add Plot Projects Android plugin

Add the Plot Projects Android plugin as a dependency in your app/build.gradle:

Select plugin version: Stable

dependencies {
    // other dependencies

    // use compile instead of implementation when using Android Studio 2.x
    implementation 'com.plotprojects:plot-android:3.13.0'
    implementation 'androidx.core:core:1.1.0'
    implementation 'androidx.fragment:fragment:1.1.0'
    implementation 'androidx.work:work-runtime:2.2.0'
    implementation 'androidx.work:work-gcm:2.2.0'
    implementation 'androidx.swiperefreshlayout:swiperefreshlayout:1.0.0'
    implementation 'com.google.android.gms:play-services-location:17.0.0'
    implementation 'com.google.android.gms:play-services-nearby:17.0.0'
    implementation 'com.google.firebase:firebase-core:17.2.1'
    implementation 'com.google.firebase:firebase-messaging:20.0.1'
    implementation 'com.google.android.gms:play-services-awareness:17.1.0'
}

Note

The dependencies com.google.android.gms:play-services-gcm and com.firebase:firebase-jobdispatcher are incompatible with each other. If your app requires firebase-jobdispatcher, you have to use com.firebase:firebase-jobdispatcher-with-gcm-dep instead. It should be a drop-in replacement. For more information about build dependencies in Gradle, refer to the official Android Developer documentation on build dependencies

You can find all versions of the Android Plugin at our download page.

Step 3: Set minimum supported Android version

The Plot Projects Android plugin supports only Android 4.1 (Jelly Bean) and up. Set the minSdkVersion version to at least 16 in your app/build.gradle

This version requires the targetSdkVersion to be at least 29.

android {
    // other android specific gradle configuration

    defaultConfig {
        applicationId "com.myplotapplication"
        minSdkVersion 16
        targetSdkVersion 29
        versionCode 1
        versionName "1.0"
    }   
}

Step 4: Define configuration file

Plot uses a configuration file which you have to define as assets/plotconfig.json. When no assets folder is available, you can create one in Android Studio by right clicking on your project, in the Project tool window, and then selecting New > Folder > Assets Folder.

{
    "publicToken": "REPLACE_ME",
    "enableOnFirstRun": true,
    "debug": true,
    "showOnGoingNotification": "during_network_request",
    "enableCombinedMonitoring": "false"
}

Note

Starting from version 3.3.0, you can use our ongoing notification feature. By default, the plugin enables this feature. When the plugin connects with our services while the app is in the background, it shows a temporary notification. The notification hides again after the update is complete. By showing the notification, it ensures the plugin reliably loads the campaigns and sends events back to us. If you didn't want to see this notification during an update, you could set this option in this configuration file.

An example of such a config file can be found on our dashboard, as well as the public token you will have to use. To hide ongoing notification, change the value of showOnGoingNotification to "never".

Step 5: Almost done!

Call Plot.init(context) to initialize the plugin from your main Activity.

When calling init from an activity, you can use the this keyword as the first parameter.

import com.plotprojects.retail.android.Plot;

public class MyActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // code of your activity

        Plot.init(this); // add this line initialize the Plot Plugin
    }
}

You are now ready to receive your first notification. Need more help during testing, look at the test guide.

By default, the Plot Plugin uses a unique identifier per installation to connect the data generated by each device. We highly recommended setting your own user_id in the Plot Plugin in addition to ease the integration with your own tools.

To set your own User ID, set a segmentation property key user_id and value <Your User ID>. Following the previous step, add the following line to the activity:

import com.plotprojects.retail.android.Plot;

public class MyActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // code of your activity

        Plot.init(this);
        Plot.setStringSegmentationProperty("user_id", <Your User Id>);
    }
}

Read about why to use a custom User ID and more in User ID - How to get started.

Optional: Set Advertising ID

To set the Advertising ID in the Plot Plugin, Use Google Play Services Advertising ID Client. Following the previous step, add the following lines to the activity:

import com.plotprojects.retail.android.Plot;
import com.google.android.gms.ads.identifier.AdvertisingIdClient;
import com.google.android.gms.common.GooglePlayServicesNotAvailableException;
import com.google.android.gms.common.GooglePlayServicesRepairableException;

public class MyActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // code of your activity

        Plot.init(this);
        new SetAdvertisingIdTask().execute(getApplicationContext());
    }

    private static class SetAdvertisingIdTask extends AsyncTask {
        @Override
        protected Void doInBackground(Context... contexts) {
            if (contexts.length == 0) {
                return null;
            }
            Context context = contexts[0];
            try {
                AdvertisingIdClient.Info adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context);
                String advertisingId = adInfo.getId();
                boolean limitAdTracking = adInfo.isLimitAdTrackingEnabled();
                Plot.setAdvertisingId(advertisingId, limitAdTracking);
            } catch (IOException e) {
                // Unrecoverable error connecting to Google Play services (e.g.,
                // the old version of the service does not support getting AdvertisingId).
            } catch (GooglePlayServicesRepairableException e) {
                // Encountered a recoverable error connecting to Google Play services.
            } catch (GooglePlayServicesNotAvailableException e) {
                // Google Play services is not available entirely.
            }
            return null;
        }
    }
}

Read more about using the Advertising ID at Advertising identifier - How to get started

Step 6: Test

If the integration was successful, look at the testing section of the documentation for more details. In case you had issues integrating our SDK, look into our troubleshooting section for help.