<
- [Client to server model](#client-to-server-model)
- [Server to server model](#server-to-server-model)
- [Supported Browsers](#supported-browsers)
- [Sample Application](#sample-application)
- [Data](#data)
- [Getting Started](#getting-started)
- [Client to Server](#client-to-server-usage)
- [Page Load Setup](#c2s-page-load-setup)
- [User Event Setup](#c2s-user-event-setup)
- [Server to Server](#server-to-server-usage)
- [Page Load Setup](#s2s-page-load-setup)
- [User Event Setup](#s2s-user-event-setup)
- [IMEI Corroboration](#imei-corroboration)
- [Client to Server with IMEI](#imei-corroboration-c2s)
- [Server to Server with IMEI](#imei-corroboration-s2s)
- [Error Handling](#imei-corroboration-error-handling)
- [DeviceAssure Cache Configuration](#deviceassure-cache-configuration)
- [Storage Types/Location](#storage-typeslocation)
- [Cache Expiry Configuration](#cache-expiry-configuration)
- [Troubleshooting](#troubleshooting)
- [iFrame](#iframe-usage)
- [Alternative Setups](#alternative-setups)
- [Using Javascript Modules](#alternative-setups-javascript-modules)
- [Vue, Angular, React etc](#alternative-setups-vue-angular-react-etc)
<h2 id="introduction">Introduction</h2>
The purpose of this JavaScript library is to analyse and validate a device
visiting a webpage with the library embedded. The collected data is compared
with sets of known valid characteristics for legitimate devices. This
comparison and validation is performed by the DeviceAssure backend service.
The data collected by the library may be sent to the DeviceAssure service in two
ways.
<h3 id="client-to-server-model">Client to server model</h3>
The data is sent directly from the client library to the DeviceAssure backend
service. Validation results are returned to the library and optionally to a
configured callback URL.
<h3 id="server-to-server-model">Server to server model</h3>
The data is collected and made available on the client. The DeviceAssure library
will not make a request to the DeviceAssure service. It is the responsibility of
the calling application to transmit the data to a suitable server and for that
server to make the request to the DeviceAssure service. The validation results
are returned directly back to the calling server and not to the client
application.
---
<h3 id="supported-browsers">Supported Browsers</h3>
DeviceAssure can reliably identify and verify devices running on browsers. The table below describes the most common browsers that can be identified.
[//]: # (✅ is a check mark emoji)
[//]: # ( is a white space, in order to show empty cells in the table)
| Browser | Android | iOS | Windows | MacOS | Linux |
|-----------------|---------|---------|---------|---------|---------|
| Chrome | ✅ | ✅ | ✅ | ✅ | ✅ |
| Edge | ✅ | ✅ | ✅ | ✅ | ✅ |
| Opera | ✅ | ✅ | ✅ | ✅ | ✅ |
| Firefox* | ✅ | ✅ | ✅ | ✅ | ✅ |
| Brave* | ✅ | ✅ | ✅ | ✅ | ✅ |
| Duck Duck Go | ✅ | ✅ | ✅ | ✅ | |
| Samsung Browser | ✅ | | | | |
| Safari | | ✅ | | ✅ | |
| IE 11 | | | ✅ | | |
#### Note: ####
In addition to identifying the browsers above, DeviceAssure can identify and verify the device model except on Firefox
and Brave as the identifying properties are withheld by the browser.
There is an exception for iOS devices running Firefox and Brave browsers. Due to Apple restrictions, all browsers on iOS must use the WebKit engine and therefore
it is possible to identify the device model on these browsers.
A more detailed browser list DeviceAssure identifies can be found [here](https://deviceatlas.com/device-data/explorer/#defined_property_values/7/2705619).
---
<h2 id="sample-application">Sample Application</h2>
A sample application is included in the package. It includes examples for the following scenarios:
- Client to Server
- On Page Load
- On User Event
- On User Event with IMEI
- Server to Server
- On Page Load
- On User Event
- On User Event with IMEI
- QR Code
A valid DeviceAssure licence key is required for the "Client to Server" examples as these will call the DeviceAssure API from the client.
To correctly identify an Android device or Desktop using the Chrome browser, or any browser that supports client-hints, data collection must occur over a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts#potentially_trustworthy_origins).
#### Running the Sample Application ####
```bash
# Unzip the package and navigate to the SampleApplication directory
cd SampleApplication
python3 -m http.server 3000
# Now navigate to http://localhost:3000
```
---
<h2 id="data">Data</h2>
The library collects data about the underlying hardware and browser
capabilities. It does not collect any PII data.
The library stores our data in a configurable location to prevent subsequent calls to the
DeviceAssure library for a **30 minute** period. DeviceAssure will not be called
again until the cache expires or is deleted.
It is possible to delete the cached location within our library. The expiry and the location of the cache can be set, or
can be disabled entirely.
Please see the DeviceAssure Cache Configuration section for more details.
> **Note:** To collect the most complete set of device data—including client-hints from Chromium-based browsers such as Chrome, ensure that your site is served over a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts#potentially_trustworthy_origins) (typically HTTPS). Some browser features and data, including client-hints, are only available when the page is loaded securely.
---
<h2 id="getting-started">Getting Started</h2>
The DeviceAssure JavaScript library must be included on a webpage for it to
work. It is recommended to include the library at the end of the web page.
The DeviceAssure library can be used in three different ways: ["Client to Server"](#client-to-server-usage), ["Server to Server"](#server-to-server-usage) and ["IMEI Corroboration"](#imei-corroboration).
There are a number of methods exposed in the DeviceAssure library. However, the `.load` method is the recommended method to use. The remaining methods have been deprecated and should no longer be used. These will be removed in a future release.
Property | Description
------------ | -------------------------------------------------------------------------------------------------------------------
`.load` | Entrypoint method for the library. Please see the setup guides below for more details.
`.check` | [Deprecated, use `load`] Please see the Migration Guide included in our bundle for help moving to the new `.load` method above.
`.checkIMEI` | [Deprecated, use `load`] Please see the Migration Guide included in our bundle for help moving to the new `.load` method above.
`.getData` | [Deprecated, use `load`] Please see the Migration Guide included in our bundle for help moving to the new `.load` method above.
<h2 id="client-to-server-usage">Client to Server</h2>
For this option the data is collected by the library and automatically sent to the DeviceAssure API for device verification.
There are two recommended ways to use the library in this scenario. The first is ["Page Load Setup"](#page-load-setup) and the second is upon a ["User Event"](#user-event-setup) e.g. a click of a button the `.check` method is called directly.
<h3 id="c2s-page-load-setup">Page Load Setup</h3>
The following is a list of configurations that can be set on the DeviceAssure library for the page load setup.
| Property | Type | Default | Description |
|------------------|--------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| `serverToServer` | Boolean | `false` | Enable server to server mode. This will disable the automatic validation to the DeviceAssure service and manual data collection can then occur. |
| `imei` | String | 'undefined' | Provide an IMEI for use as another identifier for device verification. When `imei` is present it must not be defined with an IMEI value. |
| `tags` | List<Map<String, String> | '[]' | A list of tags to add to the API request. Allows for custom parameters to be returned in the API Response. The `key` and `value` must be strings. <br> Maximum length for keys and values is 64 and 128 respectively |
| `licence` | String | `null` | The licence key to use for the DeviceAssure service. Required for Client to Server. |
| `onSuccess` | Function | `function() {}` | The callback function to call when the DeviceAssure service returns a successful response. |
| `onError` | Function | `function() {}` | The callback function to call when the DeviceAssure service returns an error response. |
| `storageType` | String | `local-storage` | The type of storage to use for the DeviceAssure cache. Available options are `local-storage`, `cookie` or `none`. |
| `storageExpiry` | Number | `1800000` | The time in milliseconds that the DeviceAssure cache will be valid for. The minimum value is 1 millisecond and the maximum value is 24 hours. |
#### Example ####
```html
<!-- Setup the configs. -->
<script type="text/javascript">
function onDeviceAssureLoad() {
DeviceValidation.load({
licence: '<LICENCE_KEY>',
storageType: 'local-storage', // override 'local-storage' default to 'cookie' or 'none'
tags: [
{ key: 'page-identifier', value: 'login' }, // Example of a tag for the API request on a login page.
{ key: 'action', value: 'on-page-load' },
],
onSuccess: function(response) {
console.log('Handle successful response here.', response);
},
onError: function(error) {
console.log('Handle error or failed response here.', error)
}
});
}
</script>
<!-- Note how the configs are defined before the import of the DeviceAssure script -->
<script src="<path/to/deviceAssure.min.js>" defer async onload="onDeviceAssureLoad()"></script>
```
A working example can be found in `SampleApplication/index.html`.
---
<h3 id="c2s-user-event-setup">User Event Setup</h3>
The below sample code shows how to include and how to call the DeviceAssure library when an event is triggered.
An event is triggered on button press.
A valid licence key _must_ be provided by replacing the placeholder `<LICENCE_KEY>`.
```html
<!-- Library must be imported before this is called -->
<script src="<path/to/deviceAssure.min.js>" async defer></script>
<!-- Call the check method and handle results -->
<script type="text/javascript">
var onSuccess = function (response) {
console.log('Handle successful response here.', response);
};
var onError = function (error) {
console.log('Handle error or failed response here.', error)
};
$('.example-submit-button').on('click', function() {
DeviceValidation.load({
licence: '<LICENCE_KEY>',
storageType: 'none',
tags: [
{ key: 'page-identifier', value: 'login' }, // Example of a tag for the API request on a form click.
{ key: 'action', value: 'on-submit-clicked' },
],
onSuccess: function(response) {
console.log('Handle successful response here.', response);
},
onError: function(error) {
console.log('Handle error or failed response here.', error)
}
});
});
</script>
```
A working example can be found in `SampleApplication/on-event.html`.
---
<h2 id="server-to-server-usage">Server to Server</h2>
In this use-case, the device data is collected by the library and made available to the calling application. It is then the responsibility of the calling application
to send the data to an appropriate server that subsequently makes a request to the DeviceAssure service. Please see the
Implementation Guide for further details on how to send the data from a server context.
Note: A licence key is not required on the client side in this scenario. It must however be provided on the server side
before making the request to the DeviceAssure API.
The Server to Server functionality may be enabled by adding **serverToServer: true** and an **onSuccess** callback parameter.
**Please Note:**
When using the Server to Server mode the data will not be cached by the library. This is the responsibility of the calling application to store the data and send it to the server.
Parameter | Required | Type | Default | Description
--------- | -------- | ------ | ----------- | -------------------------------------------------------------------------------------------------
`payload` | Yes | Object | `undefined` | This is the only argument passed in to the server to server functions. It is a javascript object.
Please see below for examples.
<h3 id="s2s-page-load-setup">Page Load Setup</h3>
```html
<!-- Enable server to server mode, this will prevent the check request from being sent on page load. -->
<script type="text/javascript">
function onDeviceAssureLoad() {
DeviceValidation.load({
serverToServer: true,
storageType: 'none',
tags: [
{ key: 'page-identifier', value: 'login' }, // Example of a tag for the API request on a login page.
{ key: 'action', value: 'on-page-load' },
],
onSuccess: function (payload) {
console.log('DeviceValidation Payload', payload);
}
});
}
</script>
<!-- Note how the configs are defined before the import of the DeviceAssure script -->
<script src="<path/to/deviceAssure.min.js>" type="text/javascript" defer async onload="onDeviceAssureLoad()"></script>
```
A working example can be found in `SampleApplicaiton/s2s.html` page.
<h3 id="s2s-user-event-setup">User Event Setup</h3>
The below is an example using jquery. The event is triggered on button press.
```html
<!-- Enable server to server mode, this will prevent the check request from being sent on page load. -->
<script type="text/javascript">
window.addEventListener('DOMContentLoaded', function() {
$('#on-button').on('click', function () {
DeviceValidation.load({
serverToServer: true,
storageType: 'none',
tags: [
{ key: 'page-identifier', value: 'user-quote' }, // Example of a tag for the API request on a button click.
{ key: 'action', value: 'on-button-click' },
],
onSuccess: function (payload) {
console.log('DeviceValidation Payload', payload);
}
});
return false;
});
});
</script>
<!-- Note how the configs are defined before the import of the DeviceAssure script -->
<script src="<path/to/deviceAssure.min.js>" type="text/javascript" defer async></script>
```
A working example can be found in `SampleApplicaiton/s2s-event.html` page.
---
<h2 id="imei-corroboration">IMEI Corroboration</h2>
This feature allows for the validation of the alignment between an IMEI and headers of the device under test.
A valid licence key with the IMEI feature enabled is required. Please contact support@deviceassure.com for more details.
Once this feature has been enabled for a licence the IMEI can be included as one of the configurations when calling the DeviceAssure library.
The collected data can be retrieved from the library asynchronously and sent along with the IMEI to the DeviceAssure API. See below for an example:
Additionally, the ability to check if a provided IMEI is lost / stolen is another optional extra and must also be turned on for a licence via DeviceAssure support.
**Please Note:**
The IMEI value must be provided in the `imei` configuration once included. The IMEI value must be a string. A clientside error will occur if the IMEI is null or empty and the IMEI will be trimmed to remove any leading or trailing whitespaces.
It is also recommended to use a storageType of `none` when validating with an IMEI. If another IMEI is entered and the
storageType is not `none`, the library will use the cached response and not the new IMEI response. This is to prevent any mis-detections due
to user error or slips.
An IMEI can be included in the payload in both Client to Server and Server to Server methods.
<h3 id="imei-corroboration-c2s">Client to Server with IMEI</h3>
```html
<!-- Library must be imported before this is called -->
<script src="<path/to/deviceAssure.min.js>" type="text/javascript" async defer></script>
<script type="text/javascript">
$('.example-submit-button').on('click', function() {
DeviceValidation.load({
imei: '<IMEI>',
storageType: 'none',
licence: '<LICENCE_KEY>',
onSuccess: function (response) {
console.log('Handle successful response here.', response);
},
onError: function(error) {
console.log('Handle error or failed response here.', error)
}
});
});
</script>
```
A working example can be found in `SampleApplication/imei.html` page.
<h3 id="imei-corroboration-s2s">Server to Server with IMEI</h3>
Please consult the Implementation Guide for more in depth usage of the Server to Server method.
```html
<!-- Library must be imported before this is called -->
<script src="<path/to/deviceAssure.min.js>" type="text/javascript" async defer></script>
<script type="text/javascript">
$('.example-submit-button').on('click', function() {
DeviceValidation.load({
imei: '<IMEI>',
storageType: 'none',
serverToServer: true,
onSuccess: function (payload) {
console.log('Payload available for sending to DeviceAssure via Server-to-Server', payload);
},
onError: function(error) {
console.log('Handle error on collection here.', error);
}
});
});
</script>
```
A working example can be found in SampleApplication/imei-s2s.html page.
<h3 id="imei-corroboration-error-handling">Error Handling</h3>
There is basic validation carried out on the IMEI value. The below errors can occur when a `blank`, `null` or `undefined` IMEI is provided.
They can be intercepted by adding the `onError` configuration. An error will be shown in the console if this is not configured. No payload will be captured or API request sent in either scenario.
Two possible errors can occur depending on the above methods used:
#### Client to Server Error:
```json
{
"message": "IMEI is not present, please enable it in config. API request not sent."
}
```
#### Server to Server Error:
```json
{
"message": "IMEI is not present, please provide an IMEI."
}
```
---
<h2 id="deviceassure-cache-configuration">DeviceAssure Cache Configuration</h2>
The DeviceAssure API Response can be stored in the browser inside a cache. This is to prevent subsequent calls to the DeviceAssure API if neccessary. By default the cache is stored in local-storage. It is possible to modify the default behaviour in
order to store this information in another type of web-storage.
<h3 id="storage-typeslocation">Storage Types/Location</h3>
The available options are:
#### local-storage ####
Using `local-storage` (default behaviour) means DeviceAssure will use localStorage to track whether to call the check endpoint. It stores a
JSON string with the time of expiry and the blocking value.
#### cookie ####
Using `cookie` means DeviceAssure will use cookies to track whether to call the check endpoint. The expiration of the cookie
will indicate whether to make another call or not.
#### none ####
Using `none` will never save any response from DeviceAssure. This means that every time the DeviceAssure library is called,
it will make a call to the DeviceAssure service. Any existing cache is left untouched and will remain there until cleared or expires.
If any of these storage options are cleared or expire, then another DeviceAssure call is made.
<h3 id="cache-expiry-configuration">Cache Expiry Configuration</h3>
It is also possible to set the expiry time of the cache. This is the time in milliseconds that the cache will be valid for.
The default value is 30 minutes. It is not necessary to specify the storageExpiry if the default is used. Once the cache expires, another DeviceAssure API call will be made.
The valid configuration for this property is between 1 millisecond and 24 hours. This is to prevent some unwanted/persisted behaviour.
#### Examples: ###
##### Configuring storageType and Cache Expiry on page load #####
```html
<!-- Run the library on load. -->
<script type="text/javascript">
function onDeviceAssureLoad() {
DeviceValidation.load({
licence: '<LICENCE_KEY>',
onSuccess: function(response) { // success callback is optional
console.log('Handle successful response here.', response);
},
onFailure: function(error) { // failure callback is optional
console.log('Handle error or failed response here.', error)
},
storageType: 'cookie' // cache type to store test results - available options 'cookie', 'local-storage' or 'none. Default is 'local-storage'.
storageExpiry: 8 * 60 * 60 * 1000 // cache expiry time in milliseconds. Default is 30 minutes.
});
}
</script>
<!-- Note how the configs are defined before the import of the DeviceAssure script -->
<script src="<path/to/deviceAssure.min.js>" defer async onload="onDeviceAssureLoad()"></script>
```
##### Configuring storageType and Cache Expiry on user event ####
```html
<!-- Library should be imported before this is called -->
<script src="<path/to/deviceAssure.min.js>" defer async></script>
<!-- Call the check method and handle results -->
<script type="text/javascript">
var onSuccess = function (response) {
console.log('Handle successful response here.', response);
};
var onError = function (error) {
console.log('Handle error or failed response here.', error)
};
$('.example-submit-button').on('click', function() {
DeviceValidation.load({
licence: '<LICENCE_KEY>'
storageType: 'local-storage' // cache type to store test results - available options 'cookie', 'local-storage' or 'none
storageExpiry: 8 * 60 * 60 * 1000 // cache expiry time in milliseconds. Default is 30 minutes.
onSuccess: onSuccess,
onError: onError
});
});
</script>
```
A more in depth example can be found in `SampleApplication/index.html`.
---
<h2 id="troubleshooting">Troubleshooting</h2>
<h3 id="iframe-usage">iFrame</h3>
If the DeviceValidation library is embedded in a cross-origin iframe, the following attributes are required to surpress warnings in the console. The library will continue to work, the errors/warnings are non-blocking in the library.
`allow="accelerometer; gyroscope;"`
##### Warning logs
```
[Violation] Permissions policy violation: accelerometer is not allowed in this document.
[Violation] Permissions policy violation: gyroscope is not allowed in this document.
```
##### Full Example:
```html
<iframe
id="deviceassure-iframe"
src="https://path-to-cross-origin-page>"
allow="accelerometer; gyroscope;"
>
</iframe>
```
---
<h2 id="alternative-setups">Alternative Setups</h2>
Below are a few different approaches to using the DeviceAssure library. Each setup still uses the same configs as listed above.
<h2 id="alternative-setups-javascript-modules">Javascript Modules</h2>
```html
<script type="module">
import('<path/to/deviceAssure.min.js>').then(() => {
DeviceValidation.load({
licence: '<LICENCE_KEY>',
onSuccess: function (response) {
console.log('DeviceValidation', response);
},
onError: function (error) {
console.error('DeviceValidation Error', error);
}
});
});
</script>
```
---
<h2 id="alternative-setups-vue-angular-react-etc">Vue, Angular, React etc</h2>
Alternatively, the DeviceValidation library can be declared on the window object.
(This can be useful when implementing in a framework such as AngularJS, React or Vue).
### Javascript for Vue, Angular, React etc ###
The library can to be imported into a js file dynamically and then setup at runtime inside a component.
Angular and React will need to do something similar too with loading the library in at runtime.
A Vue example component can be seen below:
```vue
<template>
<div class="deviceassure-component"></div>
</template>
<script>
export default {
name: "DeviceAssure",
props: {
licence: String,
imei: {
type: Boolean,
default: false,
},
onSuccess: {
type: Function,
default: () => {},
},
onError: {
type: Function,
default: () => {},
},
},
created() {
this.loadDeviceAssure();
},
methods: {
loadDeviceAssure() {
if (this.isLoaded()) {
this.instance = window.DeviceValidation;
return;
}
import("@/libs/dv.min.js").then(() => {
if (!this.instance) {
this.instance = window.DeviceValidation;
console.log("loaded library", this.instance);
}
});
},
isLoaded() {
return window.DeviceValidation && !!window.DeviceValidation.load;
},
validateWithIMEI(imei) {
var params = {
onSuccess: (data) => {
console.log("DeviceAssure onSuccess: ", data);
this.response = data;
this.$props.onSuccess(data);
},
onError: (err) => {
console.log("DeviceAssure onError: ", err);
this.error = err;
this.$props.onError(err);
},
licence: this.$props.licence,
imei: imei,
};
this.instance.load(params);
},
validate() {
var params = {
onSuccess: (data) => {
console.log("DeviceAssure onSuccess: ", data);
this.response = data;
this.$props.onSuccess(data);
},
onError: (err) => {
console.log("DeviceAssure onError: ", err);
this.error = err;
this.$props.onError(err);
},
licence: this.$props.licence,
};
this.instance.load(params);
},
getResponse() {
return this.response;
},
},
data() {
return {
instance: null,
response: {},
error: {},
};
},
};
</script>
```
---
## Copyright ##
Copyright (c) DeviceAtlas Limited 2025. All rights reserved. https://deviceatlas.com
]]>