Device-server communication

The SDK has a bi-directional communication model with the server. This enables the SDK to run on a variable frequency model, which balances the fine trade-off between low latency tracking and battery efficiency, and improve robustness. For this purpose, the Android SDK uses FCM/GCM silent notifications. This guide will take you through the setup.

Step 1: Setup FCM client for your app

[info] FCM/GCM already setup

In case you have FCM/GCM already setup in your app, you can skip this and head to the next section.

These steps will setup a Firebase project for your app, and add the google-services configuration file to your codebase. For detailed info you can refer to official documentation.

Create an API project

New Cloud Messaging projects must create a Firebase project in the Firebase console. In this process, you will generate a configuration file and credentials for your project.

  1. Create a new project in the Firebase console, if you don't already have one. If you already have an existing Google project associated with your mobile app, click Import Google Project. Otherwise, click Create New Project.
  2. Click Add Firebase to your Android app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
  3. When prompted, enter your app's package name. It's important to enter the package name your app is using; this can only be set when you add an app to your Firebase project.
  4. At the end, you'll download a google-services.json file. You can download this file again at any time.
  5. If you haven't done so already, copy this into your project's module folder, typically app/.

Add the configuration file to your project

The Google Services plugin for Gradle parses configuration information from the google-services.json file. Add the plugin to your project by updating your top-level build.gradle and your app-level build.gradle files as follows:

  • Add the dependency to your project-level build.gradle.
buildscript {
  ...
    dependencies {
       ...
        classpath 'com.android.tools.build:gradle:3.0.1'
        classpath 'com.google.gms:google-services:3.1.0'
    }
}
  • Add the plugin to bottom your app-level build.gradle.
apply plugin: 'com.google.gms.google-services'

Step 2: Locate your GCM/FCM key

Head over to your Firebase Console and locate your Server key under Project settings > Cloud Messaging.

FCM Keys

Step 3: Configure FCM/GCM key on HyperTrack

Head over to the account settings on the HyperTrack dashboard to add your FCM/GCM keys.

Note that you need to configure either one of GCM or FCM Server Key on HyperTrack, depending on the whether you have integrated GCM or FCM in your app. For detailed information, refer to official Google documentation.

FCM Key Settings

Step 4: Pass notification to SDK

For FCM Integration

To enable FCM integration, you need to change the base class for your implementation of FirebaseMessagingService to HyperTrackFirebaseMessagingService.

[info] Fresh FCM Integration

Add a new Service which extends HyperTrackFirebaseMessagingService to your application's manifest file with the tag as highlighted in the code snippet.

// Extend HyperTrackFirebaseMessagingService instead of FirebaseMessagingService
public class MyFirebaseMessagingService extends HyperTrackFirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        /**
         * Call super.onMessageReceived() method
         * SDK uses this method to handle HyperTrack notifications
         * Refer to the https://dashboard.hypertrack.com/onboarding/fcm-android
         * for more info.
         */
        super.onMessageReceived(remoteMessage);

        ...
    }
}
<!-- For fresh FCM integration, register the new file in your app's AndroidManifest.xml file -->
<service android:name=".MyFirebaseMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

For GCM Integration

To enable GCM integration, you need to change the base class for your implementation of GcmListenerService to HyperTrackGcmListenerService.

[info] Fresh GCM Integration

Add a new Service which extends HyperTrackGcmListenerService to your application's manifest file with the tag as highlighted in the code snippet.

// Extend HyperTrackGcmListenerService instead of GcmListenerService
public class MyGcmListenerService extends HyperTrackGcmListenerService {
    @Override
    public void onMessageReceived(String from, Bundle data) {
        /**
         * Call super.onMessageReceived() method
         * SDK uses this method to handle HyperTrack notifications
         * Refer to the https://dashboard.hypertrack.com/onboarding/fcm-android
         * for more info.
         */
        super.onMessageReceived(data);

        ...
    }
}
<!-- For fresh GCM integration, register the new file in your app's AndroidManifest.xml file -->
<service android:name=".MyGcmListenerService">
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    </intent-filter>
</service>

Step 5: Handle your notifications

[warning] Handle your notifications

To handle your notifications, you need to ignore HyperTrack notifications. Else your app might crash.

For FCM notifications

public class MyFirebaseMessagingService extends HyperTrackFirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        /**
         * Call super.onMessageReceived() method
         * SDK uses this method to handle HyperTrack notifications
         * Refer to the https://dashboard.hypertrack.com/onboarding/fcm-android
         * for more info.
         */
        super.onMessageReceived(remoteMessage);

        ...

        if (remoteMessage.getData() != null) {
            String sdkNotification = remoteMessage.getData().get(HT_SDK_NOTIFICATION_KEY);
            if (sdkNotification != null && sdkNotification.equalsIgnoreCase("true")) {
                /**
                 * HyperTrack notifications are received here
                 * Dont handle these notifications. This might end up in a crash
                 */
                return;
            }
        }

        // Handle your notifications here.
    }
}

For GCM notifications

public class MyGcmListenerService extends HyperTrackGcmListenerService {
    @Override
    public void onMessageReceived(String from, Bundle data) {
         /**
         * Call super.onMessageReceived() method
         * SDK uses this method to handle HyperTrack notifications
         * Refer to the https://dashboard.hypertrack.com/onboarding/fcm-android
         * for more info.
         */
        super.onMessageReceived(data);

        ...

        if (data != null) {
            String sdkNotification = data.getString(HT_SDK_NOTIFICATION_KEY);
            if (sdkNotification != null && sdkNotification.equalsIgnoreCase("true")) {
                /**
                 * HyperTrack notifications are received here
                 * Dont handle these notifications. This might end up in a crash
                 */
                return;
            }
        }

        // Handle your notifications here.
    }
}

Step 6: Test your GCM/FCM integration

This API sends a test notification (not silent) to your device from HyperTrack server.

Typical notifications from HyperTrack are silent, and will not be visible to the app user.

curl -H "Authorization: token SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v2/users/<user-id>/test_notification/

results matching ""

    No results matching ""