Android Features – AutoStart of SDK

Point SDK is represented as an Android Service in an app. A regular service can be terminated by the user or by the Android OS at any time. If the device is restarted then Android OS will not restart the service on boot complete. To keep running the SDK service in the background even the if the user/Android OS terminates the app or the device is rebooted, a special “restarting” launch mode can be used. This restart mode effectively means the service will be started with the START_STICKY flag and will register a boot complete receiver. To achieve this functionality, certain changes need to be made to the app’s source code.

  • The Point SDK needs to be authenticated at the Application level, rather than the Activity, Service or Fragment level.
  • The custom Application class should Implement the ServiceStatusListener and ApplicationNotificationListener (only if needed, as per the use case).
  • Invoke the sendAuthenticationRequest(..., boolean restartMode) API method of ServiceManager within the onCreate() method of the Application class.
  • Set the parameter  restartMode flag to true. Setting restartMode to true will start the service in sticky mode and register a boot complete receiver.
  • If the app implements its own session management, validation of the state of the app’s session before authenticating the Point SDK is recommended to ensure the SDK session is aligned with the app’s session. This is a good practice to avoid Point SDK starting on boot complete when the app has no active session.

STICKY MODE

Starting the service in sticky mode refers to running the service in the background even if the app has been terminated by the user or Android OS kills the service.  This allows Point SDK to run in the background and continue to trigger zones.

Even when sticky mode is on, the service will stop working if the device is rebooted. To continue running the Point SDK service after the reboot, the SDK registers a boot complete receiver. On successful reboot, the registered boot receiver will be invoked and will create an instance of the Application class. As recommended in Programming a minimal Point SDK-enabled app, the SDK will re-authenticate and the service will start in the background.

Caveats

  • It’s recommended to create a public authentication method in the Application class and invoke it from any other class if you would like to authenticate the Point SDK from other classes.
  • If no internet connection is available after a successful boot complete, the Point SDK will fail to authenticate and an onBlueDotPointServiceError callback will be sent.
  • If the application is stopped by the user with the “Force Stop” option via Application Management then the Bluedot Point Service will not restart when the device restarts.
  • If the sendAuthenticationRequest(…, boolean restartMode) was invoked with restartFlag set to false, then the SDK will not continue running the service if the app is terminated by the user, Android OS terminates the service, or the device is restarted.
  • It is mandatory to call the authentication inside the onCreate method of your Application class, to perform Point SDK authentication on boot complete.

Examples

The following example shows the implementation of the SDK authentication within the onCreate() method of the Application class. The Application class must be registered in the app’s manifest file.

public class BDTestApplication extends Application implements ServiceStatusListener {
     private ServiceManager mServiceManager;

     @Override
     public void onCreate() {
         super.onCreate();
         authenticateBluedotSDK();
     }
    //This method can be utilised to authenticate the Bluedot Point SDK from any other class.
     public void authenticateBluedotSDK() {
          mServiceManager = ServiceManager.getInstance(this);
          mServiceManager.sendAuthenticationRequest("API Key", this, true);
    }
}

Register your application in the Manifest file within android:name under the application tag, as shown below:

<application
 android:name="au.com.bluedot.test.BDTestApplication"
 ...
</application>

If Point SDK is integrated into the app project using the library as .jar file, then it is necessary to update the AndroidManifest.xml file to include the following receiver tag. There is no need to add the tag if Point SDK is integrated using the .AAR. Follow the migration guide to update your app to use the SDK in .AAR format.

AndroidManifest.xml changes
...
<receiver
 android:name="au.com.bluedot.point.net.engine.BluedotBootReceiver"
 android:directBootAware="true"
 android:exported="false"
 android:enabled="false">
 <intent-filter>
 <action android:name="android.intent.action.BOOT_COMPLETED" />
 <action android:name="android.intent.action.QUICKBOOT_POWERON" />
 <action android:name="android.intent.action.LOCKED_BOOT_COMPLETED" />
 </intent-filter>
</receiver>
...
Created by Bluedot DevOps on June 19, 2018

Start the discussion