<
- [Example](#basic-configurations-example)
- [Changing iframe size](#changing-iframe-size)
- [Example Response](#example-response)
- [Advanced Configurations](#advanced-configurations)
- [Examples](#all-examples)
- [All Configurations](#all-configurations)
- [Redirect Device Only](#redirect-device-only)
- [Redirect Host Only](#redirect-host-only)
- [Redirect Host and Device](#redirect-device-host)
- [Auto Refresh](#example-auto-refresh-with-a-delay-showing-a-custom-scan-message-and-redirect-the-scanning-device)
- [Troubleshooting](#troubleshooting)
This guide will help you to create a QR code for a website using DeviceAtlas Device Verification QR Code. The QR code snippet will allow
you to display a QR code on a website when scanned with a mobile device.
<h2 id="basic-configurations">Basic Configurations</h2>
| Query Parameter | Type | Constraints | Description |
|-----------------|---------|------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| dv-size | integer | Min: **50**<br/> Max: **500**<br/> Default: **250** | Sets the width and height of the QR code. |
| dv-json | boolean | **true** or **false**<br /> Default: **false** | This will hide and remove the iframe after a mobile scan is shown. A function called: `_deviceAssureResultReceived` will need to be defined to use the result in the originating page. |
| dv-licenceKey | string | Required for licence specific property set and extended configurations | This is required to return the properties configured for this licence and to enable extended configurations. |
<h3 id="basic-configurations-example">Example</h3>
The QR Code will be inserted in to an iframe within the div with the id `deviceassure`.
The result of the scan will be returned to the originating page using the `_deviceAssureResultReceived` function.
```html
<div id="deviceassure"></div>
<script src="https://qr-code.deviceatlas.com/v2/api/snippet.js?dv-licenceKey=<MY_LICENCE_KEY>&dv-size=200&dv-json=true"></script>
<script>
function _deviceAssureResultReceived(result) {
console.log('DeviceAssure result from iframe:', result);
}
</script>
```
---
<h3 id="changing-iframe-size">Changing iframe size</h3>
By default the iframe is created with a width and height of 500px. You can change this by adding some CSS to override the default values.
```css
/* Optional styling for the iframe */
#deviceassure-iframe {
width: 325px;
height: 325px;
}
/* Centered the contents in the QR div */
#deviceassure {
display: flex;
justify-content: center;
align-items: center;
}
```
---
<h3 id="example-response">Example Response</h3>
This is an example of the response that will be returned to the originating page when the QR code is scanned.
```json
{
"type": "com.deviceassure.payload.result",
"data": {
"code": "bd3f41f0-ace0-4c77-ae33-da195f2675ff",
"deviceAssure": {
"result": "AUTHENTIC",
"reason": "Properties match",
"deviceAtlasProperties": {
"vendor": "Google",
"marketingName": "Pixel 6a"
},
"referenceId": "871d26e2-94fb-400a-92ab-3b9a672b4c53"
},
"meta": {}
}
}
```
#### Response Format: ####
| Property | Type | Description |
|-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | string | The type of response returned. This is used for the behaviour of the QR code. It can be one of the following: <br> `com.deviceassure.payload.result`- default response <br> `com.deviceassure.payload.redirect` - redirect response <br> `com.deviceassure.payload.reload` - auto-refresh response |
| data | object | Data for the response, usually contains DeviceAssure response and code id |
| data.code | string | ID for the QR Code |
| data.deviceAssure | object | The DeviceAssure response. Please consult the Implementation Guide for more in depth descriptions. |
---
<h2 id="advanced-configurations">Advanced Configurations</h2>
In addition to the Basic Configurations, there are more advanced configurations that can be used to customise the QR code.
The dv-licenceKey parameter is required for these advanced configurations.
The option to configure these configurations is available upon request [here](mailto:support@deviceassure.com).
| Query Parameter | Type | Default | Constraints | Description |
|--------------------|--------|------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| dv-lifecycle | string | _default_ | _default_ or _auto-refresh_ | Describes how the QR host will behave by _default_, a click to refresh message is shown once scanned. <br> <br> If set to _auto-refresh_, the scanned QR code will be replaced with a new code automatically. |
| dv-response-delay | number | 2000 | Values must be non-negative and in milliseconds. | The time delay after a scan. Usually used in conjunction with the auto-refresh lifecycle and host-redirect in order to show a message before transitioning. |
| dv-redirect | string | | | A URL for the host showing the QR code to redirect to after a scan. When redirected, the URL will have a query param called _response_ with a base64 string of the JSON response as its value. |
| dv-device-redirect | string | | | A URL for the device to redirect to after a scan. When redirected, the URL will have a query param called _response_ with a base64 string of the JSON response as its value. |
| dv-scanned-message | string | Code was scanned | | Message to show after a QR code is successfully scanned. |
| dv-expired-message | string | Code has expired | | Message to show after a QR code expires. |
---
<h2 id="all-examples">Examples</h2>
<h3 id="all-configurations">All Configurations</h3>
This example will:
- Show a QR Code
- Show the custom 'Example Page Scanned' message on the originating page
- Refresh the QR code after 2000 milliseconds
- Scanning device will be redirected to the configured `dv-device-redirect` URL. The URL will have a query param called response with a base64 string of the JSON response as its value
- Host device will be redirect to the configured `dv-redirect` URL. the URL will have a query param called response with a base64 string of the JSON response as its value
-The `_deviceAssureResultReceived` function will be called with the result of the scan
```html
<div id="deviceassure"></div>
<script src="https://qr-code.deviceatlas.com/v2/api/snippet.js?dv-licenceKey=<YOUR_LICENCE_KEY>&dv-size=300&dv-json=false&dv-scanned-message=Example Page Scanned&dv-expired-message=Example Page Expired&dv-lifecycle=auto-refresh&dv-response-delay=2000&dv-redirect=https://www.example.com/host&dv-device-redirect=https://www.example.com/device"
</script>
<script>
function _deviceAssureResultReceived(results) {
console.log('DeviceAssure result received', results);
}
</script>
```
---
<h3 id="redirect-device-only">Device Only Redirect</h3>
#### Host setup: ####
```html
<div id="deviceassure"></div>
<script src="https://qr-code.deviceatlas.com/v2/api/snippet.js?dv-licenceKey=<MY_LICENCE_KEY>&dv-device-redirect=<MY_REDIRECT_URL>"></script>
<script>
function _deviceAssureResultReceived(result) {
console.log('DeviceAssure result from iframe:', result);
}
</script>
```
#### Redirect page setup: ####
The redirect page will need to decode the base64 string and parse the JSON object to get the DeviceAssure response.
An example of the URL that will be redirected to is as follows
```
https://www.example-redirect.com?response=ewogICJjb2RlIjogImJkM2Y0MWYwLWFjZTAtNGM3Ny1hZTMzLWRhMTk1ZjI2NzVmZiIsCiAgImRldmljZUFzc3VyZSI6IHsKICAgICJyZXN1bHQiOiAiQVVUSEVOVElDIiwKICAgICJyZWFzb24iOiAiUHJvcGVydGllcyBtYXRjaCIsCiAgICAiZGV2aWNlQXRsYXNQcm9wZXJ0aWVzIjogewogICAgICAidmVuZG9yIjogIkdvb2dsZSIsCiAgICAgICJtYXJrZXRpbmdOYW1lIjogIlBpeGVsIDZhIgogICAgfSwKICAgICJyZWZlcmVuY2VJZCI6ICI4NzFkMjZlMi05NGZiLTQwMGEtOTJhYi0zYjlhNjcyYjRjNTMiCiAgfSwKICAibWV0YSI6IHt9Cn0
```
#### Decoded Response for Redirects: ####
Below is the format for a redirect. Note how the redirect format is not nested.
```json
{
"code": "bd3f41f0-ace0-4c77-ae33-da195f2675ff",
"deviceAssure": {
"result": "AUTHENTIC",
"reason": "Properties match",
"deviceAtlasProperties": {
"vendor": "Google",
"marketingName": "Pixel 6a"
},
"referenceId": "871d26e2-94fb-400a-92ab-3b9a672b4c53"
},
"meta": {}
}
```
#### Response Format: ####
| Property | Type | Description |
|--------------|--------|----------------------------------------------------------------------------------------------------|
| code | string | ID for the QR Code |
| deviceAssure | object | The DeviceAssure response. Please consult the Implementation Guide for more in depth descriptions. |
The following code snippet demonstrates how to decode the base64 string and display the DeviceAssure response.
```html
<script>
// Function to decode base64 encoded string
function decodeBase64(encodedString) {
return atob(encodedString);
}
// Get the value of the "data" parameter from the URL
var urlParams = new URLSearchParams(window.location.search);
var encodedData = urlParams.get("response");
// Decode the base64 string and display the DeviceAssure response
document.getElementById("json-div").innerHTML = decodeBase64(encodedData);
</script>
```
---
<h3 id="redirect-host-only">Host Only Redirect</h3>
#### Host setup: ####
```html
<div id="deviceassure"></div>
<script src="https://qr-code.deviceatlas.com/v2/api/snippet.js?dv-licenceKey=<MY_LICENCE_KEY>&dv-redirect=<MY_REDIRECT_URL>"></script>
<script>
function _deviceAssureResultReceived(result) {
console.log('DeviceAssure result from iframe:', result);
}
</script>
```
#### Redirect page setup: ####
The redirect page will need to decode the base64 string and parse the JSON object to get the DeviceAssure response.
An example of the URL that will be redirected to is as follows
```
https://www.example-redirect.com?response=ewogICJjb2RlIjogImJkM2Y0MWYwLWFjZTAtNGM3Ny1hZTMzLWRhMTk1ZjI2NzVmZiIsCiAgImRldmljZUFzc3VyZSI6IHsKICAgICJyZXN1bHQiOiAiQVVUSEVOVElDIiwKICAgICJyZWFzb24iOiAiUHJvcGVydGllcyBtYXRjaCIsCiAgICAiZGV2aWNlQXRsYXNQcm9wZXJ0aWVzIjogewogICAgICAidmVuZG9yIjogIkdvb2dsZSIsCiAgICAgICJtYXJrZXRpbmdOYW1lIjogIlBpeGVsIDZhIgogICAgfSwKICAgICJyZWZlcmVuY2VJZCI6ICI4NzFkMjZlMi05NGZiLTQwMGEtOTJhYi0zYjlhNjcyYjRjNTMiCiAgfSwKICAibWV0YSI6IHt9Cn0
```
The following code snippet demonstrates how to decode the base64 string and display the DeviceAssure response.
```html
<script>
// Function to decode base64 encoded string
function decodeBase64(encodedString) {
return atob(encodedString);
}
// Get the value of the "data" parameter from the URL
var urlParams = new URLSearchParams(window.location.search);
var encodedData = urlParams.get("response");
// Decode the base64 string and display the DeviceAssure response
document.getElementById("json-div").innerHTML = decodeBase64(encodedData);
</script>
```
---
<h3 id="redirect-device-host">Host and Device Redirect</h3>
#### Host setup: ####
```html
<div id="deviceassure"></div>
<script src="https://qr-code.deviceatlas.com/v2/api/snippet.js?dv-licenceKey=<MY_LICENCE_KEY>&dv-redirect=<MY_REDIRECT_URL>&dv-device-redirect=<MY_REDIRECT_URL>"></script>
<script>
function _deviceAssureResultReceived(result) {
console.log('DeviceAssure result from iframe:', result);
}
</script>
```
#### Redirect page setup: ####
The redirect page will need to decode the base64 string and parse the JSON object to get the DeviceAssure response.
An example of the URL that will be redirected to is as follows
```
https://www.example-redirect.com?response=ewogICJjb2RlIjogImJkM2Y0MWYwLWFjZTAtNGM3Ny1hZTMzLWRhMTk1ZjI2NzVmZiIsCiAgImRldmljZUFzc3VyZSI6IHsKICAgICJyZXN1bHQiOiAiQVVUSEVOVElDIiwKICAgICJyZWFzb24iOiAiUHJvcGVydGllcyBtYXRjaCIsCiAgICAiZGV2aWNlQXRsYXNQcm9wZXJ0aWVzIjogewogICAgICAidmVuZG9yIjogIkdvb2dsZSIsCiAgICAgICJtYXJrZXRpbmdOYW1lIjogIlBpeGVsIDZhIgogICAgfSwKICAgICJyZWZlcmVuY2VJZCI6ICI4NzFkMjZlMi05NGZiLTQwMGEtOTJhYi0zYjlhNjcyYjRjNTMiCiAgfSwKICAibWV0YSI6IHt9Cn0
```
The following code snippet demonstrates how to decode the base64 string and display the DeviceAssure response.
```html
<script>
// Function to decode base64 encoded string
function decodeBase64(encodedString) {
return atob(encodedString);
}
// Get the value of the "data" parameter from the URL
var urlParams = new URLSearchParams(window.location.search);
var encodedData = urlParams.get("response");
// Decode the base64 string and display the DeviceAssure response
document.getElementById("json-div").innerHTML = decodeBase64(encodedData);
</script>
```
---
<h3 id="example-auto-refresh-with-a-delay-showing-a-custom-scan-message-and-redirect-the-scanning-device">Auto refresh with a delay, showing a custom scan message and redirect the scanning device</h3>
This example will:
- Show a QR Code
- Show the custom 'Device Scanned' message on the originating page
- Refresh the QR code after 2000 milliseconds
- Redirect the device to configured URL after a scan
- Return the configured DeviceAssure response for the licence key
- The `_deviceAssureResultReceived` function will be called with the result of the scan
#### Host setup: ####
```html
<div id="deviceassure"></div>
<script src="https://qr-code.deviceatlas.com/v2/api/snippet.js?dv-licenceKey=<MY_LICENCE_KEY>&dv-scanned-message=Device Scanned&dv-lifecycle=auto-refresh&dv-response-delay=2000&dv-device-redirect=<MY_REDIRECT_URL>"></script>
<script>
function _deviceAssureResultReceived(result) {
console.log('DeviceAssure result from iframe:', result);
}
</script>
```
#### Redirect page setup: ####
The redirect page will need to decode the base64 string and parse the JSON object to get the DeviceAssure response.
An example of the URL that will be redirected to is as follows
```
https://www.example-redirect.com?response=ewogICJjb2RlIjogImJkM2Y0MWYwLWFjZTAtNGM3Ny1hZTMzLWRhMTk1ZjI2NzVmZiIsCiAgImRldmljZUFzc3VyZSI6IHsKICAgICJyZXN1bHQiOiAiQVVUSEVOVElDIiwKICAgICJyZWFzb24iOiAiUHJvcGVydGllcyBtYXRjaCIsCiAgICAiZGV2aWNlQXRsYXNQcm9wZXJ0aWVzIjogewogICAgICAidmVuZG9yIjogIkdvb2dsZSIsCiAgICAgICJtYXJrZXRpbmdOYW1lIjogIlBpeGVsIDZhIgogICAgfSwKICAgICJyZWZlcmVuY2VJZCI6ICI4NzFkMjZlMi05NGZiLTQwMGEtOTJhYi0zYjlhNjcyYjRjNTMiCiAgfSwKICAibWV0YSI6IHt9Cn0
```
The following code snippet demonstrates how to decode the base64 string and display the DeviceAssure response.
```html
<script>
// Function to decode base64 encoded string
function decodeBase64(encodedString) {
return atob(encodedString);
}
// Get the value of the "data" parameter from the URL
var urlParams = new URLSearchParams(window.location.search);
var encodedData = urlParams.get("response");
// Decode the base64 string and display the DeviceAssure response
document.getElementById("json-div").innerHTML = decodeBase64(encodedData);
</script>
```
---
<h2 id="troubleshooting">Troubleshooting</h2>
<h3 id="qr-code-redirects">QR Code Redirects</h3>
When using the redirect functionality with the DeviceAtlas QR Code, it is important to ensure that the `dv-device-redirect`
is accessible to the scanning device.
The following urls won't work out of the box:
- localhost
- 127.0.0.1
- 0.0.0.0
It would be best to use a network IP address or a domain name that is accessible to the scanning device.
---
## Copyright ##
Copyright (c) DeviceAtlas Limited 2024. All rights reserved. https://deviceatlas.com
]]>