Ionic Native wrapper for the HyperTrack cordova plugin

This is a guest post by Daniel Olivares

At my company, we develop custom software solutions for customers, whether they need a mobile or web app for their business, or basically anything that involves technology. A large amount of the projects that we have developed have one thing in common: location awareness and tracking. This is why we have been experimenting with HyperTrack.

We are currently building an app which heavily depends on asset tracking, so we naturally were forced to make a choice: either we developed all of the location features in-house (which would take away precious time from us to actually develop what makes our project what it is), or we looked for a provider "that just works". When we found HyperTrack, the second option was a clear winner, at least for some of our needs. This post covers how we use HyperTrack in our Ionic Native mobile apps.

Ionic for hybrid mobile apps

Most of our mobile apps are hybrid. This is a no brainer for most of the cases that need rapid, compatible development cycles (search for ‘hybrid vs native apps’ to understand pros and cons). We really like Ionic and have been using it for years now. Ionic is an open source framework for building hybrid mobile apps easily, by using well-known technologies such as Angular, Javascript (and now Typescript - more on that later), HTML and CSS for developing the app. With Cordova support, Ionic apps can leverage native device capabilities, like background location.

Ionic is not only a framework for developing hybrid apps - they also provide Cloud services (for authentication, push notifications, rapid prototyping, testing, hot code updating, native cloud builds, analytics for your apps, etc), Ionic Creator (for prototyping apps with a simple drag and drop experience), Ionic View (for sharing apps easily). In this post, we will focus on native device capabilities with Ionic Native.

Ionic 1 = AngularJS + Cordova plugins

When developing Ionic 1 apps (or even just a plain simple Cordova app with AngularJS) with native device capabilities, you needed to use a Cordova plugin. A simple way to do that is through ngCordova: a collection of AngularJS extensions on top of the Cordova API. If you needed to access, for example, the native Calendar capabilities, you could use the calendar plugin with an ngCordova wrapper.

Ionic 2 = Angular 2 + Ionic Native = ❤

This year Ionic released v2 for their framework, replacing AngularJS with Angular 2+. When I found out that Ionic 2 was going to use Angular 2, I was confused about how it would work with Cordova plugins, since Angular 2 was completely rewritten to use Typescript (a typed superset of Javascript) instead of vanilla Javascript. Sure, Typescript brought nice features for developers (e.g. type checking, more object oriented programming, observables, etc), but the ngCordova wrappers would not work with it.

This is when I found out about Ionic Native, the Typescript wrapper for Cordova plugins. If you use Cordova + Angular(2+) + Typescript, Ionic Native does what ngCordova did the past. I encourage you to take a look at their documentation, where they explain how it works, along with documentation for over 170 Ionic Native wrappers of Cordova plugins.

HyperTrack on Ionic Native

I developed an Ionic Native wrapper for HyperTrack, so that we and other developers can use HyperTrack in their Ionic 2 mobile apps easily. The process was not that hard, since Ionic Native has a nice guide for adding your own wrapper to the Ionic Native codebase. If you want to take a look at how the process of the creation of the wrapper was for me, you can take a look at my pull request.

I followed the documentation of the HyperTrack Cordova plugin and replicated its methods into the Ionic Native wrapper. Put in another way, I mapped the same methods of the Cordova plugin with the syntax expected by Ionic Native, and pushed it to their codebase.

To use the HyperTrack Ionic Native wrapper, I would recommend reading the wrapper documentation. If you are too lazy and don’t want to leave this blog post, I am summarising the instructions below.

How to use

Step 1: Install the HyperTrack Cordova plugin and the Ionic Native wrapper.

$ ionic cordova plugin add cordova-plugin-hypertrack
$ npm install --save @ionic-native/hyper-track

Step 2: Get your HyperTrack keys by signing up here, and add your HyperTrack publishable key to your project's config.xml.

<preference name="HYPERTRACK_PK" value="YOUR_PUBLISHABLE_KEY" />

Step 3: Include HyperTrack in your app’s module.

import { HyperTrack } from '@ionic-native/hyper-track';
...

@NgModule({
  ...

  providers: [
    ...
    HyperTrack	

  ]
})

export class AppModule { }

Step 4: Use HyperTrack in your component.

import { HyperTrack } from '@ionic-native/hyper-track';

constructor(private hyperTrack: HyperTrack) { }

// Check if app has location permissions enabled
this.hyperTrack.checkLocationPermission().then(response => {
  // response (String) can be "true" or "false"
  if (response != "true") {
    // Ask for permissions
    this.hyperTrack.requestPermissions().then(response => {}, error => {});
  }
}, error => {});


// Check if app has location services enabled
this.hyperTrack.checkLocationServices().then(response => {
  // response (String) can be "true" or "false"
  if (response != "true") {
    // Request services to be enabled
    this.hyperTrack.requestLocationServices().then(response => {}, error => {});
  }
}, error => {});


// First set the current user. This can be done via getOrCreateUser() or setUserId()
this.hyperTrack.setUserId("xxx").then(user => {
  // user (String) is a String representation of a User's JSON

  // Once the user is set, you can start tracking.
  this.hyperTrack.startTracking().then(userId => {}, trackingError => {});


  this.hyperTrack.createAndAssignAction('visit', 'lookupId', 'address', 20.12, -100.3).then(action => {
    // Handle action. It's a String representation of the Action's JSON. For example:
    // '{"eta":"Jul 17, 2017 12:50:03 PM","assigned_at":"Jul 17, 2017 12:34:38 PM",,"distance":"0.0",...}'
  }, error => {});


  // You can complete an action with completeAction() or completeActionWithLookupId()
  this.hyperTrack.completeAction('action-id').then(response => {
    // Handle response (String). Should be "OK".
  }, error => {});


  this.hyperTrack.getCurrentLocation().then(location => {
    // Handle location. It's a String representation of a Location's JSON.For example:
    // '{"mAccuracy":22.601,,"mLatitude":23.123456, "mLongitude":-100.1234567, ...}'
  }, error => {});


  this.hyperTrack.stopTracking().then(success => {
    // Handle success (String). Should be "OK".
  }, error => {});

}, error => {});

As you can see, if you know how the HyperTrack Cordova plugin works, and if you know some TypeScript basics, you can see the similarities with the HyperTrack Cordova plugin. This wrapper just makes it possible to use it with Ionic 2.

Contribute to the project

The HyperTrack wrapper for Ionic Native is in beta, and we would love to have you try it out. You can submit issues or questions to the Ionic Native repository on Github.

The Cordova plugin itself is constantly being updated and some features are still missing, especially for iOS. This wrapper will evolve as the Cordova plugin does, and you have the opportunity to contribute to both the Cordova plugin and the Ionic Native wrapper. There’s a reason it is open source 💪.

Developing the Ionic Native for HyperTrack helped me gain a better understanding of HyperTrack, and the Cordova plugin. I have always believed that there’s no better way to learn than actually reading the source code, and doing something with it in practice. To achieve the development of the wrapper, I had to do both. I hope this helps you to bring the amazing features of HyperTrack to your app. Happy coding 💻.