Virtual Devices

When working with cloud-to-cloud scenarios, it is often impossible to embed the Tracking API authentication using deviceId and deviceSecret into the devices. Virtual Devices provide a method for authenticating using external device IDs.

Generating a Virtual Device

The API request to generate licenses for virtual devices is almost identical to the standard API request for generating physical device licenses except that it includes a devices array containing the externalIds to be associated with each virtual device. The virtual device externalId is project-specific.

Create device licenses

curl -X POST \
  https://tracking.api.here.com/registry/v2/{projectAppId}/devices \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "devices": [
      {
        "id": "my-first-device"
      },
      {
        "id": "my-second-device"
      }
    ]
}'

As with standard license creation, this is a batch API and the response will be the jobId which can be used to retrieve the results.

{
  "jobId": "344a17a4-1b19-4420-bb6f-8400b87071fd"
}

Check job progress

curl -X GET \
  'https://tracking.api.here.com/registry/v2/{jobId}/status' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json'

Retrieve licenses

curl -X GET \
  'https://tracking.api.here.com/registry/v2/{jobId}/results' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json'

Sending telemetry as a virtual device

In cloud-to-cloud scenarios, the device being tracked does not have a direct connection to the Tracking API. In this case, an intermediate service must be able to post on behalf of the device. This can be the primary contact cloud or a dedicated forwarding service.

The bearer token of the device owner is used to send the data along with the externalId (provided at the time of license creation) and the project's appId.

Get token for owner

curl -X POST \
  https://tracking.api.here.com/users/v2/login \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "{userEmail}",
    "password": "{userPassword}"
}'

Send data 'on behalf of' a device

Use the owner's account access token to authorise the POST request to the ingestion endpoint:

curl -X POST \
  https://tracking.api.here.com/v3/ \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "appId": "MyAppId123",
  "id": "MyDevice1",
  "data": [
    {
      "scan": {
        "gsm": [
          {
            "mcc": 262,
            "mnc": 1,
            "lac": 5126,
            "cid": 16504
          }
        ]
      },
      "timestamp": 1569248026000
    }
  ]
}