< and
the [Device Data guide](https://deviceatlas.com/resources/getting-the-data/device-data)
for more information.
### Requirements ###
* NodeJS 0.12.4 (or above)
* NPM 2.11.0 (or above)
### Basic Usage ###
#### Initiating DeviceAtlas API and Loading 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 DeviceApi = require('deviceatlas-deviceapi').DeviceApi;
/* Use the singleton pattern and export so that only 1 instance exists
in the application. */
module.exports.deviceApi = (function() {
/* Create an instance of DeviceApi with default config */
var deviceApi = new DeviceApi();
/* Load data. */
try {
deviceApi.loadDataFromString(require('fs').readFileSync('path/to/datafile.json'));
} catch(e) {
console.log("Could not load the data file");
}
return deviceApi;
})();
```
#### Detection via User-Agent ####
Lookup the properties by passing a User-Agent string to the API (Synchronously is faster but holds onto the resource):
```javascript
/* Use the properties - e.g. detect mobile device. */
function useProperties(properties) {
// if there is a property named "mobileDevice" and the value is true
if (properties['mobileDevice'] == true) {
// example 1: Get the screen width for image optimization
var displayWidth = properties['displayWidth'] || 100;
// example 2: Get the device vendor name
var vendor = properties['vendor'] || '';
// example 3: Touch screen optimization
var useBiggerIcons = properties['touchScreen'] == true;
// example 4: Send Geo Location JS to client?
var supportsGeoLocation = properties['js.geoLocation'] == true;
}
}
// Synchronously (not passing callback parameter)
try {
var properties = deviceApi
.getProperties({"User-Agent": "Mozilla/5.0 (Linux; U; Android 4.0.4; en-gb; GT-I9300 Build/IMM76D) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30"})
.getAsObject(); // reads request.headers object
useProperties(properties)
} catch (err) {
console.log(err)
}
```
#### Detection via Make/Model ####
Lookup the properties by passing a Make/Model string to the API (Synchronously is faster but holds onto the resource).
DeviceAtlas expects the make/model string in a specific format, this format and how to obtain the Make/Model string
can be found under the "Expected string format for DeviceAtlas lookup" section [here](https://deviceatlas.com/resources/getting-started-enterprise-for-apps).
```javascript
/* Use the properties - e.g. detect mobile device. */
function useProperties(properties) {
// Use the properties
}
// Synchronously (not passing callback parameter)
try {
var properties = deviceApi
.getProperties({"make-model": "samsung sm-n9005"})
.getAsObject(); // reads request.headers object
useProperties(properties)
} catch (err) {
console.log(err)
}
```
The exception DataLoadingException is thrown by the above methods in case the data file cannot be loaded.
## Client Side Library - Apple Device Identification ##
In addition to the server-side API, an optional client-side Javascript library
is available. This library is important for two reasons:
1. It facilitates identification of Apple devices. Apple devices are _not_
identifiable using only HTTP User-Agent data.
2. It allows for the collection of dynamic or changing properties.
When the client-side library is embedded in a web page it collects additional
properties from the client's web browser. This data is then sent back to the
server and must be passed to the DeviceAtlas API along with the HTTP headers.
The combination of the client data and the server side data allow for accurate
identification of Apple devices.
The client-side library may be included on a webpage by adding the following
snippet:
```Javascript
<!-- Adding the DeviceAtlas client side component to get client side properties -->
<script type="text/javascript" src="https://cs.deviceatlas-cdn.com/dacs.js" async></script>
```
By default, the client-side library returns the data via a cookie. If this is
present in the `req` object it will be automatically used. The
cookie name is configurable via the `Config` class.
Alternatively, the client data may be returned via AJAX and passed to the server
side API manually.
For additional information, please see the [Client Side Library](https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html) documentation.
#### Additional Examples ####
Please find more complete examples in the /Examples directory.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2024. All Rights Reserved. _
_ https://deviceatlas.com _
<!-- HTML+JS for document formatting when opened in browser -->
<div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li><a href="README.Installation.html">Enterprise API Installation</a></li><li class="disabled"><a href="README.DeviceApi.html">Device API Usage</a></li><li><a href="README.DeviceApi-Config.html">Device Detection API Config</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li class="divider"></li><li><a href="./DeviceAtlasApiDocs/index.html">DeviceAtlas API JS Docs</a></li></ul></div>]]>