Overview

Device Licenses allow manufacturers to conditionally enable features based on Digital Products and Subscriptions sold to End Customers.

There are three main use cases manufacturers need to handle, based on the type of products they care to support:

Physical Products (Hardware as a Service) - The device should only offer limited (or no) functionality until a compatible license is applied. This type of licenses is automatically generated when the End Customer purchases a Physical Product in the store and the device should operate only while this licenses is assigned. (e.g. if the End Customer stops paying - the device should stop fully functioning).
Digital Products (Feature enablement) - The device should operate with basic functionality but allow enabling more advanced features when one (or more) licenses are assigned to it.
Usage Based / Metered - Full or partial functionality of the device should be disabled by default and enabled only when this type of license is assigned to the device. Once assigned the device should enable the feature and start sending a metering telemetry to allow the platform to correctly charge the End Customer (e.g. charge by amount of miles driven).

License Flows

The flows contain 4 main cases:

Initial License assignment
License expiration update
License removal
Automated expiration

Initial License Assignment

After an End Customer purchases products from the store, they may assign a license(s) to devices. The device will be notified on pending license events via the new_licenses field returned from Send Telemetry API. When the field is set, the device should use Get License API to get the license details and Update License API to update the server once the license is successfully applied.

A device will know what action to do on the license (add / remove / update) based on the add, removeand updatefields returned by Get License API

License Expiration Update

For licenses tied to recurring products, the license information will contain an expired_atfield, signifying when this license should be automatically disabled.

On every recurring payment cycle, Xyte will automatically charge the End Customer. On successful charges, the expiration should be extended by the paid cycle length. The Send Telemetry API performed by the device will have the new_licensesfield set. The device should call the Get License API, update the expiration time of an active license and notify the server of the successful update by calling the Update License API.

License Removal

Licenses can be revoked from devices due to various events in the system, e.g. Payment failures, Subscription cancellations, users moving a license between devices (when allowed), etc.

When a license is removed from a device, the next call to Send Telemetry API will have the new_licensesfield set. The device should call the Get License API to get details on the removed license, disable it locally and update the server via the Update License API.

Until a device updates the server that it has removed a license, it will not be available to be transferred to other devices.

Automated Expiration

Licenses with expiration (created from recurring products) have the expired_at field set. In normal operation, the system will automatically charge End Customers on every billing cycle and update the device on extending the expiration until the next billing cycle (with some extra grace time).

When a device detects that an active license expiration time has passed, it should automatically disable the license locally. This measure is meant to combat possible issues of the End Customer assigning a license to a device and disconnecting it from the network - thus preventing the server from notifying a device of the need to remove it.

License states

During its lifetime a licenses can undergo multiple state changes as it is bought, enabled, transferred and cancelled. Normally a license will always be initiated in the available state, except some edge cases.

Beyond the license state, each licenses can be assigned to a single device. Unassigned licenses can be assigned via the End Customer Portal, APIs or automatically during the eCommerce flow.

State	Description	Initiated By
available	License available, if attached will be sent to the device for confirmation	Server
inuse	The device has confirmed the license has been activated.	Device
renew	Server requested device to reload license data (usually `expired_at`changed)	Server
remove	Server requested license removal, waiting for device confirmation	Server
removed	License removal acknowledged by device. The license can be unattached and moved to another device.	Device
disable	Server requested license disablement, waiting for device confirmation	Server
disabled	License disablement acknowledged by device. The license cannot be used.	Device
error	Unknown error state, support team intervention required.	Server & Device

Platform licenses

Platform licenses are a special type of license that can be used by Partners to enable commands/telemetries/etc from the Server side. E.g. a license can disable the "premium feature" command from the End Customer Portal, without the device even supporting license management (or knowing the license was assigned).

These licenses do not wait for device confirmation and automatically skip all the pending states, such as: remove& disable