This document provides an overview of how to integrate, set-up and start tracking events using the Android SDK.
Use any of these methods below to integrate the SDK. The latest stable release for the Android SDK, GCM version is 1.1.7 & FCM version is 2.0.1. Please make sure to use this in your build.gradle file.
SDK Releases
Always check the github releases for the latest version of the sdk.
Latest version of Android SDK:
FCM: v2.0.1)
GCM: v1.1.7 (soon to be deprecated)
Add as module
- Clone the Github project on your machine
- Add this project as a library module
Using .AAR file
- Download the latest version of
blueshift-android-sdk
file from here - Add it into your
/libs
folder. - Modify your
build.gradle
file to contain following code.
- Java
repositories {
flatDir {
dirs 'libs'
}
}
dependencies {
// for Android Advertising Id
compile 'com.google.android.gms:play-services-ads:10.2.0'
// for JSON parsing
compile 'com.google.code.gson:gson:2.6.1'
// for annotations used (ex @NotNull)
compile 'org.jetbrains:annotations:13.0'
// BlueShift SDK
compile(name: 'blueshift-android-sdk-1.1.7', ext: 'aar') // always use the latest version
}
From jCenter
Update your build.gradle
file with any one of the following two code snippets to get the SDK from jCenter.
- Pull the sdk from jCenter along with it's dependencies.
- Java
dependencies {
// BlueShift SDK with dependencies
compile('com.blueshift:android-sdk:1.1.7') { // always use the latest version
transitive = true
}
}
- Pull the sdk from jCenter and specify it's dependencies separately.
- Java
dependencies {
// for Android Advertising Id
compile 'com.google.android.gms:play-services-ads:10.2.0'
// for JSON parsing
compile 'com.google.code.gson:gson:2.6.1'
// for annotations used (ex @NotNull)
compile 'org.jetbrains:annotations:13.0'
// BlueShift SDK
compile 'com.blueshift:android-sdk:1.1.7' // always use the latest version
}
Follow the steps below to setup the Android SDK.
Permissions required
Add the following permissions to your AndroidManifest.xml
- XML
<!-- For GCM notification -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<!-- Important: Replace 'com.blueshift.sampleapp' with your app's package name -->
<permission
android:name="com.blueshift.sampleapp.permission.C2D_MESSAGE"
android:protectionLevel="signature" />
<!-- Important: Replace 'com.blueshift.sampleapp' with your app's package name -->
<uses-permission android:name="com.blueshift.sampleapp.permission.C2D_MESSAGE" />
<!-- For scheduling network operations effectively -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- For analytical purpose (optional) -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
Rich push notification
Add the following block inside <application> tag. This part ensures that your application can receive GCM push notifications.
- XML
<receiver
android:name="com.blueshift.gcm.GCMBroadcastReceiver"
android:permission="com.google.android.c2dm.permission.SEND">
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE" />
<action android:name="com.google.android.c2dm.intent.REGISTRATION" />
<!-- Important: Replace 'com.blueshift.sampleapp' with your app's package name -->
<category android:name="com.blueshift.sampleapp" />
</intent-filter>
</receiver>
<service android:name="com.blueshift.gcm.GCMIntentService" />
<!-- Important: Replace 'com.blueshift.sampleapp' with your app's package name -->
<receiver android:name="com.blueshift.rich_push.RichPushBroadcastReceiver">
<intent-filter>
<action android:name="com.blueshift.sampleapp.RICH_PUSH_RECEIVED" />
<category android:name="com.blueshift.sampleapp" />
</intent-filter>
</receiver>
<meta-data
android:name="com.blueshift.gcm_sender_id"
android:value="id:YOUR_GCM_SENDER_ID" />
Add the following block inside <application> tag to enable deep-linking from notification to product/cart/offer pages.
- XML
<receiver android:name="com.blueshift.rich_push.RichPushActionReceiver">
<!-- Important: Replace 'com.blueshift.sampleapp' with your app's package name -->
<intent-filter>
<action android:name="com.blueshift.sampleapp.ACTION_VIEW" />
<action android:name="com.blueshift.sampleapp.ACTION_BUY" />
<action android:name="com.blueshift.sampleapp.ACTION_OPEN_CART" />
<action android:name="com.blueshift.sampleapp.ACTION_OPEN_OFFER_PAGE" />
<action android:name="com.blueshift.sampleapp.ACTION_OPEN_APP" />
<category android:name="com.blueshift.sampleapp" />
</intent-filter>
</receiver>
In case you want to override the default SDK notification handlers, you can read on how to do that here
To initialize the SDK, add the following code inside onCreate()
of your Application file.
- Java
Configuration configuration = new Configuration();
// == Mandatory Settings ==
configuration.setAppIcon(R.mipmap.ic_launcher);
configuration.setApiKey("YOUR_BLUESHIFT_API_KEY");
// == Deeplink (Optional) ==
configuration.setProductPage(ProductActivity.class);
configuration.setCartPage(CartActivity.class);
configuration.setOfferDisplayPage(OfferDisplayActivity.class);
// == Notification (Optional) ==
configuration.setLargeIconResId(R.drawable.notification_big_icon);
configuration.setSmallIconResId(R.drawable.notification_small_icon);
int color = ContextCompat.getColor(getApplicationContext(), R.color.notification_color);
configuration.setNotificationColor(color);
configuration.setDialogTheme(R.style.dialog_theme); // for dialog type notifications
// == Batched Events (Optional) ==
/*
* This is the time interval used for batching events which are then sent to
* Blueshift using the bulk events api call. It defaults to 30 min if not set.
*
* It is recommended to use one of the following for API < 19 devices.
* AlarmManager.INTERVAL_FIFTEEN_MINUTES
* AlarmManager.INTERVAL_HALF_HOUR
* AlarmManager.INTERVAL_HOUR
* AlarmManager.INTERVAL_HALF_DAY
* AlarmManager.INTERVAL_DAY
*/
configuration.setBatchInterval(timeInMilliSeconds);
Blueshift.getInstance(this).initialize(configuration);
The UserInfo class helps sending the user related details to Blueshift. If the values are set after sign in, they will be used for building the events params for all events going forward. Here is an example of setting customer id and email after user sign in.
- Java
// sign in complete
UserInfo userInfo = UserInfo.getInstance(this);
userInfo.setRetailerCustomerId(retailerCustomerId);
userInfo.setEmail(email);
// It is important to save the instance once an updation is made on UserInfo
userInfo.save(context);
This section applies to apps using proguard, feel free to skip otherwise.
Proguard optimizes the code and obfuscates some of our header files. Please add the following rules to ensure the sdk works with proguard.
- Java
-keep class com.blueshift.** { ; }
-dontwarn com.blueshift.**
The SDK supports rendering of simple, interactive and rich push notifications. The push notification framework supports images, custom landing pages and call to action buttons (view/buy). In addition, it also supports alert box notifications.
The application can override this notification framework by implementing its own notification rendering methods. If the application override the framework, it is important to call/implement the notification events to ensure accurate reporting. Below is an overview of the methods the application should override to implement its own notification framework.
1. Override Notification Receiver
Change the receiver for rich push messages with your receiver name in AndroidManifest.xml
<!-- Important: Replace 'com.blueshift.sampleapp' with your app's package name -->
<receiver android:name="YOUR_RECEIVER_NAME">
<intent-filter>
<action android:name="com.blueshift.sampleapp.RICH_PUSH_RECEIVED" />
<category android:name="com.blueshift.sampleapp" />
</intent-filter>
</receiver>
Now implement your logic inside onReceive of this custom receiver.
public class CustomPushReceiver extends BroadcastReceiver {
public void onReceive(Context context, Intent intent) {
/** implement your logic here **/
}
}
Note: This will disable dialog notification rendering
2. Override Notification Action Receiver
Change the receiver for push message actions in AndroidManifest.xml
<receiver android:name="YOUR_RECEIVER_NAME">
<!-- Important: Replace 'com.blueshift.sampleapp' with your app's package name -->
<intent-filter>
<action android:name="com.blueshift.sampleapp.ACTION_VIEW" />
<action android:name="com.blueshift.sampleapp.ACTION_BUY" />
<action android:name="com.blueshift.sampleapp.ACTION_OPEN_CART" />
<action android:name="com.blueshift.sampleapp.ACTION_OPEN_OFFER_PAGE" />
<action android:name="com.blueshift.sampleapp.ACTION_OPEN_APP" />
<category android:name="com.blueshift.sampleapp" />
</intent-filter>
</receiver>
Subclass the RichPushActionReceiver
and implement the following methods.
Note: Do not override
onReceive()
method.
public class CustomActionReceiver extends RichPushActionReceiver {
public void displayCartPage(Context context, Bundle bundle) {
/** implement your action here **/
}
public void displayProductPage(Context context, Bundle bundle) {
/** implement your action here **/
}
public void displayOfferDisplayPage(Context context, Bundle bundle) {
/** implement your action here **/
}
public void openApp(Context context, Bundle bundle) {
/** implement your action here **/
}
}
If you have your own notification implementation with custom payload, you can incorporate that inside the Blueshift's notification rendering framework.
There are two ways to do it.
1. Implement receiver to catch non-blueshift pushes
When the RichPushBroadcastReceiver
gets a push without 'message' key in it, it will send a broadcast with the entire push payload. We can implement a receiver to receiver this kind of broadcast. In this way, blueshift's framework will render all the push messages coming from blueshift and rest of the payload we will get in our new receiver. Following are the steps to implement this new receiver.
1. Create Broadcast Receiver
- Java
public class AppNotificationsReceiver extends BroadcastReceiver {
public void onReceive(Context context, Intent intent) {
// implement notification rendering according to your app
}
}
- XML
<receiver android:name=".AppNotificationsReceiver">
<intent-filter>
<action android:name="com.blueshift.sampleapp.ACTION_PUSH_RECEIVED"/>
</intent-filter>
</receiver>
Note: Replace
com.blueshift.sampleapp
with your package name.
2. Implement your own push receiver
In this method you can override the RichPushBroadcastReceiver
and completely handle the notification rendering by your own. Following steps will let you implement this.
1. Override the RichPushBroadcastReceiver
class
- Java
public class AppNotificationsReceiver extends RichPushBroadcastReceiver {
public void onReceive(Context context, Intent intent) {
if (isMyAppsNotification(intent)) {
// handle your notification rendering here.
// Note: You have to take care of notification events explicitly
} else {
// Let Blueshift sdk do the notification rendering
super.onReceive(context, intent);
// If you want to take care of Blueshift's notification payload
// and implement your own notification rendering, you can do that too.
// for that, instead of calling super.onCreate(), implement it your own
// Note: You have to take care of notification events explicitly
}
}
private boolean isMyAppsNotification(Intent intent) {
// check the bundle and see if it belongs to this app
// if yes, return true. else return false.
return true;
}
}
- XML
replace
<receiver android:name="com.blueshift.rich_push.RichPushBroadcastReceiver">
with
<receiver android:name=".AppNotificationsReceiver">
If you have only one Activity in your app that holds different fragments for Product Details, Cart and Offer Display pages; It will be difficult to set Activities for deep linking (from notification) during initialisation. Following code demonstrates a way to handle this scenario. This helps you add additional data into the bundle, which helps you decide showing the appropriate fragment in the activity when launched.
1. Initialisation
configuration.setProductPage(HomeActivity.class); // provide product activity class
configuration.setCartPage(HomeActivity.class); // provide cart activity class
configuration.setOfferDisplayPage(HomeActivity.class); // provide offers activity class
- Java
public class MyActionReceiver extends RichPushActionReceiver {
// Note: do not override onReceive
public void displayProductPage(Context context, Bundle bundle) {
if (bundle != null) {
// add desicion making keys
bundle.putString("fragment_name", "ProductFragment")
}
super.displayProductPage(context, bundle);
}
}
- XML
// replace
<receiver android:name="com.blueshift.rich_push.RichPushActionReceiver">
// with
<receiver android:name="my.package.name.MyActionReceiver">
The Blueshift Android SDK uses the GCM library version, that uses the broadcast method. When used with Intent Service method, the GCM token received by the SDK might get invalidated due to some internal reasons. This may lead to deliverability issues for push messages. If the client app has a GCM implementation, we recommend you to use that alongside with the Blueshift Android SDK to get better results. Following guide will help you to achieve the same.
1. GCM Registration
Get the updated GCM token from the InstanceID
class and set it inside Blueshift Android SDK. You need to do this in the following three cases.
- When Blueshift Android SDK is initialized
- When the GCM registration is complete
- When the GCM token is refreshed
Following code snippet can be used in all above cases to set the GCM token inside Blueshift Android SDK.
// Following lines should not be called from main thread.
InstanceID instanceID = InstanceID.getInstance(this);
String token = instanceID.getToken(getString(R.string.gcm_defaultSenderId), GoogleCloudMessaging.INSTANCE_ID_SCOPE, null);
Blueshift.getInstance(this).updateDeviceToken(token);
2. Rendering Notifications
Blueshift Android SDK's RichPushBroadcastReceiver
class is responsible for receiving the push message and rendering the notification. To make use of this class you can send a broadcast with the notification payload to this class from your GcmListenerService.onMessageReceived
method.
Note: Use this method only if Blueshift Android SDK is not rendering the push message.
public void onMessageReceived(String from, Bundle data) {
String action = getPackageName() + ".RICH_PUSH_RECEIVED";
Intent intent = new Intent(action);
intent.puExtras(data);
sendBroadcast(intent);
}
To check if the bundle has notification payload from Blueshift, the developer can use the following snippet in their MAIN activity.
You could use the code inside either onCreate()
or onNewIntent()
- in case if your Activity is declared singleInstance
import com.blueshift.rich_push.Message;
/* ... */
Bundle bundle = getIntent().getExtras();
Object message = bundle.getSerializable(RichPushConstants.EXTRA_MESSAGE);
if (message instanceof Message) {
// we have Message object of Blueshift SDK in bundle
}
If you have your own implementation of things and just want to know if the bundle has payload from Blueshift, you may use the following method.
private boolean containsBsftPayload(Bundle bundle) {
boolean result = false;
if (bundle != null && bundle.containsKey(RichPushConstants.EXTRA_MESSAGE)) {
Object message = bundle.getSerializable(RichPushConstants.EXTRA_MESSAGE);
result = message instanceof Message;
}
return result;
}
Blueshift uses few external libraries inside the SDK.
You may find troubles integrating the SDK if you have same library included in your project with a different version. You could always exclude them and use your version instead.
Here is a sample code for excluding the play-services-ads
library.
compile('com.blueshift:android-sdk:1.1.7') {
exclude group: 'com.google.android.gms', module: 'play-services-ads'
}
Following are the dependencies we have in the Blueshift SDK
'com.android.support:appcompat-v7:25.1.0'
'com.google.android.gms:play-services-ads:10.2.0'
'com.google.code.gson:gson:2.6.1'
'org.jetbrains:annotations:13.0'