Migrating from Actions v1 to v2 APIs

We recently announced the new version of the HyperTrack Action API, which considerably simplifies the actions use model. Developers who tested the pre-release version were able to build their use cases within minutes.

In this post, we describe what's new with the Actions v2 APIs and what you need to do to move to them.

What's new with the V2 APIs

Overall API calls in a typical integration have reduced by half from v1 to v2. That means you have that much lesser code to write and multiplicatively lesser states to manage. Furthermore, it implies that we can provide more reliable data with lesser dependence on user behavior.

Fewer APIs to integrate

  • V1 had two units of tracking, users and actions. This was confusing for developers as the same use cases could be built in multiple ways, with different implications. V2 reduces it to one basic unit of tracking, actions.
  • V1 left it to developers to manage the start and stop of tracking for users, independent of actions. This would often lead to tracking their users when it was not required and gaps when tracking was required. V2 removes this burden for developers by automatically starting to track when any action is created for the user and automatically stopping when all actions are completed.
  • V1 let developers create, assign and complete actions. The choice of when to create and assign an action, and how that impacts tracking, was confusing and had incremental value. V2 merges create & assign actions into just create, so developers simply need to create and complete actions.

More automation, lesser state to manage

  • V1 did not have rules to automatically create and complete actions with a recurring schedule. V2 automates this with rules. Developers can now define rules to automatically create actions in the future based on time & place. Developers can also define rules to automatically complete actions (set at the time of creating that action), removing the need for an explicit complete action API call.
  • V1 provided geofencing as events. It was left to the developer to create and complete actions based on those events. V2 automates this to automatically create and complete actions when users enter and exit places. Now you can specify a list of places and automatically track actions when users visit any of those places. In addition, developers can define their own custom polygons for geofences.
  • V1 left it to developers to create and complete actions based on a set time. Creating actions at a fixed duration before expected completion or completing actions at a fixed duration after creation, was left to developers to manage on their own. V2 automates this by letting developers specify time parameters to create and complete so HyperTrack can manage it for them.

More reliable data, lesser dependence on user behavior

  • V1 expected all actions to complete in the order assigned. This caused unexpected behavior when actions had no expected place and complex behavior when actions were completed out of order. V2 assumes that only the actions with expected places would be completed in the order created, automatically handles the sequence when actions are completed out of order and simplifies expected behavior for ETAs and tracking experience.
  • V1 provided distance, duration and routes from created to assigned to completed. Due to overlaps in multiple actions, this data was causing confusion for developers. By default, v2 provides distance, duration and routes from completion of one action to completion of the next one. This makes data additive and easier to parse for most use cases. Power users can use additional parameters and timestamps to retreive data differently as needed.
  • V1 had no way for developers to purge incomplete actions, which would adversely impact the tracking experience, ETAs and mileage of other actions. V2 allows developers to purge actions by automatically canceling them after a set duration.

Migrating from v1 to v2

We understand that many of you have production systems running on v1. We are fully committed to ensuring no disruption to your usage. If you wish to move to v2, here is a quick migration guide.

  • Update the SDKs (iOS/Android) in your user's app to v0.7.x. These SDKs support the v2 APIs.
  • Remove startTracking and stopTracking API calls from your app. HyperTrack automagically starts and stops tracking when there is a pending action.
  • If you are using HyperTrack to track your users through the day, set up recurring track_through_the_day actions (that gets created for each user at a set time and is completed at a set time). Visit dashboard to set up these actions. You can alternatively use APIs to setup rules to autocreate and/or autocomplete actions.
  • If you are creating granular actions, call the v2 createAction and completeAction APIs. Make sure that you don't call assignAction APIs anymore.
  • While creating these actions, consider using the autocomplete parameter to autocomplete actions immediately upon creation, at a set time, at a fixed duration after it is created or expected to complete, or upon entering/exiting a place. This could help you remove an extra step your users need to make in the app to complete an action.
  • If you pass an address string for the expected_place parameter when creating actions, the createAction API will fail if the address doesn't geocode. Do add handling for such cases.
  • If you are using APIs to consume data, call the v2 mileage and Placeline APIs.

We would be happy to work closely with you to migrate your integration. Reach out to us if you like to further discuss the migration.

Impact on pricing

We recently announced the new pricing plan with multiple tiers of fixed monthly fee with limits for number of actions. Key features of the new pricing plan includes a Free Forever tier, unlimited users on all tiers, larger sandbox for testing, and unlimited consumption of actions.

As mentioned earlier, we are committed to no disruption for existing customers.

  • Customers on the old pay-per-user and pay-per-action plans may continue to remain on those plans for as long as they want
  • Customers on the old free-to-view plan may continue to remain on the plan for as long as they want. All users will automatically migrate to track-through-the-day and they may be tracked live with their tracking history through your HyperTrack dashboard.
  • Customers can move to one of the newer plans by visiting the billing page on your dashboard.
  • The new pricing plans are favorable for customers tracking users through the day and programmatically using the data, events and visuals for such users. Earlier, every user who was active for any period of time during the month was priced at $5. Now, each active day of tracking for a user is counted as one action, thus making it 75-90% cheaper.

We hope the simplified use model expands your imagination of what you can build with movement data, and makes is possible to build it easily within minutes. We are constantly iterating on making our APIs useful, simple and automatic. We would love to hear from you about the new APIs and what more would you like to see.