Android – Integrating the SDK

To integrate Point SDK, you will need a Bluedot account. If you don’t have one, you can request here. Our SDK works with Android 4.0 and above.

Bluedot Point SDK enables an ‘always-on’ geolocation capability for apps by delivering accurate location awareness, while substantially reducing battery consumption compared to Core Location or other standard methods. Point SDK connects to Bluedot’s backend system, Canvas, to download your pre-configured Geofences, GEOLINE™, conditions, and actions.

Before you start integrating, you want to review our GitHub Minimal Integration Example. It showcases: 

  • Minimum integration points to run the Point SDK
  • How to receive Application Notifications
  • The required Location Services permissions

Otherwise, you can jump straight into development with the section Introducing ServiceManager.

Introducing ServiceManager

ServiceManager is the entry-point for an app to start using Point SDK.

The first step is to start Bluedot Point Service by calling the sendAuthenticationRequest method on the shared instance of ServiceManager with a ProjectID from Canvas as a parameter.  Navigate to “Projects” in your account to get your ProjectID.

Starting the Bluedot Point Service requires that the device is connected to the internet via a mobile data network or Wi-Fi access point.

A custom URL can also be passed in as a parameter for authentication if the app needs to connect to an alternate Bluedot back-end. Custom URLs should only be used for debugging and support purposes.

In most cases, it is required that the SDK be initialized in App Restart mode to ensure that the Bluedot Service will be restarted if it is terminated by the Android OS. Please refer to the App Restart section for more details.

It is essential to pass a ServiceStatusListener that provides a callback when BlueDotPointService starts successfully. The ServiceStatusListener provides you with four callbacks as shown in the examples below.

Please note: These callbacks should be thread-safe and should not update UI views directly. If a UI view needs to be updated from within the callback, it must be wrapped into runOnUiThread or a Handler.

It is recommended that you integrate the Bluedot Point SDK at the Application class level, as Application is the most commonly used singleton class and the Application lifecycle covers the availability of this class throughout the life of the application. It is also possible, depending on the particular application structure, to implement the ServiceStatusListener and  ApplicationNotificationListener with an Activity, Service or Fragment as well.

Application Integration

public class BDTestApplication extends Application implements ServiceStatusListener, ApplicationNotificationListener {
    
    @Override
    public void onCreate() {
    super.onCreate();

    serviceManager = ServiceManager.getInstance(this);
    // Check for location permission before authenticating the SDK
    if (ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
    // Put your code to ask for location permission here. 
    // If not using a foreground service, it will also be necessary to check and request Manifest.permission.ACCESS_BACKGROUND_LOCATION.

    // Check the Bluedot Point Service is currently running, otherwise start it
    } else if (!serviceManager.isBlueDotPointServiceRunning()){
        // Setting Notification for foreground service, required for Android Oreo and above.
        String channelId = "ID";
        String channelName = "Name";

        NotificationChannel notificationChannel = new NotificationChannel(channelId, channelName, NotificationManager.IMPORTANCE_DEFAULT);

        NotificationManager notificationManager = (NotificationManager) this.getSystemService(Context.NOTIFICATION_SERVICE);
        notificationManager.createNotificationChannel(notificationChannel);

        Notification.Builder notificationBuilder = new Notification.Builder(getApplicationContext(), channelId);

        Notification notification = notificationBuilder.build();

        // Setting targetAllAPIs to TRUE will display foreground notification for Android versions lower than Oreo
        serviceManager.setForegroundServiceNotification(notification, false);
        serviceManager.sendAuthenticationRequest("<ProjectID>",this);
    }
}
@Override public void onBlueDotPointServiceStartedSuccess() {
// This is called when BlueDotPointService started successfully
// Your app logic can start from here
}

@Override public void onBlueDotPointServiceStop() {
// This will be called when BlueDotPointService has been stopped.
// Your app could release resources that use the BlueDotPointService
}

@Override public void onBlueDotPointServiceError(BDError error) {
// This gives you details if BlueDotPointService encounters an error.
// Human-readable string of bdError.getReason() can be useful to analyse the cause of the error.
// Boolean bdError.isFatal() identifies if error is fatal and BlueDotPointService is no more functional;
// onBlueDotPointServiceStop() callback is invoked next in such a case.
}

@Override public void onRuleUpdate(List zoneInfos) {
// Passively receive Zones information
// Optional
}

@Override public void onCheckIntoFence(FenceInfo fenceInfo, ZoneInfo zoneInfo, LocationInfo location, Map<String, String> customData, boolean isCheckOut) {
// This method will be called if the device checked into a Fence
// Using a handler to pass Runnable into UI thread to interact with UI elements
}

@Override public void onCheckedOutFromFence(FenceInfo fenceInfo, ZoneInfo zoneInfo, int dwellTime, Map<String, String> customData) {
// This method will be called when a device leaves the Fence that was checked into. Only applies to zones flagged as checkout enabled on the backend.
}
}
Created by Bluedot DevOps on June 19, 2018

Start the discussion