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