# 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. ### Library ### The DeviceAtlas Device Detection API consists of three libraries and each library has a separate jar file. #### DeviceAtlas common (deviceatlas-common-x.x.jar) #### Contains the shared libraries which are common between the DeviceAtlas APIs. When using the DeviceApi and DeviceApiWeb, this jar file must be included in the classpath. #### DeviceApi (deviceatlas-deviceapi-x.x.jar) #### The main DeviceApi that loads the Device data and detects and returns the properties for a set of request headers or the user-agent. Client-side properties can be optionally passed to this library to get more accurate results. #### DeviceApiWeb (deviceatlas-deviceapiweb-x.x.jar) #### A small extension to the main API that allows passing of an HttpServletRequest object for automatic extraction of the request headers and client-side properties. Unless the HttpServletRequest object is not available or when processing an off-line user-agent list or header set, it is strongly recommended to use this library over the DeviceApi. All three jar files are required for this library to work. ### The 2.x API interface ### * This is the new 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. * Unlike the former interface, this interface is not a set of static methods. This allows the interface to have more encapsulation, requiring fewer and simpler methods. This new API is highly maintainable and flexible for future improvements and new features. * The DeviceApiWeb extension makes it possible to pass the servlet request object or the whole set of HTTP headers to the API. This allows the API to make a more precise detection and return properties with more accurate values. For example, some browsers distribute the user-agent information into different headers, so it is almost impossible to correctly detect the device properties, such as type and model from the user-agent header itself. With this new interface, the API is able to overcome these situations. #### Basic Usage #### The API can be used as follows: ##### Inside a servlet container ##### Create an API instance and load the data file when the servlet starts: ```java public class ServletContextExample implements ServletContextListener { public void contextInitialized(ServletContextEvent contextEvent) { // load the data file in a try/catch block as several exceptions may be thrown try { deviceApi = new DeviceApiWeb(); deviceApi.loadDataFromFile("/path/to/datafile.json"); // store the DeviceApiWeb instance on the servlet context ServletContext context = contextEvent.getServletContext(); context.setAttribute("DeviceApiWeb", deviceApi); } catch (Exception ex) { // handle the exceptions related to loading the data file } } public void contextDestroyed(ServletContextEvent contextEvent) { } } ``` Lookup the device properties when processing requests: ```java /* (1) Get the DeviceApiWeb instance from servlet context */ ServletContext context = getServletContext(); DeviceApiWeb deviceApi = (DeviceApiWeb)context.getAttribute("DeviceApiWeb"); /* (2) look up device properties by HttpServletRequest */ Properties properties = deviceApi.getProperties(request); /* (3) 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 int displayWidth = properties.containsKey("displayWidth")? properties.get("displayWidth").asInteger(): 100; // example 2: Get the device vendor name String vendor = properties.containsKey("vendor")? properties.get("vendor").asString(): ""; // example 3: Touch screen optimization boolean useBiggerIcons = properties.contains("touchScreen", true); // example 4: Send Geo Location JS to client? boolean supportsGeoLocation = properties.contains("js.geoLocation", true); } ``` ##### Outside a servlet container ##### To lookup the properties by manually passing a user-agent string or HTTP headers to the API: Note that the DeviceApiWeb is an extension of DeviceApi so all functionalities shown below are also available in DeviceApiWeb. ```java // the detection is done based on (HTTP headers) or user-agent string /* (1) create an instance with default API configs and load the data file */ DeviceApi deviceApi = new DeviceApi(); try { deviceApi.loadDataFromFile("/path/to/data-file.json"); } catch (Exception x) { // handle the exceptions related to loading the data file } /* (2) look up device properties by HTTP headers */ Map<String, String> headers = new HashMap<String, String>(); headers.put("HEADER NAME", "HEADER VALUE"); Properties properties = deviceApi.getProperties(headers); /* (2) or look up device properties by user-agent string */ String userAgent = "THE USER AGENT VALUE"; Properties properties = deviceApi.getProperties(userAgent); /* (3) 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 int displayWidth = properties.containsKey("displayWidth")? properties.get("displayWidth").asInteger(): 100; // example 2: Get the device vendor name String vendor = properties.containsKey("vendor")? properties.get("vendor").asString(): ""; // example 3: Touch screen optimization boolean useBiggerIcons = properties.contains("touchScreen", true); // example 4: Send Geo Location JS to client? boolean supportsGeoLocation = properties.contains("js.geoLocation", true); } ``` ### 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. ##### Inside a servlet container ##### To lookup the properties of the device which sent the request: The usage is exactly the same as the basic usage, the API analyses the request object and will use the client-side properties automatically if they exist in the cookies, just include the client side component to your web pages. Create an API instance and load the data file when the servlet starts as mentioned previously. Then lookup the device properties when processing requests: ```java /* Steps (1) and (2) are exactly the same as mentioned previously */ /* (3) 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 int displayWidth = properties.containsKey("displayWidth")? properties.get("displayWidth").asInteger(): 100; // example 2: Get the device model name more precisely now String model = properties.containsKey("model")? properties.get("model").asString(): ""; // example 3: Touch screen optimization boolean useBiggerIcons = properties.contains("touchScreen", true); // example 4: Send Geo Location JS to client? boolean supportsGeoLocation = properties.contains("js.geoLocation", true); // example 5: Get the device orientation (degrees) int deviceOrientation = properties.containsKey("bjs.deviceOrientation")? properties.get("bjs.deviceOrientation").asInteger(): 0; } ``` ##### Outside a servlet container ##### To lookup the properties by manually passing the headers and the client-side properties to the API: Note that the DeviceApiWeb is an extension of DeviceApi so all functionalities shown below are also available in DeviceApiWeb. ```java // the detection is done based on (HTTP headers) or user-agent string /* (1) create an instance with default API configs and load the data file as mentioned previously */ /* (2) look up device properties by HTTP headers */ String clientSide = "PROPERTY1:VALUE1|PROPERTY2:VALUE2|PROPERTY3:VALUE3"; Map<String, String> headers = new HashMap<String, String>(); headers.put("HEADER NAME", "HEADER VALUE"); Properties properties = deviceApi.getProperties(headers, clientSide); /* (2) or look up device properties by user-agent string */ String userAgent = "THE USER AGENT VALUE"; Properties properties = deviceApi.getProperties(userAgent, clientSide); /* (#) 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 int displayWidth = properties.containsKey("displayWidth")? properties.get("displayWidth").asInteger(): 100; // example 2: Get the device model name more precisely now String model = properties.containsKey("model")? properties.get("model").asString(): ""; // example 3: Touch screen optimization boolean useBiggerIcons = properties.contains("touchScreen", true); // example 4: Send Geo Location JS to client? boolean supportsGeoLocation = properties.contains("js.geoLocation", true); // example 5: Get the device orientation (degrees) int deviceOrientation = properties.containsKey("bjs.deviceOrientation")? properties.get("bjs.deviceOrientation").asInteger(): 0; } ``` ### Examples ### Various examples are included in this package to clearly demonstrate the API features, usage and some use cases. These examples are very simple and are heavily commented. #### Basic Usage #### Includes six examples. Three basic command line examples which use DeviceApi to detect and get properties from header sets and client-side component. These examples show how the headers and client-side components help getting precise property values from Opera mini browsers and iPhone devices. Three basic web examples to be used in a servlet container. These examples use the DeviceAtlasWeb and the request object to automatically detect and get the properties for the request. Using the client-side-component is shown in these web examples. #### MultiThreading #### This example contains a versatile class that wrappers around DeviceApi and can be used to process a batch of user-agents or HTTP headers using a thread pool. A command line example application is provided to show all the use cases. #### Redirection #### This web example uses the DeviceApiWeb to get properties for the current request and then uses some basic property values to decide which website provides the most suitable content for the device making the request. #### Content Adaptation #### This web example uses the DeviceApiWeb to get properties for the device making the current request and then uses some basic property values to choose a suitable template to wrap around the content. #### Analytics #### This web example uses the DeviceApi to get properties for user-agents from a given list. Some properties such as vendor, browser name and device type are aggregated and the results are displayed as graphs and numbers. #### Content Targeting #### This example uses the DeviceApiWeb to detect the device and use some of its properties to show certain advertisements and download links which may be related or of interest to the user, considering his/her device. This is a web example. #### Singleton Wrapper #### Example showing how to wrap the DeviceApi in a class and use as a singleton. #### Combined Apis #### Contains examples of using the DeviceAtlas Enterprise API (Device and Carrier APIs) in an application. Also includes a wrapper class to combine the results of the Device and Carrier APIs and present them in one Properties object. Note that in the web examples which use the DeviceApiWeb, the client side properties are taken into account automatically by the API if the cookie exists on the browser. This means if the cookie already exists within your browser you will still see the client side properties in a getProperties call which has not included the DeviceAtlas client side component. You can delete the cookie manually to see the differences between the results from examples which use the client side component and those that don't. To run the web application examples, follow these steps: * Edit the example jsp file and update the data file path. * Run the ANT build file to package the WAR file into dist/ExampleName.war. * Deploy to your test web server. * Run in a browser http://yourwebserver/ExampleName/ to see the results. Alternatively the WAR can be created by hand or with an IDE. Please see the JavaDoc for further example code on how to use the API. ### Upgrading ### If you are currently using a DeviceAtlas Enterprise API version prior to 2.0. Please see the [Upgrade readme file](README.Upgrade.html) for more information. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) 2008-2015 by Afilias Technologies Limited (dotMobi). 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 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="README.Upgrade.html">Device Detection API Upgrade</a></li><li><a href="DeviceApiJavadoc/index.html">Device API Javadoc</a></li><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="CarrierApiJavadoc/index.html">Carrier API Javadoc</a></li><li class="divider"></li><li><a href="README.ClientSide.html">Client-side Component</a></li><li><a href="README.ConnectivityAnalyser.html">Connectivity Analyser</a></li></ul></div>