Ionic Capacitor
Ionic Capacitor HyperTrack SDK is a wrapper around native iOS and Android SDKs that allows to integrate them into Ionic Capacitor apps.
Requirements
Basic integration
Migrating from older versions? Check the Migration guide
Add HyperTrack SDK to your project
We constantly work on making our SDKs better, so make sure you have the latest version. You can get it in the changelog here.
npm install hypertrack-sdk-ionic-capacitor
iOS
Install the native HyperTrack SDK through CocoaPods:
cd ios
pod install
Enable Background Modes
Add purpose strings
Set up silent push notifications
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 improves robustness. This also enables HyperTrack Trips to start and stop tracking automatically when trip starts and ends. For this purpose, the iOS SDK uses APNs silent remote notifications and Android SDK uses FCM silent notifications.
Set the publishable key
Get your publishable key from the Setup page.
Grant the permissions to the app
Start tracking
Now the app is ready to be tracked from the cloud.
You will need the device id to start tracking, check the Identify devices section for instructions on how to get it.
Follow the Start Tracking tutorial to learn how to control device tracking from your backend.
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.
Prepare for App Store and Google Play submission
Recommended additional steps
Identify devices
All devices tracked on HyperTrack are uniquely identified using UUID. You can get this identifier programmatically in your app by calling getDeviceId().
The device ID is changed on each app re-install or clearing the app data
Another approach to identification is to tag devices with names that will make it easy to distinguish them on HyperTrack Dashboard.
HyperTrack.setName("Device name")
You can additionaly tag devices with custom metadata (and filter them in the Dashboard using metadata fields). Metadata should be representable in JSON.
HyperTrack.setMetadata({"key": "value"})
Handle errors
Use the getErrors() or subscribeToErrors() to make sure that when the driver navigates to the screen where tracking is supposed to happen, there are no blockers that can prevent that.
You can use subscription API to be able to react immediately when errors come up:
HyperTrack.getErrors().forEach((element) => {
switch (errors) {
...
}
});
const errorsSubscription = HyperTrack.subscribeToErrors { errors in
errors.forEach((element) => {
switch (error) {
...
}
}
}
// Call .remove() to unsubscribe
errorsSubscription.remove()
Check the API docs to get the full list of errors.
Migration Guide
The release of HyperTrack Ionic Capacitor SDK 2.0.0 is a major update that has a bunch of new improvements. We highly recommend upgrading, but please note that there are a few breaking changes.
The key advantages of the new version are:
User-friendly API:
The revamped static API is the highlight, standing out for its unmatched simplicity, ease of use, and conciseness.
Enhanced Responsiveness & Speed:
Experience quicker time to the first location and minimized system latency.
Superior Tracking Performance:
Delight in the improved quality, granularity, and accuracy of the location event stream.
Optimized Battery Efficiency:
Our refined tracking algorithm reduces unnecessary network calls, preserving battery life.
Decreased Binary Size:
The library's size optimization ensures a more compact overall app footprint.
You can check the detailed Changelog here
The key breaking changes are:
Setting the publishable key
There is no need to initialize the SDK by setting publishable key. The Basic integration instructions decribe the new way of setting it.
Static API
The SDK API was fully redesigned to be more ergonomic and to require less code to use.
All the API methods can be accessible at any time from any place in the app by calling them on the static HyperTrack class.
Check the Changelog for the renamed methods.
Motion activity permission is no longer required
While the SDK still can benefit from Motion activity data to get better accuracy, requesting this permission is now optional.
The corresponsive items of HyperTrackError are removed from the API.
SDK Sync
The SDK is now automatically syncs with the servers, so the sync() method is not needed. You can safely remove it and all the logic related to it.
Reference
For a full SDK API reference see HyperTrack Ionic Capacitor SDK Reference
SDK integration examples
To learn more about SDK integration examples, you may visit these resources:
Frequently Asked Questions
Updated 5 months ago