<![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
in an automated way via https://deviceatlas.com/getJSON page.
For more information please see:
https://deviceatlas.com/resources/getting-the-data
### Library ###
The DeviceAtlas Enterprise API comprises one Gem file which includes both the
Device and Carrier Identification APIs.
The Device Detection API namespace and main class is: **DeviceAtlas::Device::DeviceApi**
There is also an API wrapper that lets you use the main API as a filter from a
Rails controller to transparently use the user's HTTP headers: **DeviceAtlas::Device::DeviceApiWeb**
### Dependencies ###
This library does not depend on any third party libraries.
### Input ###
The API can be queried by passing any of the following to the get_properties() method.
1. A **User-Agent** string.
2. A **Hash** of HTTP Header names to HTTP Header values.
3. An **[Net::HTTP]** request object.
### Basic Usage ###
The API has a very simple interface and can be used as follows:
_Initialize API_
```ruby
require 'deviceatlas'
device_api = DeviceAtlas::Device::DeviceApi.new
device_api.load_data_from_file "/path/to/datafile.json"
```
_Get the properties_
```ruby
user_agent = "Mozilla/5.0 (Linux; U; Android 4.1.2; en-ph; GT-N8000 Build/JZO54K) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Safari/534.30"
properties = device_api.get_properties(user_agent)
```
_Use the properties_
```ruby
if !properties.nil?
puts("Marketing Name: #{properties[:marketingName]}")
end
```
Note: When using the library inside a Rails container it is recommended to implement
the API as a singleton. This eliminate the JSON data file loading overhead on each
request. See **Examples/device/basic_usage_web/** for further details.
### 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 Component](README.ClientSide.html) readme file
for more information.
#### Usage with 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-cdn.deviceatlas.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-cdn.deviceatlas.com/dacs.js" async></script>
```
_Inside a Rails container_
```ruby
device_api_web = DeviceAtlas::Device::DeviceApiWeb.new
device_api_web.load_data_from_file "/path/to/datafile.json"
properties = device_api_web.get_properties(request)
```
_From a stand-alone script_
```ruby
device_api = DeviceAtlas::Device::DeviceApi.new
device_api.load_data_from_file "/path/to/datafile.json"
user_agent = <USER AGENT STRING>
client_side = <THE DAPROPS COOKIE VALUE>
properties = device_api.get_properties(user_agent, client_side)
```
### Included Examples ###
Please see the **Examples/device/** directory for more examples:
1. **basic_usage_cli_detect** - simple example using the API
2. **basic_usage_cli_detect_iphone_models** - an example with the Client-side Component
3. **basic_usage_cli_detect_list_of_uas** - shows how the API can be used for batch processing
4. **basic_usage_cli_detect_opera** - shows how to handle the side-loaded browsers
5. **basic_usage_web** - controller and viewer files for Rails projects
### Upgrading ###
If you are currently using a DeviceAtlas Enterprise API version prior to 2.1.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/DeviceAtlas/Device/DeviceApi.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/DeviceAtlas/Carrier/CarrierApi.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><li><a href="README.ConnectivityAnalyser.html">Connectivity Analyser</a></li></ul></div>]]>