Android SDK Setup

To use HyperTrack SDK in your Android app, we first need to plug in the SDK into your app.

[warning] Requirements

The SDK is compatible with Android 4.1 (API level 16) and above. Also, the SDK can only be used in devices that support GPS. Devices utilizing only A-GPS are not supported.

Step 1: Install the SDK

In your app's build.gradle file, define the repositories and dependencies as shown. Once configured, run a gradle sync to import the SDK and its dependencies to your project.

In case you're facing Gradle dependency conflict errors, troubleshoot here for detailed info.

[info] build.gradle files

Your project will have two gradle files: one for the app module, and one for the project. Edit the app module file to install the SDK.

repositories {
    maven {
      url "http://hypertrack-android-sdk.s3-website-us-west-2.amazonaws.com/"
    }
}

dependencies {
    compile("com.hypertrack:android:0.4.19:release@aar") {
        transitive = true;
    }
}

[warning] Proguard rules

If you are using Proguard in your project add the following lines to your proguard configuration file (proguard-rules.pro):

  • -keep class com.hypertrack.lib.** { *; }
  • -dontwarn com.hypertrack.lib.**

Step 2: Configure the SDK

Now that the SDK has been installed, you can use the SDK methods inside Android Studio. Configure your publishable key and initialise the SDK in the onCreate method of your Application class.

HyperTrack.initialize(this.getApplicationContext(), “YOUR_PUBLISHABLE_KEY”);

Step 3: Enable location permissions

  • The SDK requires the ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions. These are already included in the SDK manifest so need not be explicitly added.

  • In case your app is for Marshmallow and above (API level 23+), Call requestPermissions() API to request for run-time location permissions.

  • For high quality location collection, the SDK needs location services enabled at high accuracy. Call requestLocationServices() API to request for user to enable Location Services in high-accuracy, if not enabled already.

Refer here for a sample implementation for requesting Location Permissions & Services.

// To request Location Permissions
HyperTrack.requestPermissions(this);

// To enable Location Services
HyperTrack.requestLocationServices(this, null);

Now that we have the SDK plugged-in in your app. Call a few simple SDK methods to start seeing live location of your users on HyperTrack dashboard. You'll begin to see trips that the user makes (along with polylines, time & distance traveled) and places that the user stops at (along with time they spend at that place).

Step 4: Create SDK user

To be able to identify the device, the SDK needs a user id. You can create a new user user on the SDK, and specify user's name, phone and a unique lookup_id as string identifiers. This API is a network call that requires the device to be online.

[info] User already created?

You can set an existing user id, in case you have created an user id via the backend API using the HyperTrack.setUserId("YOUR_USER_ID") method in the SDK.

SDK method Description
getOrCreateUser Creates a new user, or fetches an existing user with the same lookup id.
setUserId Set the user id if the user has been created on the backend.
UserParams userParams = new UserParams().setName(name)
                .setPhone(phoneNumber)
                .setPhoto(encodedImage)
                .setLookupId(phoneNumber);

// This API will create a new user only if none exists already for the given lookup_id
HyperTrack.getOrCreateUser(userParams, new HyperTrackCallback() {
    @Override
    public void onSuccess(@NonNull SuccessResponse response) {
        if (response.getResponseObject() != null) {
            User user = (User) response.getResponseObject();
            // Handle user_id, if needed
            String userId = user.getId();

            Toast.makeText(this, "User created successfully with UserId: " + userId, Toast.LENGTH_SHORT).show();
            ...
        }
    }

    @Override
    public void onError(@NonNull ErrorResponse errorResponse) {
        // Handle createUser error here
       Toast.makeText(this, errorResponse.getErrorMessage(), Toast.LENGTH_SHORT).show();
    }
});

Step 4: Start the SDK

To start tracking the user, use the startTracking method. You can keep the SDK on throughout the day, or turn it off if you want to stop tracking the user at any point of time using the HyperTrack.stopTracking() method.

HyperTrack.startTracking();

Step 6: View dashboard

Install your app with the HyperTrack SDK on a device and begin tracking on the Dashboard. You would see the user’s current state on the HyperTrack dashboard. If you click on the user, you should be able to view the user's trips and stops.

Real-time support

GCM/FCM integration with HyperTrack SDKs enables realtimeness in tracking experiences across platforms. This allows the SDK to be controlled by the server for better battery optimization and also adds robustness in recovering from crashes.

[info] Realtime support Onboarding

We recommend you try our new interactive step-by-step onboarding to enable realtime support. Refer here for more details or in case of any issues.

Android Realtime support Onboarding

Step 7: Stop the SDK

To stop tracking the user, use the stopTracking method.

HyperTrack.stopTracking();

[success] Basic Integration Completed

Now that we have the basic integration complete, we need to implement the device-server communication.

Simulate a trip for testing

To simulate a trip, replace startTracking API with startMockTracking and stopTracking API with stopMockTracking.

[info] Simulate where?

startMockTracking API will run a simulation from your current location to a nearby location. You can stop this simulation anytime by calling stopMockTracking API.

// Replace startTracking API with startMockTracking
// HyperTrack.startTracking();
HyperTrack.startMockTracking(new HyperTrackCallback() {
    @Override
    public void onSuccess(@NonNull SuccessResponse response) {
        // Handle startMockTracking success here
    }

    @Override
    public void onError(@NonNull ErrorResponse errorResponse) {
        // Handle startMockTracking error here
        Toast.makeText(MainActivity.this, errorResponse.getErrorMessage(), Toast.LENGTH_SHORT).show();
    }
});
// Replace stopTracking API with stopMockTracking
// HyperTrack.stopTracking();
HyperTrack.stopMockTracking();

results matching ""

    No results matching ""