mobi.mtld.da.device

Class DeviceApi

java.lang.Object

mobi.mtld.da.device.DeviceApi

Direct Known Subclasses:

DeviceApiWeb

public class DeviceApi
extends Object

The DeviceAtlas device detection API provides a way to detect devices based on the HTTP headers. Using the 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 get the properties from a real-time detection on user's device in a servlet container.

The DeviceApi is preferred when you want to get the properties outside 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 the whole HTTP headers. 2- Use the DeviceAtlas client-side-component and pass the result.

When you have limited data you can also use this 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();
     }
 } catch (...
 

Author:

dotMobi

Field Summary

Fields

Modifier and Type	Field and Description
static String	API_VERSION Api version

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
static String	getApiVersion() Get DeviceApi version.
Integer	getDataCreationTimestamp() Get the device data creation (JSON file) timestamp.
int	getDataRevision() Get the device data generation revision.
String	getDataVersion() Get the device data (JSON file) version.
Properties	getProperties(Map<String,String> headers) Get the properties for a set of HTTP headers.
Properties	getProperties(Map<String,String> headers, String clientSideProperties) Get the properties for a set of HTTP headers merged with properties from the client side component.
Properties	getProperties(String userAgent) Get the properties for a User-Agent.
Properties	getProperties(String userAgent, String clientSideProperties) Get the properties for a User-Agent merged with the client-side properties (provided by the DeviceAtlas client side component).
Set<PropertyName>	getPropertyNames() Get a set of all possible property names.
void	loadDataFromClassPath(String fileName) Load the DeviceAtlas device detection data into the API from a JSON file form the class path.
void	loadDataFromFile(String jsonDataFilePath) Load the DeviceAtlas device detection data into the API from a JSON file.
void	loadDataFromStream(InputStream inputStream) Load the DeviceAtlas device detection data into the API from an input stream.

Methods inherited from class java.lang.Object

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

Field Detail

API_VERSION

public static final String API_VERSION

Api version

See Also:

Constant Field Values

Constructor Detail

DeviceApi

public DeviceApi()

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

See Also:

Config

DeviceApi

public DeviceApi(Config config)

Constructs a DeviceApi instance with custom configs.

Parameters:

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

See Also:

Config

Method Detail

loadDataFromClassPath

public void loadDataFromClassPath(String fileName)
                           throws 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 web-site.

Parameters:

fileName - The JSON file-name

Throws:

IOException

DataFileException

DataReadException

JsonException

loadDataFromFile

public void loadDataFromFile(String jsonDataFilePath)
                      throws IOException,
                             DataReadException,
                             FileNotFoundException,
                             JsonException

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

Parameters:

jsonDataFilePath - Path to the JSON file

Throws:

IOException

DataFileException

DataReadException

JsonException

FileNotFoundException

loadDataFromStream

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

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

Parameters:

inputStream - Input stream

Throws:

IOException

DataReadException

JsonException

getPropertyNames

public 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 PropertyName objects. A PropertyName object holds a property-name and it's data-type

getApiVersion

public static String getApiVersion()

Get DeviceApi version.

Returns:

DeviceApi version

getDataVersion

public String getDataVersion()

Get the device data (JSON file) version.

Returns:

The data version

getDataCreationTimestamp

public Integer getDataCreationTimestamp()

Get the device data creation (JSON file) timestamp.

Returns:

The data creation timestamp

getDataRevision

public int getDataRevision()

Get the device data generation revision.

Returns:

Data generation revision

getProperties

public Properties getProperties(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(String userAgent,
                       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 over-ride 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(Map<String,String> headers)

Get the properties for a set of HTTP headers. The DeviceApi gets all the request HTTP headers and will precisely detect the device and find property values by 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(Map<String,String> headers,
                       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 by 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 over-ride 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