Skip to content

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 {
    implementation 'com.plotprojects:plot-android:3.16.0'
    implementation 'androidx.core:core:1.1.0'
    implementation 'androidx.fragment:fragment:1.1.0'
    implementation 'androidx.work:work-runtime:2.7.1'
    implementation 'androidx.work:work-gcm:2.7.1'
    implementation 'androidx.swiperefreshlayout:swiperefreshlayout:1.0.0'
    implementation 'com.google.android.gms:play-services-location:19.0.1'
    implementation 'com.google.android.gms:play-services-nearby:18.0.2'
    implementation 'com.google.android.gms:play-services-awareness:19.0.1'

    implementation platform('com.google.firebase:firebase-bom:28.3.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.

In case you wish to enable our alt beacon plugin to monitor beacons please incluse it in the dependencies, in case not, feel free to ignore this.

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

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

android {
    // other android specific gradle configuration

    defaultConfig {
        applicationId "com.myplotapplication"
        minSdkVersion 24
        targetSdkVersion 31
        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"
}

Note

If you are planning to use AltBeacon instead of the default google nearby to monitor beacons, you need to add the following configuration items:

"enableAltBeaconMonitoring": true,
"enableAltBeaconForegroundService": true

You also need to add the add AltBeacon dependency to your app as explained in step 2.

AltBeacon library is useful when distance to the beacon is an essential part of your application and gives you more control over the background scanning of beacons. 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 permenent notification. For most cases, the default beacon monitoring works fine.

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

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