<![CDATA[
# DeviceAtlas Device Detection for Web #
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 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 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/mobi/mtld/da/*) ####
Contains the shared classes which are common between the DeviceAtlas APIs.
When using DeviceApi this module must be accessible from your code.
#### DeviceApi (Api/mobi/mtld/da/device/device_api/DeviceApi) ####
The main class 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.
### The 2.x API Interface ###
* DeviceApi is the new standard interface, common across the DeviceAtlas APIs.
* DeviceApi interface is intended to be simple to use, as it includes
custom objects for getting the detected property set and getting a single
property value.
* Unlike the former interface, DeviceApi 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.
### Basic Usage ###
The API can be used as follows:
To lookup the properties by manually passing the Hash of headers to the API:
```python
# (1) create an instance with default API settings
device_api = DeviceApi()
# (2) load the data file
try:
device_api.load_data_from_file("/path/to/apps_datafile.json")
except:
# handle the exceptions related to loading the data file
# (3) look up device properties based on your custom header set
headers = {"HEADER NAME": "HEADER VALUE"}
properties = device_api.get_properties(headers)
# (4) 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
if "displayWidth" in properties:
display_width = int(properties["displayWidth"])
else:
display_width = 100
# example 2: Get the device vendor name
if "vendor" in properties:
vendor = properties.get("vendor")
else:
vendor = ""
# example 3: Touch screen optimization
use_bigger_icons = properties.contains("touchScreen", True)
# example 4: Send Geo Location JS to client?
supports_geo_location = 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 [Client-side 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 Client-side properties are returned to
the server in a cookie called DAPROPS. 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 as
iPhone and iPad models which are normally not detectable.
* For instance, from a class that inherits from BaseHTTPRequestHandler.
To lookup the properties by manually passing the headers and the client-side
properties to the API:
```python
# (1) create an instance with default API settings
device_api = DeviceApi()
# (2) load the data file
try:
device_api.load_data_from_file("/path/to/datafile.json")
except:
# handle the exceptions related to loading the data file
# (3) look up device properties
# the client_side_properties value can be retrieved from the DAPROPS cookie or from a URL parameter
# see the Client-side readme file for more information
client_side_properties = <THE DAPROPS COOKIE VALUE>
properties = device_api.get_properties(self.headers, client_side_properties)
# (4) 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
if "displayWidth" in properties:
display_width = int(properties["displayWidth"])
else:
display_width = 100
# example 2: Get the device vendor name
if "vendor" in properties:
vendor = properties.get("vendor")
else:
vendor = ""
# example 3: Touch screen optimization
use_bigger_icons = properties.contains("touchScreen", True)
# example 4: Send Geo Location JS to client?
supports_geo_location = 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 eight examples. Three simple examples which
use DeviceApi to detect and get properties from header sets and the 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. Five simple web examples with custom API settings. Usage of the
client-side-component is shown in these web examples.
* Command line example:
```
cd Examples/DeviceApi/BasicUsage/cli
python detect.py
python detect_opera.py
python detect_iphone_models.py
```
* Web example:
```
cd Examples/DeviceApi/BasicUsage/web
python examples.py
```
And access http://localhost:3000/examples from the browser.
#### Redirection ####
This web example uses the DeviceApi 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.
```
cd Examples/DeviceApi/Redirection
python example.py
```
And access http://localhost:3000/example from browser.
#### Content Adaptation ####
This web example uses DeviceApi 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.
```
cd Examples/DeviceApi/ContentAdaptation
python example.py
```
And access http://localhost:3000/example from browser.
#### Analytics ####
This web example uses 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.
```
cd Examples/DeviceApi/Analytics
python example.py
```
And access http://localhost:3000/example from browser.
#### Content Targeting ####
This example uses the DeviceApi 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.
```
cd Examples/DeviceApi/ContentTargeting
python example.py
```
And access http://localhost:3000/example from browser.
### 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 2021. 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-Web.html">Device Detection for Web</a></li><li><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.Upgrade.html">Device Detection API Upgrade</a></li><li><a href="ApiDocs/mobi.mtld.da.device.device_api.DeviceApi-class.html">Device API Docs</a></li><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="ApiDocs/mobi.mtld.da.carrier.carrier_api.CarrierApi-class.html">Carrier API Docs</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>]]>