This document provides an overview of how to integrate, set-up and start tracking events using the Android SDK.

1. Integration
2. Setup
3. Initializing the SDK
4. Setting User Info
5. Proguard
6. Push Notification and Alerts
7. Overriding Notification Framework
8. Overriding Notification Clicks
9. Overriding GCM Registration
10. Check for Blueshift's Payload
11. Exclude dependencies

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.

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.

From jCenter 
Update your build.gradle file with any one of the following two code snippets to get the SDK from jCenter.

1. Pull the sdk from jCenter along with it's dependencies.

2. Pull the sdk from jCenter and specify it's dependencies separately.

Follow the steps below to setup the Android SDK.

Permissions required
Add the following permissions to your AndroidManifest.xml

Rich push notification
Add the following block inside <application> tag. This part ensures that your application can receive GCM push notifications.

Add the following block inside <application> tag to enable deep-linking from notification to product/cart/offer pages.

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.

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.

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.

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 {
    @Override
    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 {

    @Override
    public void displayCartPage(Context context, Bundle bundle) {
        /** implement your action here **/
    }

    @Override
    public void displayProductPage(Context context, Bundle bundle) {
        /** implement your action here **/
    }

    @Override
    public void displayOfferDisplayPage(Context context, Bundle bundle) {
        /** implement your action here **/
    }

    @Override
    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

2. Register in AndroidManifest.xml

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

2. Update AndroidManifest.xml

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

2. Create your Receiver

3. AndroidManifest.xml

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.

1. When Blueshift Android SDK is initialized
2. When the GCM registration is complete
2. 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.

@Override
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'