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
ACME's SHORTCODE is abcd
CloudID of the device abcdDl8z6CASzFpiojfwy9kk — the 4-character SHORTCODE followed by 20 characters unique to the device
The QR URL will be: https://cloud.acme.com/c/abcdDl8z6CASzFpiojfwy9kk

📘
About your SHORTCODE
Your SHORTCODE is the 4-character manufacturer prefix shown at Settings → Hardware Keys → SHORTCODE (Provision page). Every CloudID begins with it, so a full CloudID is always 24 characters: the 4-character SHORTCODE plus 20 characters unique to the device.
Two things to know before you print labels:

It never changes. The SHORTCODE is assigned once, when your Xyte tenant is created, and cannot be edited afterwards — it is embedded in the CloudID of every device you have already registered. It is safe to hard-code into firmware and label printing permanently.

It belongs to one tenant. If your organization has more than one Xyte tenant, each tenant has its own separate SHORTCODE. Always use the SHORTCODE of the tenant your devices actually register into. A QR code built with another tenant's prefix will not resolve to a device, and the scan will fail.

If you are unsure which tenant your production units register into, read the cloud_id off a unit coming off the line — its first four characters are the SHORTCODE you should be printing.

🚧
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

Open the End Customer Portal on a mobile device
Login to the Organization where you want to claim the device
Select the Space you are currently in
Click "Scan QR Code" button at the bottom
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 generated portion should be a string of 20 characters and must be unique for each device created by the manufacturer. CloudIDs are compared case-sensitively, so whatever the device sends must match the QR code exactly.

Combine the MAC and Serial numbers as strings and use a digest algorithm (e.g. SHA 256) on the string, then take the first 20 characters of the digest.

Example

Given

Xyte manufacturer prefix: abcd (Settings —> Hardware Keys —> SHORTCODE)
QR Prefix: https://cloud.acme.com/c/

Step #1 - Generate the unique string

base = MAC_address + Serial_number

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

= 1685e896317aa9ed0828

Step #2 - Prepend the SHORTCODE

abcd + 1685e896317aa9ed0828

= abcd1685e896317aa9ed0828

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

https://cloud.acme.com/c/ + abcd1685e896317aa9ed0828

= https://cloud.acme.com/c/abcd1685e896317aa9ed0828

Step #4 - Generate the QR