DeviceAtlas Device Detection API

# 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 ### 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 Synchronously ### #### 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) { //json could not load! do something! } return new deviceApi; })(); ``` #### Looking up Properties #### ```javascript /* Look up device properties. The detection is done based on the nodejs request object*/ var properties = deviceApi.getPropertiesFromRequest(request); /* Use the properties - e.g. detect mobile device. */ // 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); } ``` ### Basic Usage Asynchronously ### Synchronously is faster but holds onto the resource. Asynchronously is slower due but does not hold onto the single resource. The loading of the file and device detection will be short so the overhead created asynchronously might not be worth it. #### 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. */ deviceApi.loadDataFromFile('path/to/datafile.json', function(err, properties) { if (err) //do something //finished loading data file }); return deviceApi; })(); ``` #### Looking up Properties #### ```javascript //use singleton instance created in main script var deviceApi = require('path/to/main.js').deviceApi; /* Look up device properties. The detection is done based on the nodejs request object*/ var properties = deviceApi.getPropertiesFromRequest(request, function(err, properties) { if (err) //do something // 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); } //more code }); ``` ### 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.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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) 2021 by DeviceAtlas Limited. All rights reserved. https://deviceatlas.com _  <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 class="disabled"><a href="README.DeviceApi.html">Device Detection API</a></li><li><a href="README.DeviceApi-Config.html">Device Detection API Config</a></li><li><a href="DeviceApiDocs/index.html">Device API JS Docs</a></li><li class="divider"></li><li><a href="README.ClientSide.html">Client-side Component</a></li></ul></div>