# 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 _ <!-- 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 class="disabled"><a href="README.html">Device Detection API</a></li><li><a href="README.DeviceApi-Config.html">Device Detection API Config</a></li><li><a href="./DeviceAtlasApiDocs/index.html">DeviceAtlas API JS Docs</a></li><li class="divider"></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side Component</a></li></ul></div>