<![CDATA[
# 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 Ruby gem does only depend on the official "json" gem:
https://rubygems.org/gems/json
### Library ###
The DeviceAtlas Device Detection API consists of three libraries and each
library has a separate gem file.
#### DeviceAtlas common (mobi_mtld_da-x.x.gem) ####
Contains the shared libraries which are common between the DeviceAtlas APIs.
When using DeviceApi and DeviceApiWeb, this gem file must be included in
your gem list.
#### DeviceApi (mobi_mtld_da_device_api-x.x.gem) ####
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.
#### DeviceApi (mobi_mtld_da_device_api_web-x.x.gem) ####
A small extension to the main API that allows an automatic extraction of the
request headers and client-side properties. Unless the request 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 gem
files are required for this library to work.
### The 2.0 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 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 Rails container.
To lookup the properties of the device which sent the request:
```ruby
# the detection is done based on the request object
# (1) include the controller helper into the Rails controller
include Mobi::Mtld::Da::Device::ControllerHelper
# (2) create an instance with default API config
device_api = get_deviceatlas_device_api_web_instance
# (3) load the data file
begin
device_api.load_data_from_file "/path/to/datafile.json"
rescue
# handle the exceptions related to loading the data file
end
# (4) look up device properties
properties = device_api.get_properties request.env
# (5) use the properties - e.g. detect mobile device
# if there is a property named "mobileDevice" and the value is true
# NOTE: properties can be identified by a Symbol or String property name
# indistinctly
if properties.contains?(:mobileDevice, true) # or with the "mobileDevice" string
# example 1: Get the screen width for image optimization
if properties.has_key?:displayWidth
display_width = properties[:displayWidth].to_i
else
display_width = 100
end
# example 2: Get the device vendor name
if properties.has_key?(:vendor)
vendor = properties.get(:vendor)
else
vendor = ""
end
# 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)
end
```
* From a stand-alone script.
To lookup the properties by manually passing the Hash of headers to the API:
```ruby
# (1) create an instance with default API config
device_api = Mobi::Mtld::Da::Device::DeviceApi.new
# (2) load the data file
begin
device_api.load_data_from_file "/path/to/datafile.json"
rescue
# handle the exceptions related to loading the data file
end
# (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
# NOTE: properties can be identified by a Symbol or String property name
# indistinctly
if properties.contains?(:mobileDevice, true) # or with the "mobileDevice" string
# example 1: Get the screen width for image optimization
if properties.has_key?:displayWidth
display_width = properties[:displayWidth].to_i
else
display_width = 100
end
# example 2: Get the device vendor name
if properties.has_key?(:vendor)
vendor = properties.get(:vendor)
else
vendor = ""
end
# 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)
end
```
### 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 Rails container.
To lookup the properties of the device which sent the request:
The usage inside a Rails container, will let you use the client-side
properties if they exist in the cookies.
```ruby
# the detection is done based on request object
# (1) include the controller helper into the Rails controller
include Mobi::Mtld::Da::Device::ControllerHelper
# (2) create an instance with default API config
device_api = get_deviceatlas_device_api_web_instance
# (3) load the data file
begin
device_api.load_data_from_file "/path/to/datafile.json"
rescue
# handle the exceptions related to loading the data file
end
# (4) look up device properties
# NOTE: default cookie name with the client-side properties is "DAPROPS"
client_side_properties = request.cookies[Mobi::Mtld::Da::Device::Config.cookie_name]
properties = device_api.get_properties(request.env, client_side_properties)
# (5) use the properties - e.g. detect mobile device
# if there is a property named "mobileDevice" and the value is true
# NOTE: properties can be identified by a Symbol or String property name
# indistinctly
if properties.contains?(:mobileDevice, true) # or with the "mobileDevice" string
# example 1: Get the screen width for image optimization
if properties.has_key?:displayWidth
display_width = properties[:displayWidth].to_i
else
display_width = 100
end
# example 2: Get the device vendor name
if properties.has_key?(:vendor)
vendor = properties.get(:vendor)
else
vendor = ""
end
# 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)
end
```
* From a stand-alone script.
To lookup the properties by manually passing the headers and the client-side
properties to the API:
```ruby
# (1) create an instance with default API config
device_api = Mobi::Mtld::Da::Device::DeviceApi.new
# (2) load the data file
begin
device_api.load_data_from_file "/path/to/datafile.json"
rescue
# handle the exceptions related to loading the data file
end
# (3) look up device properties
client_side_properties = "PROPERTY1:VALUE1|PROPERTY2:VALUE2|PROPERTY3:VALUE3"
properties = device_api.get_properties(request.env, client_side_properties)
# (4) use the properties - e.g. detect mobile device
# if there is a property named "mobileDevice" and the value is true
# NOTE: properties can be identified by a Symbol or String property name
# indistinctly
if properties.contains?(:mobileDevice, true) # or with the "mobileDevice" string
# example 1: Get the screen width for image optimization
if properties.has_key?:displayWidth
display_width = properties[:displayWidth].to_i
else
display_width = 100
end
# example 2: Get the device vendor name
if properties.has_key?(:vendor)
vendor = properties.get(:vendor)
else
vendor = ""
end
# example 3: Touch screen optimization
use_bigger_icons = properties.contains?(:touchScreen, true)
# example 4: Send Geo Location JS to client?
supports_geo_locatin = properties.contains?(:"js.geoLocation", true)
end
```
### 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 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. Three simple web examples to be used in a Rails container. 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 DeviceApiWeb 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 properties() 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 controller .rb file and update the data file path.
* Copy controllers, views and assets in the respective directories of your Rails project.
* Run in a browser http://yourwebserver/example_name/ to see the results.
### 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. _
<!-- 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.Upgrade.html">Device Detection API Upgrade</a></li><li><a href="DeviceApiDocs/Mobi/Mtld/Da/Device/DeviceApi.html">Device 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><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="CarrierApiDocs/Mobi/Mtld/Da/Carrier/CarrierApi.html">Carrier API docs</a></li></ul></div>]]>