API concepts and scope proposal

[paddybyers]

Overview

This issue proposes updates to the API for the initial release of these SDKs. Its focus is the publisher API; the subscriber API is simpler, and should follow naturally once the publisher API concepts are finalised.

API concepts

AssetPublisher

This is the entity that is constructed and typically survives for the lifetime of a publisher app. It maintains the Ably connection, and makes use of NavSDK resources as required. Its principal attributes, fixed for the lifetime of the AssetPublisher instance, include the AblyConfig (which in turn includes clientId) plus any other fixed metadata about the publisher.

Asset

This naming is provisional - we might want this to be Delivery or Track or whatever. The idea is that this represents a period in which a specific asset is tracked and its position broadcast. But given the other terminology already adopted I think Asset is probably the best fit.

Typically an Asset will be a single delivery; but could also include a rider: for example, in the use case of tracking rider locations when not on a delivery, for the purposes of assigning deliveries.

An Asset has a unique ID and fixed metadata.

An Asset can have multiple subscribers, which can vary over the lifetime of the Asset. The rights that permit an individual subscriber to view an in-progress Asset are valid for the lifetime of the Asset.

An Asset has a destination location, but this can be varied during the active time of the Asset.

An Asset corresponds to a single Ably channel, and the Ably channel name is canonically derived from the Asset ID.

An Asset has a lifecycle, in that publishing on the channel begins when the Asset is created, and stops when the Asset ends.

An AssetPublisher, at any given time, may have multiple Assets active, and the present location of the AssetPublisher may be published on the channel for each Asset.

The Assets associated with an AssetPublisher are ordered naturally as a result of the order of their creation. Assets may be ended out of order (eg in the case that a delivery is cancelled, for example).

Asset location updates: determining location resolution

Tracking is performed against a specification of the tracking Resolution - this captures the positional accuracy and update frequency. A Resolution captures the following parameters:

• priority: loosely analogous to Android’s LocationRequest.priority (https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest#setPriority(int)); this captures the requirement for positional accuracy - or the expense to which the publisher is willing to go to obtain accuracy - and will usually determine the sensor(s) used to obtain the location.

• maxDelay: this is an indication of the target currency or staleness of a location update, expressed in milliseconds. It is used to govern the frequency of updates requested from the underlying location provider, and the frequency of messages broadcast to subscribers.

• minDisplacement: this is an indication of the positional granularity required. Location updates whose position differs from the last known position by a distance smaller than the minDisplacement will not be broadcast. The minDisplacement is used to configure the underlying location provider and also to filter the broadcast of updates.

The publisher obtains location updates from the local platform, and publishes those to the Asset, based on a current targetResolution. The targetResolution governs the accuracy of location updates (for example by determining the sensors used) and the frequency of location updates being published. The publisher specifies the targetResolution for each Asset; it can be specified on construction of the Asset, and can vary it during the active lifetime of a Asset.

The aim in most practical situations is for targetResolution to vary dynamically based on circumstances; this might be based on parameters known by the publisher (such as proximity to destination, or the current power state of the device) but may also be based on the existence, or preferences, of the subscribers to the track. The tracking SDKs therefore incorporate the following additional concepts:

• subscriber requestedResolution: this captures the preference of a subscriber for update resolution. A subscriber’s preference might be a consequence of the subscriber simply existing, but might also depend on the subscriber’s circumstances (eg the zoom level of the map that the subscriber is using the display updates).

• ResolutionPolicy: this captures the strategy by which the various Resolution requests/preferences are translated into a targetResolution. By providing a ResolutionPolicy a publisher specifies the rules that govern how the targetResolution should be updated in response to changing circumstances. A ResolutionPolicy may be specified on construction of an Asset.

If a subscriber wishes to indicate a requestedResolution, then this is done via the Subscriber API; the effect of this is to entering presence on the Asset channel and providing the requestedResolution in its presence data. The publisher’s ResolutionPolicy can obtain occupancy, requestedResolutions, and use any other strategy, to update the targetResolution as required.

Impact on current API

The most obvious changes that would be required to the existing API under this proposal are:

• changes to terminology;

• creation of an Asset as a distinct interface, with a Builder; moving some of the current AssetPublisher.Builder options into Asset.Builder; addition of APIs on the AssetPublisher to add and remove Assets.

• the current BatteryConfiguration, associated with an AssetPublisher, will become ResolutionPolicy and be associated with an Asset.

• assetMetadataJson / tripMetadataJson: I think we will need freely structured metadata associated with the AssetPublisher, and freely structured metadata associated with the Asset.

• delivery: these will become associated with an Asset. destination should be structured as lat/long. There is no need for destination.trackingId - this will be the Asset.id - and other details of the delivery (eg a transaction Id) would be part of the Asset metadata.

Scope of preview releases

I propose that the Asset and Asset.Builder API are created now. For Preview 1 then perhaps we do not include the addAsset / removeAsset APIs in AssetPublisher but instead allow the AssetPublisher.Builder to be provided with an Asset.Builder. Preview 2 can include the ability to support multiple concurrently-active Assets.

Implementation of Resolution and some simple ResolutionPolicys need to be included in Preview 2.

┆Issue is synchronized with this Jira Task by Unito

[lmars]

Some thoughts based on reading through this without the context of the currently implemented API (so apologies if it departs from what is already agreed):

An Asset has a lifecycle, in that publishing on the channel begins when the Asset is created, and stops when the Asset ends.

Assets may be ended out of order (eg in the case that a delivery is cancelled, for example).

I find it a little awkward that an Asset has a temporal component, I wonder if there should be two distinct concepts:

• Asset - a physical object (e.g. "a bag of Nando's food", "an IKEA chair" or "a rentable bicycle")
• Journey - a spatiotemporal concept representing the movement of an Asset (e.g. "a delivery of <an IKEA chair> from <point A> to <point B> starting at <time T>" or "the usage of a rented bicycle from <point A> starting at <time T>")

So basically an asset is an object that can be the subject of one or more journeys (although only one journey at any given time).

I say Journey rather than Delivery because I'm thinking that not every asset being tracked is necessarily a delivery (like in my example of a rented bicycle being used that isn't necessarily being delivered anywhere).

AssetPublisher

I wonder whether Tracker is a more descriptive term for this?

So a Tracker is something that:

• has an immutable identifier (which will be the Ably clientId)
• has a current location
• can be associated with one or more journeys at any given time

A Tracker could be:

• a driver's phone that is publishing updates whilst driving to deliver one or more food orders
• an IoT device attached to a shipping container containing multiple delivery parcels
• an IoT device attached to a rentable bicycle

[QuintinWillison]

Thanks, @paddybyers! 😁

On reflection, I agree with @lmars around the temporal component which perhaps conflates too many concerns together under Asset. Perhaps we could normalise the entities involved in any given journey being tracked to:

• Asset, perhaps sharing common properties with Driver via super-interface
• Driver, perhaps sharing common properties with Asset via super-interface
• Journey, always has a Driver, sometimes has an Asset

[ably-sync-bot]

➤ Ivan Kavalerov commented:

Notes from our call:

• Driver will be explicit separate entity
• Delivery to be used as terminology for single asset being delivered.
• Quintin Willison will have a go in implementing this later today and we can review/discuss tomorrow.

[mattheworiordan]

For context, I looked at what others were doing, see https://ably.atlassian.net/wiki/spaces/product/pages/863764481/Competitive+fleet+tracking+solutions.

In the context of what we're providing as a product, I believe went with Realtime Asset Tracking.

Realtime for obvious reasons, we enable this live experience. Asset because you an asset can be an item, a driver, a delivery bot, a bike etc. Tracking because we enable the tracking of the item.

Re: @lmars comments:

• I think we should avoid making this about drivers. This is more generic than that.
• The Asset has a broadcaster role, but is an asset
• The Asset can be tracked, via Ably, if it's broadcasting it's position.
• The Asset may be on a journey, but may not, it could just be stationery.

Our SDKs should IMHO avoid talking about deliveries, drivers, etc.

If we want this to be a product, it is up to us now to crack the hard naming stuff (greatest rewards lie on the hardest path, and there are only two hard things in CS, cache & naming - https://martinfowler.com/bliki/TwoHardThings.html), and make this useful beyond just customers in the delivery space. Going back and changing this later will be impractical because we'll need to tell existing customers to change their implementations.

[kavalerov]

So, first of all, this doesn't represent the latest state of the interface discussion - latest changes are actually made here right now.

With regards to the naming I did some research over the weekend looking at other solutions. Most of them put "device" in the centre of their APIs - so they are tracking devices, not assets, and the logic for handling multiple assets associated with one device is then on the customer (Hypertrack, Radar, Here Tracking).

I think we should stick with our current assumption that there can be multiple assets tracked by one publishing SDK. We also should be able to track the driver/rider, which is, effectively, tracking the device the SDK is running on.

Because of the above, I think we should do the following:

• Largely keep the current SDK structure from here
• remove "Delivery" class. The only thing that makes it different from "Trackable" is destination, and we have just discussed on Slack that destination is optional, and probably should live within "Trackable"
• Rename Courier to Device. This has two advantages: removes reference to specific use case, but keeps the logic clear - we are really tracking Device here. As a device, it also should be the entity storing device specific properties, most importantly - "mode of transportation".
• Change references to "delivery" in method names to "Trackable" - this will make Trackable the basic unit of the SDK

@QuintinWillison @paddybyers WDYT?

[QuintinWillison]

@kavalerov My understand was, with my current structure but this new naming, that:

• both Delivery and Device inherit from Trackable
• a publisher only ever has exactly one associated Device instance
• a publisher can, at any given time and varying over its lifespan, have zero or more Delivery instances
• a Device is a continuum, so will only ever have an implicit destination if we have an active/current delivery which does have a destination (i.e. adopting/inheriting the destination of that delivery for the duration of time that that delivery is active/current)
• a Device has a "transportation mode" property (not needed for a Delivery)
• a Delivery has an optional "destination" property (not needed for a Device)

Therefore I think we do need a Delivery concept also.

[kavalerov]

Just had a chat with @QuintinWillison (and @paddybyers for a bit).

What we have discussed and decided for now (just updating and reflecting the notes from above):

• Remove Device (formerly Courier) as a separate entity altogether. This simplifies logic (Asset Publisher just tracks Trackables that you add to it, no Trackable is "special" => this clarifies billing (per Trackable) and also gives user control over what is tracked and when)
• Remove Delivery and move destination to Trackable - adding additional entities doesn't add too much value. Term Trackable is also really good - it is more specific than Asset, and less overloaded, and it does convey exactly what entity it represents.
• Make transportationMode a property of the AssetPublisher. This will be set in the Builder first, and then can be changed dynamically during tracking.

@QuintinWillison please let me know if I didn't capture something properly.

[kavalerov]

@paddybyers please also me or @QuintinWillison know if you want to chat about the above ^

[QuintinWillison]

Thanks @kavalerov ... I'm making changes now and will push up commit(s) to the PR soon.

[mattheworiordan]

Sounds sensible all 👍 Nice one