class DeviceAtlas

Copyright

Copyright © 2014 by mTLD Top Level Domain Limited. All rights reserved.
Portions copyright © 2008 by Argo Interactive Limited.
Portions copyright © 2008 by Nokia Inc.
Portions copyright © 2008 by Telecom Italia Mobile S.p.A.
Portions copyright © 2008 by Volantis Systems Limited.
Portions copyright © 2002-2008 by Andreas Staeding.
Portions copyright © 2008 by Zandan.

Author

dotMobi

Used to load the recognition tree and perform lookups of all properties, or get individual properties. Typical usage is as follows:

deviceAtlas = DeviceAtlas.new
path = File.join(File.dirname(__FILE__), '..', 'data_file/sample.json')
tree = deviceAtlas.getTreeFromFile(path)
properties = deviceAtlas.getProperties(tree, "Nokia6680...")
property = deviceAtlas.getProperty(tree, "Nokia6680...", "displayWidth")

Note that you should normally use the user-agent that was received in the device's HTTP request. In a Rails environment, you would do this as follows:

userAgent = request.env['HTTP_USER_AGENT']
displayWidth = deviceAtlas.getPropertyAsInteger(tree, userAgent,
"displayWidth")

Third-party Browsers:

In some contexts, the user-agent you want to recognise may have been provided in a different header. Opera's mobile browser, for example, makes requests via an HTTP proxy, which rewrites the headers. in that case, the original device's user-agent is in the “X-OperaMini-Phone-UA” header, and the following code could be used:

operaHeader = "X-OperaMini-Phone-UA"
if request.env.include?(operaHeader)
        userAgent = request.env[operaHeader]
else
        userAgent = request.env['HTTP_USER_AGENT']
end
displayWidth = deviceAtlas.getPropertyAsInteger(tree, userAgent,
"displayWidth")

See here for more information: deviceatlas.com/resources/side-loaded-browser-handling

Client side properties:

Client side properties can be collected and merged into the results by using the DeviceAtlas Javascript detection file. The results from the client side are sent to the server inside a cookie. The contents of this cookie can be passed to the DeviceAtlas getProperty and getProperties methods. The client side properties over-ride any data file properties and also serve as an input into additional logic to determine other properties such as the iPhone models that are otherwise not detectable. The following code shows how this can be done in Rails:

userAgent = request.env['HTTP_USER_AGENT']
cookieContents = request.cookies['DAPROPS']
properties = deviceAtlas.getPropertiesAsTyped(tree, userAgent,
cookieContents)

Public Class Methods

new() click to toggle source

Public Instance Methods

getApiRevision() click to toggle source

Return the revision number of the API.

getProperties(tree, userAgent, cookie = nil, typedValues = false, sought = nil, uaPropsNeeded = true) click to toggle source

Return a associative array of known properties merged with properties from the client side JavaScript. The client side JavaScript sets a cookie with collected properties. The contents of this cookie must be passed to this method for it to work. The client properties over-ride any properties discovered from the main JSON data file.

tree: Previously generated associative array tree.
userAgent: The device's User-Agent header string.
cookie: The content of the cookie containing the client side properties.
typedValues: Whether values in the results are typed.
sought: A set of properties to return values for.
uaPropsNeeded: Whether the extra properties from the UA String are

needed.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.properties instead.

getPropertiesAsTyped(tree, userAgent, cookie = nil) click to toggle source

Return an associative array of known properties merged with properties from the client side JavaScript. The client side JavaScript sets a cookie with collected properties. The contents of this cookie must be passed to this method for it to work. The client properties over-ride any properties discovered from the main JSON data file.

tree: Previously generated associative array tree.
userAgent: The device's User-Agent header string.
cookie: The content of the cookie containing the client side properties.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.properties instead.

getProperty(tree, userAgent, property, cookie = nil, typedValue = false) click to toggle source

Return a value for the named property for this user agent.

tree: Previously generated associative array tree.
userAgent: The device's User-Agent header string.
property: The name of the property to return.
cookie: The contents of the cookie containing the client side properties.
typedValue: Whether value in the associative array are typed.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.properties instead.

getPropertyAsBoolean(tree, userAgent, property, cookie = nil) click to toggle source

Strongly typed property access. Return a boolean property (or throws an exception if the property is actually of another type).

tree: Previously generated associative array tree.
userAgent: The device's User-Agent header string.
property: The name of the property to return.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.properties and Mobi::Mtld::Da::Property.to_binstead.

getPropertyAsDate(tree, userAgent, property, cookie = nil) click to toggle source

Strongly typed property access. Returns a date property (or throws an exception if the property is actually of another type).

tree: Previously generated associative array tree.
userAgent: The device's User-Agent header string.
property: The name of the property to return.

DEPRECATED: Date data type is not supported anymore.

getPropertyAsInteger(tree, userAgent, property, cookie = nil) click to toggle source

Strongly typed property access. Return an integer property (or throws an exception if the property is actually of another type).

tree: Previously generated associative array tree.
userAgent: The device's User-Agent header string.
property: The name of the property to return.

DEPRECATED: Please use DeviceApi.properties and Property.to_i instead.

getPropertyAsString(tree, userAgent, property, cookie = nil) click to toggle source

Strongly typed property access. Return a string property (or throws an exception if the property is actually of another type).

tree: Previously generated associative array tree.
userAgent: The device's User-Agent header string.
property: The name of the property to return.

DEPRECATED: Please use DeviceApi.properties and Property.to_s instead.

getTreeFromFile(filename, reload = false, includeChangeableUserAgentProperties = true) click to toggle source

Return a tree from a JSON file. The loaded tree is stored in a static cache to avoid multiple reloads if this method is repeatedly called. To reload from the JSON file set “reload” to true.

Some properties cannot be known before runtime and can change from user-agent to user-agent. The most common of these are the OS Version and the Browser Version. This API is able to dynamically detect these changing properties but introduces a small overhead to do so. To disable returning these extra properties set “includeChangeableUserAgentProperties” to false.

filename: The location of the file to read in. Use an absolute path

name to be sure of success if the current working directory is not clear.

reload: Set true to reload regardless of static cache.
includeChangeableUserAgentProperties: Also detect changeable user-agent

properties.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.load_data_from_file.

getTreeFromString(json, includeChangeableUserAgentProperties = true) click to toggle source

Return a loaded JSON tree from a string of JSON data.

This method does not use the built in static cache.

json: The string of json data.
includeChangeableUserAgentProperties: Also detect changeable user-agent

properties.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.load_data_from_string.

getTreeGeneration(tree) click to toggle source

Get the generation date for this tree.

tree: Hash object with the tree.
return: Date and time the tree was generated.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.data_creation_timestamp.

getTreeGenerationAsTimestamp(tree) click to toggle source

Get the generation date for this tree as a UNIX timestamp.

tree: Hash object with the tree.
return: Timestamp the tree was generated.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.data_creation_timestamp.

getTreeRevision(tree) click to toggle source

Return the revision number of the tree.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.data_revision instead.

listProperties(tree) click to toggle source

Return an associative array of all property names available for all user agents in this tree, with their data type names.

DEPRECATED: Please use Mobi::Mtld::Da::Device::DeviceApi.property_names instead.