Quickstart

Compatibility

The Pulse library works with Android 4.3.1(API 18) to Android Oreo(API 26) and with devices equipped with Bluetooth 4.0 or higher.

Installation

---

Add Pulse SDK

Add Pulse repository to your project's build.gradle file.

repositories {
    ...
    maven {
        url "https://dl.bintray.com/pulseid/pulse-android"
    }
}

Add following to your module’s build.gradle file:

android {
    ...
    packagingOptions {
        exclude 'META-INF/DEPENDENCIES.txt'
        exclude 'META-INF/LICENSE.txt'
        exclude 'META-INF/NOTICE.txt'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/notice.txt'
        exclude 'META-INF/license.txt'
        exclude 'META-INF/dependencies.txt'
        exclude 'META-INF/LGPL2.1'
    }
}

dependencies {
    ...
    compile 'com.pulseid:pulse-sdk:2.11.0'
}

For build systems other than Gradle please visit our Bintray page and click the Set me up! button.

Access

If for some reason you're unable to use the Maven repository, please contact support@pulseid.com to be provided with an installation package and instructions..

Add location permissions

Ensure that following permissions are in AndroidManifest.xml file of your project:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

If your app’s target build is API 23 or higher, then you need to account for the new permission standard introduced in Android 6.0: See additional Permissions

Initialise SDK

Initialise the PulseSDK class in the main Application class of your project. For example :

   Private PulseSDK mPulseSDK;
   mPulseSDK = new PulseSDK(this);

   String mPackageName = "your-app-package-name-here";
   boolean available = mPulseSDK.isAvailable(mApplicationContext,mPackageName);

   if(available) {
      initPulseSDK(mPackageName);
   }

• Build.VERSION.SDK_INT is 23 or higher

  Initialise the Pulse SDK once Activity that shows the location permission prompt receives a location permission result. Please make sure the following should be called only once during the lifecycle of the application. For example :

   if(true != PulseSDK.getSDKInitialised()) {
      mApplication.initPulseSDK("your-app-package-name-here");
   }

• Build.VERSION.SDK_INT is less than 23

  Initialise Pulse SDK onCreate() in Activity that shows the location permission prompt. Please make sure the following should be called only once during the lifecycle of the application. For example :

    if(true != PulseSDK.getSDKInitialised()) {
        mApplication.initPulseSDK("your-app-package-name-here");
    }

Integration Example

Please use the Demo Application as a reference implementation for the SDK. Refer to the app’s DemoAppApplication.java and DemoActivity.java files to review the examples in this guide.

Configuration

---

Set app key

Initialise the SDK using the setConfig method with the app key provided to you by Pulse iD:

mPulseSDK.setConfig(“key”,“your-app-key-here”);

Set your app end-point

Then set your app's environment end-point provided by Pulse iD:

mPulseSDK.setConfig(“url”,“your-app-url-here”);

Set the package name

If the package name of the Application does not match the package name in AndroidManifest.xml, set the package name to ensure app references can be correctly read by the SDK:

mPulseSDK.setPackageName(mPackageName);

Set Session

Optional step

By default, the SDK will use ANDROID_ID and the hardware SERIAL number from the operating system to create a session identifier for the app install. All analytics and data will be gathered against this session id:

• Settings.Secure.html#ANDROID_ID

• Build.html#SERIAL

Use the setSessionID method before starting the service, if you want to use a custom identifier:

   mPulseSDK.setSessionID("4083EE6AF29F4DEDBE5729EB85DD16C8");
   ...
   mPulseSDK.startService(true, true, true);

Integration

---

Start Services

Pulse runs a service to ensure that interactions can be triggered even when the app is in the background or inactive (not in memory). Based on project requirements, Pulse's service can be started in different modes to selectively trigger interactions:

• To interact in all modes (foreground, background and inactive):

   mPulseSDK.startService(true, true, true);

• To interact in foreground and background mode only:

   mPulseSDK.startService(true, true, false);

• To interact in foreground only:

   mPulseSDK.startService(true, false, false);

• To interact in background only:

   mPulseSDK.startService(false, true, false);

In-app Interactions

When the app is open (active), in-app beacon/geofence interactions are rendered within a web view. This feature is only available when the setActivityStatus method is called within the app’s activity lifecycle functions.

For example :

   import com.pulse.sdk.global.PulseSDK;

   @Override
   protected void onResume() {
     super.onResume();
     PulseSDK.setActivityStatus(this,false,false);
   }

   @Override
   protected void onPause() {
     PulseSDK.setActivityStatus(this,true,false);
     super.onPause();
   }

   @Override
   protected void onDestroy() {
     PulseSDK.setActivityStatus(this,false,true);
     super.onDestroy();
   }

Please refer to the demo app’s DemoActivity.java file for a working example.

Stop Services

Pulse interactions can be force stopped if required. This feature can be used to implement custom user controls within the app to allow users to opt-in/out of using Pulse-powered features.

• To stop the PulseSDK Service:

   PulseSDK.stopService(mApplication);

• After stopping, to restart the PulseSDK Service:

   PulseSDK.resetService(mApplication);
   PulseSDK mPulseSDK = new PulseSDK (mApplication);
   PulseSDK.startService(true, true, true);

Asynchronous Operations

Pulse services operate asynchronously, therefore depending on the device it will take a few seconds for them shut down or restart.

Build

Clean the project (Project > Clean) and then Build(Project > Build Project). Please refer to both proguard-pulse.txt and project.properties files in the Pulse demo app to build with ProGuard.

Tips

---

Lollipop and above

Notification icon

Ensure the name of the notification icon file (PNG) is ic_notification_above_lollipop.png for target devices that have API 21 (Lollipop) and above. This app icon will appear in notifications. Refer to the Android guide for guidance on notification icon design: Android Notifications

You can also refer to the demo app’s res folder for an example.

Notification background

You also need to customize the background color of the notification icon by adding the colors.xml file in the application project. Please refer to the demo app’s res folder for an example.

For example :

<?xml version="1.0" encoding="utf-8"?>
<resources>
<color name="notification_icon_bg_color_above_lollipop">#ffff4b2f</color>
</resources>

Marshmallow and above

---

Location permission

The Pulse SDK requires Location permissions to operate its Geofence and beacon features. Thus, it is recommended that user Location permission is asked for when the app is opened for the first time. Android Permissions

Below is an example to request location permission in the launcher activity of the app. Refer to the demo app’s DemoActivity.java file to see this example:

     //remove Toast messages in production
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       if (Build.VERSION.SDK_INT >= 23) {
         PulsePermissions mPulsePermissions = new
         PulsePermissions (this.getApplicationContext());
         requestLocationPermission(mPulsePermissions.getPemissionStatusLocation());
       }
     }

     private void requestLocationPermission(int mLocation) {
        if (Build.VERSION.SDK_INT >= 23) {
           if ((mLocation != PackageManager.PERMISSION_GRANTED)) {
             boolean bLocation = ActivityCompat.shouldShowRequestPermissionRationale(this,Manifest.permission.ACCESS_FINE_LOCATION);
               if (bLocation) {
                  Toast.makeText(this, "User denied Location Permission... Wait until user has changed Permission", Toast.LENGTH_LONG).show();
               }else {
                  //Show location permission prompt to user
                  ActivityCompat.requestPermissions((Activity) this,
                  new String[]{Manifest.permission.ACCESS_FINE_LOCATION},
                  REQUEST_PERMISSION_LOCATION);
               }
           } else {
              if((mLocation != PackageManager.PERMISSION_GRANTED)) {
                  boolean bLocation = ActivityCompat.shouldShowRequestPermissionRationale(this,Manifest.permission.ACCESS_FINE_LOCATION);
                 if (bLocation) {
                   Toast.makeText(this, "User disabled Location Permissions... Wait until user changes Permissions", Toast.LENGTH_LONG).show();
                 }
              }
           }
        }
     }

---