# DeviceAtlas Device API Usage # 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. 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. Please see the [Data File Configuration documentation](README.DataFileConfig.html) 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>