# 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 so it is recommended to download the data file
on a regular basis. This can be done manually from your account page or
in an automated way 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 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();
/* (2) load the data file */
try {
$deviceApi->loadDataFromFile("/path/to/datafile.json");
} 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 _