mobi.mtld.da.device

Class DeviceApi

java.lang.Object

mobi.mtld.da.BaseDeviceAtlasApi

mobi.mtld.da.device.DeviceApi

All Implemented Interfaces:

DeviceAtlasApi

Direct Known Subclasses:

DeviceApiWeb

public class DeviceApi
extends BaseDeviceAtlasApi

The DeviceAtlas device detection API provides a way to detect devices based on the HTTP headers. Using these headers, the API returns device properties such as screen width, screen height, is mobile, vendor, model etc. If you want to use the DeviceAtlas API in a servlet container then it is strongly recommended to use DeviceApiWeb instead of this library.

The DeviceApiWeb is preferred when you want to perform real-time detection of a user's device in a servlet container.

The DeviceApi is preferred when you want to perform device outside of a servlet container or from an off-line User-Agent list or header set.

getProperties(Map headers, String clientSide).

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

When you have limited data you can also use these alternatives:

getProperties(Map headers).

getProperties(String userAgent, String clientSide).

getProperties(String userAgent).

Example usage:

 Map headers = new HashMap();
 headers.put("user-agent", "...");
 headers.put("accept-language", "...");
 // add any other available header...

 DeviceApi deviceApi = new DeviceApi();

 try {
     DeviceApi.loadDataFromFile("/path/to/datafile.json");

     // get all properties from the headers
     Properties props = DeviceApi.getProperties(headers);

     // .... use the properties ....
     if (props.contains("isMobilePhone", true)) {
         // it is a mobile phone
     }
     if (props.containsKey("model")) {
         String deviceModel = props.get("model").asString();
     }
     if (props.containsKey("yearReleased")) {
         int deviceModel = props.get("yearReleased").asInteger();
     }
 } catch (...
 

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	API_VERSION

Constructor Summary

Constructors

Constructor and Description
DeviceApi() Constructs a DeviceApi instance with default config.
DeviceApi(Config config) Constructs a DeviceApi instance with custom config.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	getApiVersion()
java.lang.Integer	getDataCreationTimestamp()
int	getDataRevision() Deprecated. use getDataCreationTimestamp() for comparing data generation
java.lang.String	getDataVersion()
java.lang.String	getDeviceAtlasApiVersion()
Properties	getProperties(java.util.Map<java.lang.String,java.lang.String> headers) Get the properties for a map of HTTP headers.
Properties	getProperties(java.util.Map<java.lang.String,java.lang.String> headers, java.lang.String clientSideProperties) Get the properties for a set of HTTP headers merged with properties from the Client-side component.
Properties	getProperties(java.lang.String userAgent) Get the properties for a User-Agent.
Properties	getProperties(java.lang.String userAgent, java.lang.String clientSideProperties) Get the properties for a User-Agent merged with the client side properties (provided by the DeviceAtlas Client-side component).
java.util.Set<PropertyName>	getPropertyNames() Get a set of all possible property names.
void	loadDataFromClassPath(java.lang.String fileName) Load the DeviceAtlas device detection data into the API from a JSON file form the class path.
void	loadDataFromFile(java.lang.String jsonDataFilePath) Load the DeviceAtlas device detection data into the API from a JSON file.
void	loadDataFromStream(java.io.InputStream inputStream) Load the DeviceAtlas device detection data into the API from an input stream.
void	setConfig(Config config) Updates the DeviceApi instance with a new config.

Methods inherited from class mobi.mtld.da.BaseDeviceAtlasApi

downloadAndLoadDataFile, downloadAndLoadDataFile, getDetectionLookupCount, isDataFileReload, resetDetectionLookupCount

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

API_VERSION

public static final java.lang.String API_VERSION

See Also:

Constant Field Values

Constructor Detail

DeviceApi

public DeviceApi()

Constructs a DeviceApi instance with default config. You can see the default config here: Config.

See Also:

Config

DeviceApi

public DeviceApi(Config config)

Constructs a DeviceApi instance with custom config.

Parameters:

config - An instance of Config, you can change the DeviceAtlas API config by creating an instance or Config and setting your custom config values and then passing the instance to the DeviceApi constructor.

See Also:

Config

Method Detail

setConfig

public void setConfig(Config config)

Updates the DeviceApi instance with a new config.

Parameters:

config - An instance of Config, you can change the DeviceAtlas API config by creating an instance or Config and setting your custom config values and then passing the instance to this method.

See Also:

Config

loadDataFromClassPath

public void loadDataFromClassPath(java.lang.String fileName)
                           throws java.io.IOException,
                                  DataReadException,
                                  DataFileException,
                                  JsonException

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 website.

Parameters:

fileName - The JSON file-name

Throws:

java.io.IOException

DataFileException

DataReadException

JsonException

loadDataFromFile

public void loadDataFromFile(java.lang.String jsonDataFilePath)
                      throws java.io.IOException,
                             DataReadException,
                             java.io.FileNotFoundException,
                             JsonException

Load the DeviceAtlas device detection data into the API from a JSON file. The JSON data file is provided by the DeviceAtlas website.

Parameters:

jsonDataFilePath - Path to the JSON file

Throws:

java.io.IOException

DataReadException

java.io.FileNotFoundException

JsonException

loadDataFromStream

public void loadDataFromStream(java.io.InputStream inputStream)
                        throws java.io.IOException,
                               DataReadException,
                               JsonException

Load the DeviceAtlas device detection data into the API from an input stream.

Parameters:

inputStream - Input stream

Throws:

java.io.IOException

DataReadException

JsonException

getPropertyNames

public java.util.Set<PropertyName> getPropertyNames()

Get a set of all possible property names. Note that the client side properties are not included in this set.

Returns:

A set of all possible device property names as PropertyNameType objects. A PropertyNameType object holds a property-name and its data-type

getApiVersion

public static java.lang.String getApiVersion()

Returns:

DeviceApi version

getDataVersion

public java.lang.String getDataVersion()

Returns:

The device data (JSON file) version.

getDataCreationTimestamp

public java.lang.Integer getDataCreationTimestamp()

Returns:

The device data creation (JSON file) timestamp.

getDataRevision

@Deprecated
public int getDataRevision()

Deprecated. use getDataCreationTimestamp() for comparing data generation

Get the device data generator revision.

Returns:

Data generation revision

getProperties

public Properties getProperties(java.lang.String userAgent)

Get the properties for a User-Agent.

Parameters:

userAgent - The User-Agent string

Returns:

A set of properties (Property objects) wrapped in a Properties object

getProperties

public Properties getProperties(java.lang.String userAgent,
                                java.lang.String clientSideProperties)
                         throws ClientPropertiesException

Get the properties for a User-Agent merged with the client side properties (provided by the DeviceAtlas Client-side component). The DeviceAtlas Client-side component (JavaScript library) collects the client-side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will override any properties discovered from the main JSON data file.

Parameters:

userAgent - The User-Agent string

clientSideProperties - The contents of the cookie containing the client side properties

Returns:

A set of properties (Property objects) wrapped in a Properties object

Throws:

ClientPropertiesException

getProperties

public Properties getProperties(java.util.Map<java.lang.String,java.lang.String> headers)

Get the properties for a map of HTTP headers. The DeviceApi gets all the request HTTP headers and will precisely detect the device and find property values for all usable headers.

Parameters:

headers - Client's request HTTP headers

Returns:

A set of properties (Property objects) wrapped in a Properties object

getProperties

public Properties getProperties(java.util.Map<java.lang.String,java.lang.String> headers,
                                java.lang.String clientSideProperties)
                         throws ClientPropertiesException

Get the properties for a set of HTTP headers merged with properties from the Client-side component. The DeviceApi gets all the request HTTP headers and will precisely detect the device and find property values for all usable headers. Get the properties for a User-Agent merged with the client side properties (provided by the DeviceAtlas Client-side component). The DeviceAtlas Client-side component (JavaScript library) collects the client side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will override any properties discovered from the main JSON data file.

Parameters:

headers - Client's request HTTP headers

clientSideProperties - The contents of the cookie containing the client side properties

Returns:

A set of properties (Property objects) wrapped in a Properties object

Throws:

ClientPropertiesException

getDeviceAtlasApiVersion

public java.lang.String getDeviceAtlasApiVersion()