# DeviceAtlas Device Detection for Apps # The DeviceAtlas Device Detection API for Apps provides a way to detect devices based on make/model strings. Using the make and model information, 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 . ### Make-Model String Format ### DeviceAtlas expects the make/model string in a specific format. This format consists of values separated by a space character, where the mandatory values are manufacturer and model. The string is the same for all platforms: ``` "Make Model" ``` The term "Make" stands for manufacturer and the term "Model" stands for a model number. It is important to pass the string to the DeviceAtlas API in the lowercase form when using lowercased data file. Other modifications to the make or model strings obtained from the device may result in non-identification or mis-identification. For more information please visit: https://deviceatlas.com/resources/getting-started-enterprise-for-apps ### 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 can be configured to load the latest data file on a regular basis. 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. The data file can be downloaded from your account page or automated via the https://deviceatlas.com/getJSON page. Please see the [Data File Configuration documentation](README.DataFile.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 Carrier API and schedule an auto-download and reload to ensure the API has the latest version of data file. Please see the [Data File Configuration documentation](README.DataFile.html) to obtain the data file download URL and for data file configuration options. ```php $deviceApi = new Mobi_Mtld_DA_Device_DeviceApi(); $dataFileUrl = <data file download URL>; // Load using custom configuration $dataFile = DataFile::Builder($dataFileUrl)->fileDirectory(<persistent download directory>)->buildCarrierDataFile(); $deviceApi->downloadAndLoadDataFileFromUrl($dataFile); // 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. ```php $deviceApi = new Mobi_Mtld_DA_Device_DeviceApi(); // Load data from file path $deviceApi->loadDataFromFile(<data file path>); ``` ### Dependencies ### This library does not depend on any third party libraries. ### Library ### The DeviceAtlas API consists of one package that contains modules with all common API classes plus the additional modules for the Device Detection API. #### DeviceAtlas Common (Api/) #### Contains the shared libraries which are common between the DeviceAtlas APIs. When using the DeviceApi and DeviceApiWeb, the required files from this library will be included automatically by the API. Keep the relative paths of the libraries as they are in the downloaded package. #### DeviceApi (Api/Device/Mobi_Mtld_Da_Device_DeviceApi) #### 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 (Api/Device/Mobi_Mtld_Da_Device_DeviceApiWeb) #### A small extension to the main API that allows automatic extraction of the request headers and client-side properties from the request. It is preferred to use this library for real-time device detections in web applications. #### CacheProvider (Api/CacheProvider/) #### Contains an interface for cache-provider classes that can be used with the DeviceApi and DeviceApiWeb. Also contains three classes which implement the interfaces for APC, Memcache and a file-cache. ### 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 do device lookups based on the request or a whole set of HTTP headers. 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: To lookup the properties by passing the make/model string to the API: * Inside a web application. To lookup the properties of the device which sent the request: ```php // the detection is done based on the current HTTP request // the detection is done based on (HTTP headers) or user-agent string require_once "/path/to/Api/Device/DeviceApi.php"; /* (1) create an instance with default API configs */ $deviceApi = new Mobi_Mtld_DA_Device_DeviceApi(); $dataFile = DataFile::Builder(<data file download URL>)->fileDirectory(<persistent download directory>)->buildDeviceDataFile(); /* (2) download and load the data file */ try { $deviceApi->downloadAndLoadDataFileFromUrl($dataFile); } catch (Exception $x) { // handle the exceptions related to loading the data file } /* (3) look up device properties by make model string */ $makeModel = strtolower("samsung SM-N9005"); $properties = $deviceApi->getProperties($makeModel); /* (4) use the properties - e.g. detect mobile device */ // show properties of device $displayWidth = $properties->containsKey("displayWidth")? $properties->get("displayWidth")->asInteger(): 100; // example 2: Get the device vendor name $vendor = $properties->containsKey("vendor")? $properties->get("vendor")->asString(): ""; // example 3: Touch screen optimization $useBiggerIcons = $properties->contains("touchScreen", true); // example 4: Send Geo Location JS to client? $supportsGeoLocation = $properties->contains("js.geoLocation", true); // example 5: The Properties class implements the magic __get so you can: // if property does not exists then the value will be null // otherwise you get a typed value $model = $properties->model; // null or string $isTablet = $properties->isTablet; // null or boolean $displayHeight = $properties->displayHeight; // null or integer ``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved. https://deviceatlas.com _ _ 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.DeviceApi-Web.html">Device Detection for Web</a></li><li class="disabled"><a href="README.DeviceApi-Apps.html">Device Detection for Apps</a></li><li><a href="README.DeviceApi-Config.html">Device Detection API Config</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="README.Upgrade.html">Device Detection API Upgrade</a></li><li class="divider"></li><li><a href="./DeviceAtlasApiDocs/index.html">DeviceAtlas PHP API Docs</a></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side Component</a></li><li><a href="README.ConnectivityAnalyser.html">Connectivity Analyser</a></li></ul></div>