class Mobi::Mtld::Da::Device::DeviceApi

Copyright
Author

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.

DeviceApi.properties(user_agent_or_headers, client_side_properties)

To get the most accurate results: 1- Pass the whole HTTP headers. 2- Use the DeviceAtlas client-side-component and pass the result.

Example usage:

device_api = Mobi::Mtld::Da::Device::DeviceApi.new
device_api.load_data_from_file "/path/to/datafile.json"

# get all properties from the headers
properties = device_api.properties headers

# .... use the properties ....

if properties.contains?("isMobilePhone", true)
  # it is a mobile phone
end

if properties.has_key?("model")
  device_model = properties.get("model").to_s
end

Example usage with custom settings:

settings = Mobi::Mtld::Da::Device::Settings.new

# if you don't use the dynamic user-agent properties such as browser and os
# names
settings.include_ua_props = false

# if you don't use the language and locale properties
settings.include_lang_props = false

device_api = Mobi::Mtld::Da::Device::DeviceApi.new settings

device_api.load_data_from_file "/path/to/datafile.json"

# get all properties from the headers
properties = device_api.properties headers

# .... use the properties ....

if properties.has_key?("model")
  device_model = properties.get("model").to_s
end

Public Class Methods

new(settings = nil) click to toggle source

Constructs a DeviceApi instance with default configs. You can see the default configs in the class “Settings”.

settings

Instance of Settings. You can change the DeviceAtlas API

configs by creating an instance of Settings and setting your custom config values then passing the instance to the DeviceApi constructor.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 79
    def initialize settings = nil
if settings.nil?
  @settings = Mobi::Mtld::Da::Device::Settings.new
else
  @settings = settings
end
    end

Public Instance Methods

api_version() click to toggle source

Get DeviceApi version.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 122
def api_version
  return "2.0"
end
data_creation_timestamp() click to toggle source

Get the device data (JSON file) creation timestamp.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 137
def data_creation_timestamp
  return @tree.data_creation_timestamp
end
data_revision() click to toggle source

Get the device data (JSON file) revision.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 132
def data_revision
  return @tree.data_revision
end
data_version() click to toggle source

Get the device data (JSON file) version.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 127
def data_version
  return @tree.data_version
end
load_data_from_file(json_data_file_path) click to toggle source

Load the DeviceAtlas device detection data into the API from a JSON file form the class path. The JSON data file is provided by the DeviceAtlas web-site.

json_data_file_path

Path to the JSON data file.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 91
def load_data_from_file json_data_file_path
  if !File.file?(json_data_file_path)
    raise Mobi::Mtld::Da::Exception::DataFileException,
      "File not found: #{json_data_file_path}"
  end
  json = File.open(json_data_file_path, "r").read
  load_data_from_string json
end
load_data_from_string(json_data_string) click to toggle source

Load the DeviceAtlas device detection data into the API from a string.

json_data_string

JSON data string.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 102
def load_data_from_string json_data_string
  @tree = Mobi::Mtld::Da::Device::Tree.new json_data_string, @settings
end
properties(user_agent_or_headers, client_side_properties = nil) click to toggle source

Get known properties from a User-Agent or HTTP headers optionally merged with properties from the client side component. The client side component (JS) sets a cookie with collected properties. The client properties will over-ride any properties discovered from the main JSON data file.

user_agent_or_headers

User-Agent string or array of HTTP headers.

client_side_properties

String of client side properties with the format

the client side component provides.

return

Array of Property objects.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 151
def properties user_agent_or_headers, client_side_properties = nil
  get_new_properties = false

  if @cached_client_side_properties.nil? ||
      @cached_client_side_properties != client_side_properties
    @cached_client_side_properties = client_side_properties
    get_new_properties = true
  end

  # Just a UA
  if user_agent_or_headers.kind_of?String

    if @cached_user_agent.nil? || @cached_user_agent != user_agent_or_headers
      @cached_user_agent = user_agent_or_headers
      @cached_headers = nil
      get_new_properties = true
    end

    if get_new_properties
      @tree.put_properties(@cached_user_agent, @cached_headers,
        @cached_client_side_properties)
      @properties = @tree.properties
    end

  # Headers
  else

    if @cached_headers.nil? || @cached_headers != user_agent_or_headers
      @cached_user_agent = nil

      # make header keys lower-cased with no underlines
      @cached_headers = normalise_keys user_agent_or_headers

      @properties = get_properties_from_headers(@cached_headers,
        @cached_client_side_properties)
      # add language and locale properties
      if @settings.include_lang_props
        add_language_properties @cached_headers
      end
    end

  end

  if @properties.empty? && @settings.return_nil_when_no_properties
    return nil
  end

  return @properties
end
property_names() click to toggle source

Get a set of available device property names. return: Array of PropertyName objects.

# File ../../device_api/trunk/ruby/src/lib/device_api.rb, line 108
def property_names
  property_names = []
  property_type_name = @tree.property_names
  max_property_names = property_type_name.size - 1
  for i in 0..max_property_names
    property_names.push(
      Mobi::Mtld::Da::PropertyName.new(
        property_type_name[i][1..property_type_name[i].length],
        get_property_as_byte(property_type_name[i][0])))
  end
  return property_names
end