# DeviceAtlas Device Detection API #
The DeviceAtlas Device Detection API provides a way to detect devices based on
the HTTP headers. Using the headers, the API returns device information such as
screen width, screen height, is mobile, vendor, model etc.
To see a full list of properties in DeviceAtlas please visit:
https://deviceatlas.com/resources/available-properties
### Data File ###
The DeviceAtlas API relies on a device data file to function. DeviceAtlas
provides daily data file updates so it is recommended to download the data file
on a regular basis. This can be done manually from your account page or
automated via the https://deviceatlas.com/getJSON page.
For more information please see:
https://deviceatlas.com/resources/getting-the-data
### Requirements ###
* NodeJS 0.12.4 (or above)
* NPM 2.11.0 (or above)
### Installation ###
**Local Installation**
1. Unpack the Api
2. Install deviceatlas-deviceapi-2.1.5.tgz with NPM
```shell
$ npm install --save deviceatlas-enterprise-nodejs-2.1.5/Api/deviceatlas-deviceapi-2.1.5.tgz
```
### Dependencies ###
This library does not depend on any third party libraries.
### The 2.x API interface ###
* This is the standard interface, common across the DeviceAtlas APIs.
* This interface is intended to be simple to use, as the interface includes
custom objects for getting the detected property set and getting a single
property value.
### Basic Usage ###
#### Load in data file ####
The API can be used as follows:
This should be in the main js file and reused in other parts of the
application as follows
```javascript
var DeviceApiWeb = require('deviceatlas-deviceapi').DeviceApiWeb;
/* Use the singleton pattern and export so that only 1 instance exists
in the application. */
module.exports.deviceApi = (function() {
/* Create an instance of DeviceApiWeb with default config */
var deviceApi = new DeviceApiWeb();
/* Load data. */
try {
deviceApi.loadDataFromFile('path/to/datafile.json');
} catch(e) {
console.log("Could not load the data file");
}
return deviceApi;
})();
```
#### Looking up Properties ####
Synchronously is faster but holds onto the resource.
Asynchronously is slower due but does not hold onto the single resource.
```javascript
/* Use the properties - e.g. detect mobile device. */
function useProperties(err, properties) {
if (err) {
console.error(err);
return;
}
// if there is a property named "mobileDevice" and the value is true
if (properties.contains('mobileDevice', true)) {
// example 1: Get the screen width for image optimization
var displayWidth = properties.containsKey('displayWidth')?
properties.get('displayWidth').getValue(): 100;
// example 2: Get the device vendor name
var vendor = properties.containsKey('vendor')?
properties.get('vendor').getValue(): '';
// example 3: Touch screen optimization
var useBiggerIcons = properties.contains('touchScreen', true);
// example 4: Send Geo Location JS to client?
var supportsGeoLocation = properties.contains('js.geoLocation', true);
}
}
// Synchronously (not passing callback parameter)
try {
var properties = deviceApi.getPropertiesFromRequest(request);
useProperties(null, properties)
} catch (err) {
useProperties(err)
}
// or
// Asynchronously (passing a callback parameter)
deviceApi.getPropertiesFromRequest(request, useProperties)
```
### Client Side Component ###
In addition to the properties from the data file, properties can be gathered
from the client's browser and used both on the client side and on the server
side. Please see the [ClientSide readme file](README.ClientSide.html) for more
information.
#### Usage with Client Side Component ####
In addition to normal usage, DeviceAtlas has the capability to capture client
side properties and merge them into the server side properties.
The "deviceatlas-CLIENT_SIDE_VERSION.min.js" file must be included on your webpage in order for it
to detect the client side properties. The contents of this cookie are
automatically detected with the request headers or can be passed separately,
with Headers or a User-Agent, to get the combined properties back. Both sets of
properties are used in additional logic to determine other properties such
iPhone and iPad models which are normally not detectable.
### Example
An example project is provided in this package that demonstrates the usage
of the DeviceAtlas Device Detection API within a web application. This project
can be found at `./Examples/Device/basic-usage-web/`.
Follow readme provided in example directory.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved. _
_ https://deviceatlas.com _