<![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 DeviceAssure library asynchronously. A valid licence
key _must_ be provided by replacing the placeholder "LICENCE_KEY".
```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>
<!-- include the JavaScript library -->
<script src="<path/to/deviceAssure.min.js>" defer></script>
```
Alternatively, the library may be included and called synchronously using the sample javascript code below.
```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.
### 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 type="text/javascript">
// Asynchronous call by providing a callback function:
function callBack(collectedData) {
var payload = collectedData;
// Proceed with your response or perhaps use our DeviceValidation.check() method above.
}
DeviceValidation.getData(callBack);
// OR alternatively a synchronous blocking call may be made:
var payload = DeviceValidation.getData();
</script>
```
---
### DeviceAssure Storage Expiry Configuration Location ###
Collected device information is stored in the browser inside a cache. It is possible to modify the default behaviour in
order to store this information in another type of web-storage.
The available options are:
###### `local-storage` - Default ######
Using `local-storage` 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.
If any of these storage options are cleared or expire, then another DeviceAssure call is made.
##### Example setup ######
Below is an example of overriding the storage type to a different value. If you do not wish to change the location of the
stored data, then no configuration is needed.
```javascript
DeviceValidation = {
options: {
..., // Also include other properties
storageType: 'cookie' // cache type to store test results - available options 'cookie', 'local-storage'
}
}
```
A more in depth example can be seen in the example page found in example/index.html
It has a default cache set to `local-storage`.
---
## 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 2023. All rights reserved. https://deviceatlas.com
]]>