Salesforce Android Integration

Overview

The Bluedot SDK integration wrapper for Salesforce Marketing Cloud enables mobile apps to take advantage of the power of the Marketing Cloud and the superior accuracy, Geofence, Geolines™ and BLE Beacon triggering capabilities of the Bluedot SDKs. This documentation describes the steps required to integrate the Bluedot Point Android SDK and Marketing Cloud Android SDK using the BDSalesforceIntegrationWrapper library into an Android App.

Salesforce Marketing Cloud Android SDK Integration

Add the following repositories and dependencies to your Project’s build.gradle file:

...
allprojects {
    repositories {
        maven { url "http://salesforce-marketingcloud.github.io/JB4A-SDK-Android/repository" }
    }
}
...
dependencies { 
    ...
    classpath 'com.google.gms:google-services:4.0.1'
}

2. Add the following plugin and dependencies to your application’s build.gradle file:

dependencies { 
    ... 
    implementation ('com.salesforce.marketingcloud:marketingcloudsdk:6.1.0') { 
           exclude module: 'android-beacon-library' //remove to use Proximity messaging 
           exclude module: 'play-services-location' //remove to use Geofence or Proximity messaging 
    } 
    implementation 'com.google.android.gms:play-services-location:16.0.0'
    api 'com.google.firebase:firebase-messaging:17.4.0'
    api 'com.google.firebase:firebase-core:16.0.8'
}
apply plugin: 'com.google.gms.google-services'

3. Add google-services.json obtained from Firebase test project in your app as below:

The following code example demonstrates starting the Marketing Cloud SDK as well as obtaining the salesforceContactKey or setting thesalesforceContactKey if not assigned yet. More information on how to get AppID, Access Token and MID can be found here

public class MainApplication extends Application implements MarketingCloudSdk.InitializationListener {
    private String salesforceContactKey;
    private String app_id="";           //From Marketing Cloud App details
    private String access_token="";     //From Marketing Cloud App details
    private String mID = “”;            // MID from Firebase setup
    private String fcm_id="";
    private void initCloudMobilePushSDK() {
        MarketingCloudSdk.init((this, MarketingCloudConfig.builder()
            .setApplicationId(app_id)
            .setAccessToken(access_token)
            .setSenderId(fcm_id)
            .setMarketingCloudServerUrl(getString(R.string.marketing_cloud_url))   //Cloud Marketing URL
            .setMid(mID)
            .setNotificationCustomizationOptions(
                        NotificationCustomizationOptions.create(R.mipmap.ic_launcher, null,
                              new com.salesforce.marketingcloud.notifications.NotificationManager.NotificationChannelIdProvider() {
                              @Override @NonNull 
                               public String getNotificationChannelId(@NonNull Context context,@NonNull NotificationMessage notificationMessage) {
                                     // Whatever custom logic required to determine which channel should be used for the message.
                                     return CHANNEL_ID;
                               }
                })).build((Context) this), this);
    }

@Override
public void complete(@NonNull InitializationStatus status) {


if (status.status() == InitializationStatus.Status.SUCCESS) {
    logInfo("Marketing Cloud SDK started");
    salesforceContactKey = MarketingCloudSdk.getInstance().getRegistrationManager().getContactKey();
    if (salesforceContactKey == null || salesforceContactKey.length() == 0) {
        salesforceContactKey = UUID.randomUUID().toString();
        MarketingCloudSdk.getInstance().getRegistrationManager().edit().setContactKey(salesforceContactKey).commit();
    }

    } else if (status.status() == InitializationStatus.Status.COMPLETED_WITH_DEGRADED_FUNCTIONALITY) {
        // While the SDK is usable, something happened during init that you should address.
       // This could include:

      //Google play services encountered a recoverable error

     /* The user had previously provided the location permission, but it has now been revoked.
     Geofence and Beacon messages have been disabled. You will need to request the location
     permission again and re-enable Geofence and/or Beacon messaging again. */

     /* Google Play Services attempted to update your SSL providers but failed. It should be assumed that
     all network communications will fallback to TLS1.0.
     */
     } else if (status.status() == InitializationStatus.Status.FAILED) {
         logInfo("Marketing Cloud SDK error: " + status.toString());
     } else {
         logInfo("Marketing Cloud SDK : Unknown error");
     }
   }
    ...
}

The full documentation on Marketing Cloud SDK integration; if required at any point; is available here.

Bluedot Point SDK Integration

Download the SDK and follow the steps below to complete the integration of the Bluedot Point SDK for Android. The SDK can be downloaded from the ‘Developers’ section of the ‘Bluedot Location Marketing’ app on Salesforce Marketing Cloud. A comprehensive integration guide on how to integrate the Bluedot Point SDK can be found here. It is recommended that the Bluedot Point SDK for Android is integrated at the Application class level.

Requirements

Minimum Android OS Version – 4.0 Ice Cream Sandwich (API 14) and above.
For apps with indoor beacon support:
- Bluetooth V4.0 Low Energy (BLE) hardware support.
- Android OS Version – 4.3 Jellybean (API 18) and above.
Active mobile data or a Wi-Fi connection.
Location services must be turned on with the device allowing location updates from both GPS and network.

Integration Steps

Integrating Bluedot Point SDK to project

Bluedot Point SDK can be added as an AAR (recommended) or JAR file to your project. Follow the links below for SDK integration steps:

Starting the SDK

The ServiceManager is the entry-point for an app to start using the Bluedot Point SDK. The app must get an instance of the ServiceManager class and invoke sendAuthenticationRequest method by providing the API key in order to authenticate and start the Bluedot engine. The API Key can be retrieved from the ‘Developers’ section of the ‘Bluedot Location Marketing’ app on Marketing Cloud. It is important to pass a reference to ServiceStatusListener so the app can receive Service status callbacks from the SDK.

public class BDTestApplication extends Application implements ServiceStatusListener{
    ...
    private ServiceManager mServiceManager;
    private String apiKey = ""; //API key for the Bluedot Location Marketing app from HubExchange.
    private boolean restartMode = true;
    ...        
    @Override
    protected void onCreate() {
        super.onCreate();
              
        //Get an instance of ServiceManager to access the Bluedot Point Service
        mServiceManager = ServiceManager.getInstance(this);
          
        //Check if the Bluedot Point Service is currently running and start it if it is not running
        if(!mServiceManager.isBlueDotPointServiceRunning()){
            serviceManager.setForegroundServiceNotification(<Notification Object>, false);
            serviceManager.sendAuthenticationRequest(apiKey, this);
        }
    }
    ...
}

Callbacks

The following mandatory callbacks of the ServiceStatusListener interface must be implemented.

public class BDTestApplication extends Application implements ServiceStatusListener{
    ....    
    @Override
    public void onBlueDotPointServiceStartedSuccess() {
        // This is called when BlueDotPointService started successfully
        // Start listening for Check-in / Check-out events from the Bluedot SDK
        mServiceManager.subscribeForApplicationNotification(this);
    }
  
    @Override
    public void onBlueDotPointServiceStop() {
        // This will be called when BlueDotPointService has been stopped.
        // Stop listening for CheckIn / CheckOut events from Bluedot SDK
        mServiceManager.unsubscribeForApplicationNotification(this);
    }
  
    @Override
    public void onBlueDotPointServiceError(BDError error) {
        // This gives you details if BlueDotPointService encounters errors.
        // Human-readable string of bdError.getReason(). It is useful for analysing the cause of the error.
        // Boolean bdError.isFatal() identifies if the error is fatal and BlueDotPointService is no longer functional;
        // onBlueDotPointServiceStop() callback is invoked immediately after a fatal erro.
    }
  
    @Override
    public void onRuleUpdate(List zoneInfos) {
        // Passively receive Zones information and is optional
    }
    ....
}

The ApplicationNotificationListener provides the following callbacks to inform when a Zone Check-in / Check-out event occurs.

/**
 * This callback executes when the app user checks into a geofence
 */
public void onCheckIntoFence(FenceInfo fenceInfo, ZoneInfo zoneInfo, Location location, Map<String, String> customData, boolean isCheckOut);
 
/**
 * This callback executes when the device checks out of a geofence
 */
public void onCheckedOutFromFence(FenceInfo fenceInfo, ZoneInfo zoneInfo, int dwellTime, Map<String, String> customData);
 
/**
 * This callback executes when the device checks into a beacon at a pre-set proximity
 */
public void onCheckIntoBeacon(BeaconInfo beaconInfo, ZoneInfo zoneInfo, Location location, Proximity proximity, Map<String, String> customData, boolean isCheckOut);
 
/**
 * This callback executes when the device checks out of a beacon
 */
public void onCheckedOutFromBeacon(BeaconInfo beaconInfo, ZoneInfo zoneInfo, int dwellTime, Map<String, String> customData);

For further information on the classes and methods discussed within this documentation, please refer to the Android SDK documentation.

The Bluedot Salesforce integration wrapper

The BDSalesforceIntegrationWrapper can be downloaded from the ‘Developers’ section of the ‘Bluedot Location Marketing’ app. This lightweight wrapper is responsible for initiating Salesforce Journey Builder interactions when zones trigger.

The downloaded bdsalesforceintegrationwrapper.jar file should be placed in the /libs folder of the project

The BDSalesforceIntegrationWrapper library declares a singleton class named ZoneEventReporter containing reportCheckIn and reportCheckOut methods. These methods are used to report Zone Check-in and Check-out events to the backend in order to initiate the Marketing Cloud Journey Builder interactions.

/**
 * Report a check-in event
 * @param zoneEvent - BDZoneEvent object.
 */
public void reportCheckIn(BDZoneEvent zoneEvent);
 
/**
 * Report triggered zone Check Out event
 * @param zoneEvent - BDZoneEvent object.
 */
public void reportCheckOut(BDZoneEvent bdZoneEvent);

GitHub Sample Project

A sample project which demonstrates the integration of Marketing Cloud SDK and Bluedot Point SDK using the BDSalesforceIntegrationWrapper is available on GitHub.