<![CDATA[# DeviceAssure Web Client #
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.
1) Client to server model
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.
2) Server to server model
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.
## Data ##
The library collects data about the underlying hardware and browser
capabilities. It does not collect any PII data.
The library stores a non-configurable cookie to prevent subsequent calls to the
DeviceAssure library for a **30 minute** period. DeviceAssure will not be called
again until the cookie expires or is deleted.
## Setup ##
The DeviceAssure JavaScript library must be included on a webpage for it to
function. It is recommended to include the library at the end of the web page.
This section shows how to setup the library for both "Client to Server" and also
"Server to Server" usage.
### Client to Server usage ###
In this scenario the data is collected by the library and automatically sent to
the DeviceAssure service to be analysed.
The below sample code shows how to include and call the library. A valid licence
key _must_ be provided by replacing the placeholder "LICENCE_KEY".
```javascript
<!-- include the JavaScript library -->
<script src="<path/to/deviceAssure.min.js>"></script>
<!-- Call the check method and handle results -->
<script type="text/javascript">
try{
DeviceValidation.check('LICENCE_KEY',
function(response) { // success callback is optional
// Handle successful response here.
},
function(error) { // failure callback is optional
// Handle error or failed response here.
}
);
}
catch(err) {
// Handle error thrown here.
}
</script>
```
Please see the Implementation Guide for the structure and examples of returned
validation data.
Alternatively, the library may be included and called asynchronously. This is
shown below:
```javascript
<script type="text/javascript">
DeviceValidation = {
options: {
licence: 'LICENCE_KEY',
onSuccess: function(response) { // success callback is optional
// Handle successful response here.
},
onFailure: function(error) { // failure callback is optional
// Handle error or failed response here.
}
}
};
</script>
<script src="<path/to/deviceAssure.min.js>" defer></script>
```
### Server to Server usage ###
In this scenario, the data is collected by the library and made available to the
calling application. The calling application must send the data to an appropriate
server that subsequently makes a request to the DeviceAsssure 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 service.
The Server to Server functionality may be enabled by adding a **serverToServer: true**
parameter to the options object before calling the library. This flag will
disable the automatic validation to the DeviceAssure service and will instead
make the collected data available to the calling application.
The collected data may be retrieved from the library synchronously or
asynchronously. Both approaches are shown below:
```javascript
<!-- enable server to server mode -->
<script type="text/javascript">DeviceValidation={options:{serverToServer:true}};</script>
<!-- include the library -->
<script src="<path/to/deviceAssure.min.js>" type="text/javascript"></script>
<!-- call the getData() function -->
<script>
// Asynchronous call by providing a callback function:
var payload;
function callBack(collectedData) {
payload = collectedData;
// or do whatever with data
};
DeviceValidation.getData(callback);
// OR alternatively a synchronous blocking call may be made:
var payload = DeviceValidation.getData();
</script>
```
## Sample Application ##
A sample application is included in the package. This sample shows usage for
both the "Client to Server" and the "Server to Server" approaches. A valid
DeviceAssure licence key is required for the "Client to Server" example.
## Copyright ##
Copyright (c) DeviceAtlas Limited 2022. All rights reserved. https://deviceatlas.com
]]>