Setup with GCM (v1.1.7 or older)

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.

  1. 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 
    }
}
  1. 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
}
 

Setup

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

  • Java
public class AppNotificationsReceiver extends BroadcastReceiver {
    @Override
    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 {
    @Override
    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

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

  1. When Blueshift Android SDK is initialized
  2. When the GCM registration is complete
  3. 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'
Was this article helpful?
0 out of 0 found this helpful