Install SDK for Cordova

Add Hypertrack Plugin to project

Cordova HyperTrack plugin is available for Android platform. To use it add it to your project:

$ npx cordova add cordova-plugin-hypertrack-v3

note

We constantly work on making our SDKs better, so make sure you have the latest version. You can get it in changelog here.

Set you publishable Key

Inside your application logic initialize HyperTrack Plugin with your publishable Key

hypertrack.initialize( 'MY-PUBLISHABLE-KEY', onSuccess, onError );

Initializer follows standart practice and accepts success and error callbacks. Success callback receives SDK instance handle that you need to save for further usage:

var hypertrackSdk;

function onSuccess(sdkInstance) {

console.log("HyperTrack succesfully initialized");

hypertrackSdk = sdkInstance;

}

Set up silent push notifications

Set up silent push notifications to manage on-device tracking using HyperTrack cloud APIs from your server. This requires Firebase push notification. If you do not yet have push notifications enabled, please proceed to setup Firebase Cloud Messaging.

Also you need to add your Firebase API key to your HyperTrack Dashboard Setup Page under Server to Device communication section.

note

Push notifications have delays so if you're looking for more instant channel you can use syncDeviceSettings plugin method to speed up command propagation.

Identify your device

We use internal unique identifiers to manage the devices, so in order to be able to distinguish between users you need to get this device id and pass it to your backend to establish user to deviceId mapping.

hypertrackSdk.getDeviceId(

function(deviceId) {

console.log("HyperTrack device id is " + deviceId);

user.hyperTrackDeviceId = deviceId;

},

function(err) {console.log("HyperTrack: can't get device id due to err " + err);}

);

Give your device a name

You can set device name that will show up in your Dashboard and attach metadata. You might wish to look at this guide on how to use it.

hypertrackSdk.setDeviceName(user.fineUserName);

hypertrackSdk.setDeviceMetadata({ region: 'Bay Area', manager: 'William Hill' });

Request permissions

HyperTrack needs access to device's geolocation and motion sensors to detect its position. Although you can use third party libraries to present the dialog, sdk has convenience method for it.

hypertrackSdk.requestPermissionsIfNecessary();

Resolve blockers

HyperTrack SDK requires some preconditions to track reliably. Since those vary across platforms and versions, we recommend using Blockers API to get the list of things to be resolved. Use getBlockers SDK method to get them. If the result is empty - you can navigate users to the screen, that has tracking feature, otherwise show an appropriate prompt, using blocker properties and nudge customer to resolve the issue, by invoking blocker.resolve(). The following action is context dependent, e.g. in the case of disabled geolocation an appropriate settings page will be opened with location switch been highlighted. Possible usage might look similar to shown below.

hypertrack.getBlockers(

function(blockers) {

let dialogConfig = [];

blockers.forEach(blocker =>

let menuItem = {

title: blocker.userActionTitle,

buttonName: blocker.userActionCTA,

onClick: function() {blocker.resolve(success, error);},

actionExplanation: blocker.userActionExplanation

};

dialogConfig.push(menuItem);

);

if (dialogConfig.length) showErrorDialog(dialogConfig);

},

function(error) {

console.log("Can't get blockers due to the error: " + error);

}

);

Tag locations with geotags

Some places are more important then the others, so you can mark them on map, creating geotag when specific action in your app happens (e.g. delivery is marked done or driver confirmend pickup)

// Tag the geolocation of app action

hypertrackSdk.addGeotag({"action": "Login"}, null,

function(location) {

console.log("Created geotag at lat=${location.latitude}, long=${location.longitude}.");

},

function(err) {console.err("Can't create a geotag. Error code: " + err);}

)

If you already know the address, where action is supposed to happen, you can specify it to analyze the deviations

// Tag the geolocation of app action

const expectedLocation = {latitude: 35.0476912, longitude: -90.0260493};

hypertrackSdk.addGeotag({"action": "Login"}, expectedLocation,

function(location) {console.log("Created geotag within ${location.deviation} meters from expected");,

function(err) {console.err("Can't create a geotag. Error code: " + err);}

)

Prepare for App Store and Play Market submission

Read the Prepare for App Store submission section of iOS SDK guide and Get approved for the background location access section of Android SDK guide.

Tracking your device

Once you integrated the SDK into your app, you can start tracking your device.

In order to test and verify your SDK integration, you can use either PlayGround in the Dashboard or call Devices and Trips APIs from your server.

• You can start tracking your device with the API
• You can create trips with destination
• You can also create trips with geofences

Dashboard

Once your app is running, go to the Dashboard where you can see a list of all your devices and their live location with ongoing activity on the map.

You are all set

You can now run the app and start using HyperTrack. You can see your devices on the dashboard.

SDK integration examples

To learn more about SDK integration examples, you may visit these resources:

• QuickStart app
• Use case sample apps

Frequently Asked Questions

What API levels (Android versions) are supported?

Currently we do support all of the Android versions starting from API 21 (Android 5.0 Lollipop).

Why do I have persistent notification on my app?

HyperTrack SDK by default runs as a foreground service. This is to ensure that the location tracking works reliably even when your app is minimized.

A foreground service is a service that the user is actively aware of and isn't a candidate for the system to kill when it is low on memory. Android mandates that a foreground service provides a persistent notification in the status bar. This means that the notification cannot be dismissed by the user.

How do I handle custom ROMs?

Smartphones are getting more and more powerful, but the battery capacity is lagging behind. Device manufacturers are always trying to squeeze some battery saving features into the firmware with each new Android release. Manufactures like Xiaomi, Huawei and OnePlus have their own battery savers that kills the services running in the background.

To avoid OS killing the service, users of your app need to override the automatic battery management and set it manual.

To inform your users and direct them to the right setting page, SDK shows a special promt on requestPermissionsIfNecessary() invocation.

Unfortunately whitelisting can't be performed programmatically. So you need to always rely on user performing particular action.

In that case the only way to achieve service reliability is manual setup. E.g. for Oxygen OS (OnePlus) you need to select Lock menu item from app options button in Recent Apps view:

Why does HyperTrack notification show even after my app is terminated?

The HyperTrack service runs as a separate component and it is still running when the app that started it is terminated. That is why you can observe that notification. When you tracking is stopped, the notification goes away.

How does tracking work in Doze mode?

Doze mode requires device to be stationary, so before OS starts imposing power management restrictions, exact device location is obtained. When device starts moving, Android leaves Doze mode and works regularly, so no special handling of Doze mode required with respect to location tracking.

What is AAPT: error: attribute android:foregroundServiceType not found?

If build fails with error like AAPT: error: attribute android:foregroundServiceType not found that means that you're targeting your app for Android P or earlier. To fix this update your build tools and set the target platform as Android 10 (target SDK level 30). Although there are other workarounds to fix the build still targeting earlier versions, starting from Android 10 Google imposes additional restrictions on services, that access location data while phone screen is turned off, so the drawback will be tracking gaps on devices that run Android 10 or later.

Why doesn't setting device metadata and name work in SDK?

Devices API or in PlayGround take precedence over SDK methods in setting device name and metadata. If you used either Devices API or PlayGround, these SDK methods setDeviceMetadata and setDeviceName will not modify device metadata and name.

Can I test functionality without actual movement

Although HyperTrack SDK ignores mocked locations by default, you can use standard emulator, that comes with Android Studio. Check the official manual on how to use it. All the emulators have (Emulator) suffix appended to the device-hardware field, so they can be easily identified, if you need it to distinguish between them and real devices.

caution

Make sure the mock data, you feeding to the SDK, looks real. Instant teleport from Delhi to New York doesn't make sense, so those values will be ignored by processing logic, that is present on HyperTrack platform. Make sure you set desired start location before turning the traking on.