# DeviceAtlas Cloud Client API #
DeviceAtlas Cloud is a web service that can return device information such
as screen width, screen height, is mobile, vendor, model etc. To see a full
list of properties, please visit
https://deviceatlas.com/resources/available-properties .
This Client API provides an easy way to query DeviceAtlas Cloud. It provides the
ability to cache returned data locally to greatly improve performance and has
automatic failover should one of the global DeviceAtlas Cloud endpoints become
unavailable. As of version 1.2, the Client API is able to leverage data
collected by the DeviceAtlas Client Side Component. This data is sent to
DeviceAtlas Cloud to augment the data found from the normal HTTP headers and
also allows the detection of the various iPhone and iPad models.
### Compatibility ###
The DeviceAtlas Cloud Ruby gem is compatible with Ruby 1.8.7, 1.9.3 and 2.0
releases. It can be used inside any stand-alone script or Rails project.
### Dependencies ###
The Ruby Cloud API depends on the following libraries and gems:
- socket
- tmpdir
- cgi
- json
- digest
### Configuration ###
The DeviceAtlas Cloud Client is configured by setting the "settings" property of
the client instance (e.g. client.settings).
The only required property is your DeviceAtlas licence key:
client.settings.licence_key
Note: as of version 1.4 the API throws exceptions on errors and failures unless
the class attribute "debug_mode" in Settings is set to false. It is recommended
to keep "debug_mode" set to true during implementation time.
#### Basic Usage ####
The DeviceAtlas Cloud Client API can be used as follows:
* Install the Ruby Client API gem.
```bash
gem install deviceatlas_cloud_client-X.X.gem
# Add the installed "deviceatlas_cloud_client" gem to the Gemfile of your
# Rails project if needed.
```
* Include the Client API gem and the controller helper at your Rails controller.
```ruby
# Client API gem
require 'deviceatlas_cloud_client'
class ExampleController < ActionController::Base
# Include the Controller helper
include DeviceAtlasCloudClient::ControllerHelper
def index
# ...
end
```
* Get a client instance and set your DeviceAtlas Cloud licence key.
```ruby
# Get the client instance (singleton) and set your licence key
client = get_deviceatlas_cloud_client_instance
client.settings.licence_key = 'YOUR_LICENCE_KEY'
```
* Get the properties (recommended usage)
When "debug_mode" = true and API version is 1.4 or higher:
```ruby
begin
# Get device data without passing any parameter.
# It will let the API use the default request headers for detection.
device_data = client.get_device_data
# Get the properties
if device_data.has_key?DeviceAtlasCloudClient::KEY_PROPERTIES
properties = device_data[DeviceAtlasCloudClient::KEY_PROPERTIES]
end
rescue Exception => e
# Handle exception
end
```
Alternative ways to get the properties (optional)
```ruby
# Passing a user-agent string (useful for stand-alone scripts)
device_data = client.get_device_data(user_agent_string)
```
```ruby
# Passing a hash of headers (useful for stand-alone scripts)
device_data = client.get_device_data(user_headers_hash)
```
```ruby
# Passing explicitly request headers from a framework such as Rails.
# Not needed on Rails as Controller helper will transparently use the
# headers.
device_data = client.get_device_data(request)
```
* Use the device properties.
```ruby
if properties.has_key?:mobileDevice && properties.get(:mobileDevice)
# example 1: Get the screen width for image optimization
if properties.has_key?:displayWidth
display_width = properties.get(:displayWidth)
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.has_key?:touchScreen &&
properties.get(:touchScreen)
# example 4: Send Geo Location JS to client?
supports_geo_location = properties.has_key?"js.geoLocation" &&
properties.get("js.geoLocation")
end
```
See the list of all property names here:
https://deviceatlas.com/resources/available-properties
The availability of a property depends on the device and your licence,
before accessing a property always check if it exists in the set or not.
When "debug_mode" = false or API version is < 1.4:
```ruby
# Get the client instance (singleton) and set your licence key
client = get_deviceatlas_cloud_client_instance
client.settings.licence_key = 'YOUR_LICENCE_KEY'
# Use headers from request
device_data = client.get_device_data
# Get the properties
if device_data.has_key?DeviceAtlasCloudClient::KEY_ERROR
puts device_data[DeviceAtlasCloudClient::KEY_ERROR]
else
properties = device_data[DeviceAtlasCloudClient::KEY_PROPERTIES]
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 two examples. One simple command line examples which use API to detect
and get properties from header sets. The other example is a web application to
be used in a Rails controller. This example uses the API with the request object
to automatically detect and get the properties for the request. Using custom API
configs and the client-side-component is shown in this example.
* Command line example:
```
cd Examples/BasicUsage/cli
ruby detect.rb
```
* Web example:
Copy to the right dirs of a Rails project, files from Examples/BasicUsage/web.
And access http://localhost:3000/cloud_basic_usage_examples from browser.
#### Redirection ####
This web example uses the API 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.
* Web example:
Copy to the right dirs of a Rails project, files from Examples/Redirection
And access http://localhost:3000/cloud_redirection_example from browser.
#### Content Adaptation ####
This web example uses the API 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.
* Web example:
Copy to the right dirs of a Rails project, files from Examples/ContentAdaptation
And access http://localhost:3000/cloud_content_adaptation_example from browser.
#### Analytics ####
This web example uses the API 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.
* Web example:
Copy to the right dirs of a Rails project, files from Examples/Analytics
And access http://localhost:3000/cloud_analytics_example from browser.
#### Content Targeting ####
This example uses the API 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.
* Web example:
Copy to the right dirs of a Rails project, files from Examples/ContentTargeting
And access http://localhost:3000/cloud_content_targeting_example from browser.
Note that in the web examples which use the API, 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 the result even when the DeviceAtlas client side
component is not added to the page. 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.
### Caching ###
The API can cache the returned data after a call to the DeviceAtlas Cloud service,
this will speed up subsequent requests.
The API has a file caching mechanism. It is recommended to always use the file
cache if possible.
The file cache stores the returned properties on your server disk. The cache
location is typically the system temp directory but this can be overridden with
the "client.settings.custom_cache_dir" constant. Items in the cache expire after
a set time period to ensure the data is up-to-date. This cache is enabled by
default. It is recommended to always have file caching enabled even when you are
using cookie cache.
Items in the cache expire after a set time period to ensure the data is up-to-date.
### 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. Both sets of properties are
used in additional logic to determine other properties such iPhone and iPad
models which are normally not detectable.
By default, if the cookie exists it will be used by the API. To disable using
the client side cookie:
```ruby
client.settings.use_client_cookie = false
```
### DeviceAtlas Cloud Service End-points ###
The DeviceAtlas Cloud Service is powered by independent clusters of servers
spread around the world. This ensures optimum speed and reliability. The API is
able to automatically switch to a different end-point if the current end-point
becomes unavailable. It can also (optionally) auto-rank all of the service
end-points to choose the end-point with the lowest latency for your location.
The Cloud service provider servers are defined in the "client.settings.servers"
variable when a client instance is created.
```ruby
client.settings.servers = [
{:host => 'server1-url', :port => server1-port},
{:host => 'server2-url', :port => server2-port},
{:host => 'server3-url', :port => server3-port}
]
```
By default the API will analyze the end-points from time to time to rank them by
their stability and response speed. The ranked list is then cached and used
whenever the Client API needs to query the DeviceAtlas Cloud Service. If an end-
point fails, the Client API will automatically switch to the next end-point on
the list.
There is no need to set the servers array if auto-ranking is turned on. If you
wish, you may re-order the array and turn auto-ranking off. In this case the API
will respect your preferred order of end-points and only switch to a different
end-point should the primary one fail to resolve.
#### Notes ####
* With the default auto-ranking settings, the ranking is done every 24 hours.
The actual time may be more than 24 hours as the ranking is only triggered by
a request to the Client API and the cached server list is older than value
set to client.settings.auto_server_ranking_lifetime.
* During end-point analysis a number of requests are made to each end-
point. Please note that these requests count towards your total hits to
the Cloud service.
e.g:
```ruby
if
client.settings.server contains 3 servers
client.settings.auto_server_ranking_lifetime = 1440
client.settings.auto_server_ranking_num_requests = 3
then
auto ranking will add 9 (3x3) hits per day
```
#### Methods ####
* Get the ranked server list:
```ruby
ranked_server_list = client.servers
```
The first end-point in the list will be used to make a request to the cloud, if
it fails the next end-point will be take it's place.
* Get the end-point used for the last request:
```ruby
server = client.get_cloud_url
```
Note that if data comes from cache this method will return "nil".
* Get end-point info. This is useful when you want to manually rank the server list:
```ruby
server = client.get_servers_latencies
```
Please see https://deviceatlas.com/resources/cloud-service-end-points for more
information.
#### Cloud Server end-point settings ####
You can set multiple server end-point settings from the "client.settings"
property of your client instance.
##### auto_server_ranking = true #####
To turn auto ranking on/off. To manually rank the servers set to "false"
and edit the SERVERS list to set your preferred order of end-points.
The API will not rank the servers and will use the SERVERS list items
directly with the topmost server used first to get device data. On fail-
over the next end-point in the list will be used.
##### cloud_service_timeout = 2 #####
Time in seconds. If an end-point fails to respond in this amount of time
the API will fail-over to the next end-point on the list.
##### auto_server_ranking_max_failures = 1 #####
When auto ranking servers, if a server fails more than this number of
times it will not be included in the list.
##### auto_server_ranking_num_requests = 3 #####
When auto ranking servers, number of requests to perform for service
speed calculation.
##### auto_server_ranking_lifetime = 1440 #####
Time in minutes. How often to auto rank servers.
0 = servers will be ranked and cached only once and this list will not
be updated automatically. You can update this list manually:
client.rank_servers
Note: auto_server_ranking must be set to true so this cached server list
will be used by the API even if auto_server_ranking_lifetime is set to 0
Note: If auto_server_ranking = false then the cached server list will be
totally ignored.
##### server_phaseout_lifetime = 1440 #####
Used when auto ranking is OFF. Specifies how long to use the fail-over
endpoints before the preferred end-point is re-checked. If the preferred
end-point is available it will be added back into the list of end-points
and used for future requests.
### Extra Tools ###
This package comes with extra tools that can help you enhance your mobile websites.
#### DeviceAtlas Client Side Component ####
This is the DeviceAtlas Client Side component which discovers device info on
client side to augment the server data.
This library is used in the DeviceAtlas Cloud Client API examples.
#### Latency Checker ####
There are two command line tools included in this package to help you tweak the
DeviceAtlas Cloud API end-point selecting.
##### Check Server Latency #####
This tool can be used to get info about the DeviceAtlas Cloud Service end-points.
The info shown can be used for manually setting up the DeviceAtlas Clous service
end-points in the API. To access the cloud servers a valid DeviceAtlas licence
would be required.
Usage (command line):
```ruby
ruby /path/to/ExtraTools/LatencyChecker/check_server_latency.rb
```
##### Update Server Ranking Cache #####
When client.settings.auto_ranking is set ON you can use this tool to re rank the DeviceAtlas Cloud
end-points. All you need to do is to run this script in regular intervals which
are smaller than the client.settings.auto_server_ranking_lifetime.
Usage (command line):
```ruby
ruby /path/to/ExtraTools/LatencyChecker/update_server_ranking_cache.py
```
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) 2021 by DeviceAtlas Limited. All rights reserved. https://deviceatlas.com _