# DeviceAtlas Device Detection # The DeviceAtlas Device Detection API for web 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. The DeviceAtlas API has the capability to automatically download and load the latest data file on a scheduled basis. Please note that basic telemetry data such as the number of API lookups are collected when using the download and load functionality. If however your integration cannot make use of the automatic download and load feature 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. #### Loading the data file #### The DeviceAtlas API provides multiple methods to load the data file. ##### Downloading and loading the data file ##### The following examples download the data file, save it to the file system, load it into the DeviceAtlas API and schedule a background task to download and load a fresh data file at a configured time in the future. Please see the [Data File Configuration documentation](README.DataFileConfig.html) to obtain the data file download URL and for data file configuration options. ```csharp using Mobi.Mtld.DA.Device; using Mobi.Mtld.DA.DataFile; DeviceApi deviceApi = new DeviceApi(); string dataFileUrl = <data file download URL>; // Load using custom configuration DataFileConfig dataFileConfig = DataFileConfigBuilder.Create(<data file download URL>).FileDirectory(<persistent download directory>).BuildDevice(); deviceApi.DownloadAndLoadDataFile(dataFileConfig); // Load using default configuration deviceApi.DownloadAndLoadDataFile(dataFileUrl); ``` ##### Loading an existing data file ##### The following examples show how to load a data file that is already on the filesystem. ```csharp using Mobi.Mtld.DA.Device; DeviceApi deviceApi = new DeviceApi(); // Load data from file path deviceApi.LoadDataFromFile(<data file path>); // Load data from a Stream deviceApi.LoadDataFromStream(<Stream instance>); ``` ### 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. It is strongly recommended to use the Client-side component when using the DeviceAtlas API within a web application in order to correctly identify iOS devices. The client side resource (https://cs.deviceatlas-cdn.com/dacs.js) must be included on your webpage in order for it to detect the client side properties. The contents of this cookie are automatically detected by the API. Please click [here](https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html) for more information. ``` <!-- 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> ``` ### Basic Usage ### The API can be used as follows: #### Detection in a Web Application Context #### Create an API instance and load the data file when the servlet starts: ##### Initialize Device API (.NET Framework) ##### It is recommended to instantiate the API inside Application_Start() method inside Global.asax or Global.asax.cs: Global.asax: ```csharp <%@ Application Language="C#" Inherits="Global" %> ``` Global.cs: ```csharp using Mobi.Mtld.DA.Device; public class Global : System.Web.HttpApplication { void Application_Start(object sender, EventArgs e) { // load the data file in a try/catch block as several exceptions may be thrown try { DeviceApiWeb deviceApi = new DeviceApiWeb(); deviceApi.DownloadAndLoadDataFile(<data file download URL>); // store the DeviceApiWeb instance in Application state Application.Lock(); Application["deviceApi"] = deviceApi; Application.UnLock(); } catch (System.Exception e) { // handle the exceptions related to loading the data file } } } ``` ##### Initialize Device API (.NET Core) ##### It is recommended to instantiate the API as a singleton during service configuration. Setup class: ```csharp using Mobi.Mtld.DA.Device; public void ConfigureServices(IServiceCollection service) { service.AddMvc(); try { DeviceApiWebCore deviceApi = new DeviceApiWebCore(); deviceApi.DownloadAndLoadDataFile(<data file download URL>); service.AddSingleton(deviceApi); } catch (System.Exception e) { // handle exception } } ``` Lookup the device properties when processing requests (.NET Framework): ```csharp using Mobi.Mtld.DA; using Mobi.Mtld.DA.Device; /* (1) get the DeviceApiWeb instance from the Application state */ DeviceApiWeb deviceApi = (DeviceApiWeb)Application["deviceApi"]; /* (2) look up device properties by current request */ Properties properties = deviceApi.GetProperties(); ``` Lookup the device properties when processing requests (.NET Core): ```csharp using Mobi.Mtld.DA; using Mobi.Mtld.DA.Device; /* (1) get the DeviceApiWeb instance from the configured services */ DeviceApiWebCore deviceApi = HttpContext.RequestServices.GetService<DeviceApiWebCore>(); /* (2) look up device properties by current request */ Properties properties = deviceApi.GetProperties(HttpContext.Request); ``` #### Detection via user-agent #### Lookup the properties by passing a user-agent string to the API: ```csharp using Mobi.Mtld.DA; using Mobi.Mtld.DA.Device; using Mobi.Mtld.DA.Exception; try { DeviceApi deviceApi = new DeviceApi(); deviceApi.DownloadAndLoadDataFile(<data file download URL>); string userAgent = "THE USER AGENT VALUE"; Properties properties = deviceApi.GetProperties(userAgent); } catch (DataFileException x) { // handle the exceptions related to loading the data file } ``` #### Detection via Make/Model #### Lookup the properties by passing a Make/Model string to the API. 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). ```csharp using Mobi.Mtld.DA; using Mobi.Mtld.DA.Device; using Mobi.Mtld.DA.Exception; DeviceApi deviceApi = new DeviceApi(); try { DeviceApi deviceApi = new DeviceApi(); deviceApi.DownloadAndLoadDataFile(<data file download URL>); string makeModel = "samsung sm-n9005"; Properties properties = deviceApi.getProperties(makeModel); } catch (DataFileException x) { // handle the exceptions related to loading the data file } ``` #### Use The Properties #### ```csharp // 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["displayWidth"].AsInteger(): 100; // example 2: Get the device vendor name string vendor = properties.ContainsKey("vendor")? properties["vendor"].AsString(): ""; // example 3: Touch screen optimization bool useBiggerIcons = properties.Contains("touchScreen", true); // example 4: Send Geo Location JS to client? bool supportsGeoLocation = properties.Contains("js.geoLocation", true); } ``` #### 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 several examples. A few simple 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. There is also an example showing how to batch process User-Agents. The web examples use the DeviceAtlasWeb wrapper 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. #### 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. 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. ### 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) DeviceAtlas Limited 2022. 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><a href="README.DataFileConfig.html">Data File Configuration</a></li><li class="disabled"><a href="README.DeviceApi.html">Device Detection</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="./DeviceApiDocs/classes.html">Device API Docs</a></li><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="./CarrierApiDocs/classes.html">Carrier API 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>