API Reference

QR Code Claiming

Overview

To better support device claiming, manufacturers can print a QR Code on their devices or packaging, allowing End Customers to use the End Customer portal on a mobile device or any QR Scanner to easily claim devices.

Structure

The QR Code should be generated in the following structure:

https://[Partner's Cloud URL]/c/CloudID

Example:

  • For an ACME partner who's End Customer domain is set to be cloud.acme.com
  • CloudID of the device eX-N5DiKi34LdV5_qsYkEpKp
  • The QR URL will be: https://cloud.acme.com/c/eX-N5DiKi34LdV5_qsYkEpKp

🚧

Make sure that the QR generator used, encodes the string "as-is" and does not replace the URL with a shortener or tracking links. As some QR generators wrap the link into a tracking URL.

Claiming with End Customer Portal on a Mobile Device

  1. Open the End Customer Portal on a mobile device
  2. Login to the Organization where you want to claim the device
  3. Select the Space you are currently in
  4. Click "Scan QR Code" button at the bottom
  5. Scan the QR code

Claiming via regular QR Scanner

Since the URL encoded in the QR already points to the OEM's End Customer portal, once scanning the user will be redirected there. After the user sign-in or sign-up, the device with be auto claimed to their End Customer Portal.


What if we don't use CloudID for claiming?

Partners that use MAC & Serial Number based claiming, will need to generate a CloudID and make sure it is sent by the device in the Register Device API call as the cloud_id parameter.

The CloudID can be generated using the regular recommended method or by the following MAC & SN method.

Generating a Unique ID with MAC and Serial Number

The ID should be an alphanumeric string (case sensitive) of 20 characters and must be unique for each device created by the manufacturer.

Combine the MAC and Serial numbers as strings and use a digest algorithm (e.g. SHA 256) on the string to generate a unique alphanumeric and case-insensitive string of 20 characters.

Example

Given

Step #1 - Generate the unique string

**base** = MAC_address + Serial_number

Digest::SHA256.hexdigest(**base**)[0...20]

= 1685e896317aa9ed0828

Step #2 - Prepend the SHORTCODE

**abcd** + Dl8z6CASzFpiojfwy9kk

= **abcd**Dl8z6CASzFpiojfwy9kk

Step #3 - Prepend the "https://" + End Customer cloud URL

**https://cloud.acme.com/c/** + abcdDl8z6CASzFpiojfwy9kk

= **https://cloud.acme.com/c/**abcdDl8z6CASzFpiojfwy9kk

Step #4 - Generate the QR