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()
        mavenCentral()

        // 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 {
    implementation 'com.plotprojects:plot-android:3.19.1'
    implementation 'androidx.work:work-runtime:2.7.1'
    implementation 'androidx.work:work-gcm:2.7.1'
    implementation 'com.google.android.gms:play-services-location:20.0.0'
    implementation 'com.google.android.gms:play-services-nearby:18.3.0'
    implementation 'com.google.android.gms:play-services-awareness:19.0.1'

    implementation platform('com.google.firebase:firebase-bom:30.4.0')
    implementation 'com.google.firebase:firebase-core'
    implementation 'com.google.firebase:firebase-messaging'
}

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.

Optional

In case you are planning to use beacon monitoring you need to include the following dependency in your build.gradle file:

dependencies {
    implementation 'org.altbeacon:android-beacon-library:2.19.4'
}

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 supports sdk version 31.

android {
    // other android specific gradle configuration

    defaultConfig {
        applicationId "com.myplotapplication"
        minSdkVersion 24
        targetSdkVersion 33
        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,
    "enableCombinedMonitoring": "false"
}

Optional

In case you are planning to use beacon monitoring, you can enable a foreground service as in the example above to force more aggressive BLE scanning but it also causes the app to display a permanent notification.

"enableAltBeaconForegroundService": true

An example of such a config file can be found on our dashboard, as well as the public token you will have to use.

Step 5: Request location permissions

In order to receive location data, your app needs to request location permissions. Google play recommends requesting location permissions when the user uses a feature that requires location.

You need to request the following permissions in order for your app to be able to receive location updates:

android.permission.ACCESS_COARSE_LOCATION
android.permission.ACCESS_FINE_LOCATION
android.permission.ACCESS_BACKGROUND_LOCATION

Note

In case you are planning to use beacons monitoring and targetting Android 12 or above, you will also need to request the Bluetooth scan permission:

android.permission.BLUETOOTH_SCAN

In addition to the following permission in case you are targetting versions before Android 12:

android.permission.BLUETOOTH

For more information about how to request location permissions, please refer to this guide. For information about best practices, please refer to the this guide.

Step 6: Request notification permission

In order to send notifications on Android 13 or later, you need to request the permission to send notifications to the user. Google play recommends requesting notification permission when the user uses a feature that requires it.

You need to request the following permission in order for your app to be able to send notifications to the user:

android.permission.POST_NOTIFICATIONS

For more information about how to request notification permissions, please refer to this guide. For information about best practices, please refer to the this guide.

Step 7: Almost done!

Call Plot.init(Activity) 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.

Recommended: Set User ID

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 using Google Play Services Advertising ID Client, add the following lines to the main activity:

import com.plotprojects.retail.android.Plot;
import com.google.android.gms.ads.identifier.AdvertisingIdClient;
import com.google.common.util.concurrent.Futures;

public class MyActivity extends Activity {

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

        Plot.init(this);
        determineAdvertisingInfo();
    }

    private void determineAdvertisingInfo() {
        if (AdvertisingIdClient.isAdvertisingIdProviderAvailable()) {
            ListenableFuture<AdvertisingIdInfo> advertisingIdInfoListenableFuture =
                    AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext());
            Futures.addCallback(advertisingIdInfoListenableFuture,
                    new FutureCallback<AdvertisingIdInfo>() {
                        @Override
                        public void onSuccess(AdvertisingIdInfo adInfo) {
                            String advertisingId = adInfo.getId();
                            String providerPackageName =
                                    adInfo.getProviderPackageName();
                            boolean limitAdTracking =
                                    adInfo.isLimitTrackingEnabled();

                            Plot.setAdvertisingId(advertisingId, limitAdTracking);

                        }
                        // Any exceptions thrown by getAdvertisingIdInfo()
                        // cause this method to get called.
                        @Override
                        public void onFailure(Throwable throwable) {
                            Log.e("MY_APP_TAG",
                                    "Failed to connect to Advertising ID provider.");
                            // Try to connect to the Advertising ID provider again,
                            // or fall back to an ads solution that doesn't require
                            // using the Advertising ID library.
                        }
                    });
        } else {
            // The Advertising ID client library is unavailable. Use a different
            // library to perform any required ads use cases.
        }
    }
}

Read more about using the Advertising ID at Advertising identifier - How to get started or check Android developers guide for more details about requesting Advertising identifier.

Step 8: 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.

Step 9 (optional): Huawei support

If you are planning to support new huawei devices without Google play services, add the following dependency

dependencies {
    implementation 'com.plotprojects:plot-android-huawei:1.0.0'
}

Warning

Google Play Store would either reject or later remove apps that support huawei devices. If you are planning to support them, consider creating a different flavor of your app with Huawei support and submit that variant to Huawei app gallery connect store.