Quickstart - Android Studio

Compatibility

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

Files

The Pulse Android package contains three files:

  • android-beacon-library-x.x.x.aar – Pulse utilizes the AltBeacon library for beacon monitoring and ranging functions
  • pulse-sdk-library.zip – Pulse library files
  • demo-app-.zip – Demo app as a reference implementation

Installation

Import Beacon module

Import a new module (android-beacon-library-x.x.x.aar). Add this module to the existing project structure.

Quickstart Capabilities

Import Pulse SDK library module

Unzip pulse-sdk-library.zip and import this library project in Android Studio as an Eclipse ADT Project. Add this module to the existing project structure.

Quickstart Capabilities

Add Google Play Services

Add Google Play Services dependency inside the build.gradle file in the pulse-sdklibrary module :

dependencies {
 compile files('libs/PulseSdk.jar')
 compile 'com.google.android.gms:play-services:8.4.0'
}

Note that Pulse uses Android’s Google Play Services for Geofencing interactions. See the guide for details: https://developers.google.com/android/guides/setup

Compile Sdk Version & Build Tools Version

Update “Compile Sdk Version” and “Build Tools Version” for both application and pulse-sdk-library modules

Quickstart Capabilities

Quickstart Capabilities

Location permissions in AndroidManifest.xml

Add location permissions in the AndroidManifest.xml file of your project for Geofence operations:

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

Integration

Initialise Pulse library

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

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

Please refer to the demo app’s DemoAppApplication.java file to review the examples in this document.

Initialise SDK with your app key

Initialise the SDK using the setConfig method with your app key:

mPulseSDK.setConfig(“key”,“your-app-key-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 the SDK mode

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);

By default, the SDK will use ANDROID_ID and the hardware SERIAL number to create a session identifier for the app install: https://developer.android.com/reference/android/provider/Settings.Secure.html#ANDROID_ID https://developer.android.com/reference/android/os/Build.html#SERIAL

If you want to use another identifier, use the setSessionID method before starting the service:

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

Please refer to the demo app’s DemoAppApplication.java file to review these Pulse service configurations.

Stop and restart the SDK

Pulse interactions can be “force” stopped if required. This feature is used to implement custom user controls within the app to allow users to opt-in/out of using Pulse-powered features. Note that Pulse services operate asynchronously; therefore depending on the device it will take a few seconds to shut it down or restart.

  • 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);

In-app interactions within a web view

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.

Android 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: https://developer.android.com/design/patterns/notifications.html

  • Please refer to the demo app’s res folder for an example.

    Quickstart Capabilities

  • You may also wish to customize the background color of the notification icon by modifying the colors.xml file in the pulse-sdk-library project.

    Quickstart Capabilities

    For example :

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

Android Marshmallow and above

New permission standard

If an app’s target build is API 23 or higher, then the developer needs to account for the new permission standard introduced in Android 6.0: https://developer.android.com/guide/topics/security/permissions.html#normal-dangerous

  • 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.

    Quickstart Capabilities

  • As an example, below is a suggested approach 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();
                 }
              }
           }
        }
     }

Clean the project and build with ProGuard

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.