com.deviceatlas.device

Class DeviceApi

java.lang.Object

com.deviceatlas.BaseDeviceAtlasApi

com.deviceatlas.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<String, String> 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<String, String> headers).

getProperties(String userAgent, String clientSide).

getProperties(String userAgent).

Example usage:

 Map<String, String> 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 (...) {
     ...
 }
 

Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved.

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() The version of this API.
java.lang.String	getDataCreationIso8601() The creation date/time of the loaded data file in ISO 8601 format.
java.lang.Integer	getDataCreationTimestamp() The creation date/time of the loaded data file as a Unix timestamp.
java.lang.String	getDataVersion() The version of the data file.
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 clientSideString) Get the properties for a set of HTTP headers merged with properties from the Client-side component.
Properties	getProperties(java.lang.String identifier) Get the properties for the provided identifier.
Properties	getProperties(java.lang.String identifier, java.lang.String clientSideString) Get the properties for an identifier 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.

Methods inherited from class com.deviceatlas.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

loadDataFromClassPath

public void loadDataFromClassPath(java.lang.String fileName)
                           throws DataLoadingException

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:

DataLoadingException

loadDataFromFile

public void loadDataFromFile(java.lang.String jsonDataFilePath)
                      throws DataLoadingException

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:

DataLoadingException

loadDataFromStream

public void loadDataFromStream(java.io.InputStream inputStream)
                        throws DataLoadingException

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

Parameters:

inputStream - Input stream

Throws:

DataLoadingException

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 PropertyName objects.

getApiVersion

public static java.lang.String getApiVersion()

The version of this API.

Returns:

DeviceApi version

getDataVersion

public java.lang.String getDataVersion()

The version of the data file.

Returns:

The device data file version.

getDataCreationTimestamp

public java.lang.Integer getDataCreationTimestamp()

The creation date/time of the loaded data file as a Unix timestamp.

Returns:

The creation date/time of this data file as a Unix timestamp.

getDataCreationIso8601

public java.lang.String getDataCreationIso8601()

The creation date/time of the loaded data file in ISO 8601 format.

Returns:

The creation date/time of the loaded data file in ISO 8601 format.

getProperties

public Properties getProperties(java.lang.String identifier)

Get the properties for the provided identifier. The identifier may be a User-Agent string, Client Hints model or if enabled in the data file an app "Make Model" string.

Parameters:

identifier - The identifier string to identify

Returns:

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

getProperties

public Properties getProperties(java.lang.String identifier,
                                java.lang.String clientSideString)
                         throws ClientPropertiesException

Get the properties for an identifier 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:

identifier - An identifier such as a User-Agent or Client Hints model.

clientSideString - 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 clientSideString)
                         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

clientSideString - 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()