< and
the [Device Data guide](https://deviceatlas.com/resources/getting-the-data/device-data)
for more information.
### Loading the data file ###
The DeviceAtlas API provides multiple methods to load the data file.
#### Downloading and loading the data file ####
The following examples download the data file, save it to the file system,
load it into the DeviceAtlas API and schedule a background task to download and load
a fresh data file at a configured time in the future.
Please see the [Data File Configuration documentation](README.DataFile.html)
to obtain the data file download URL and for data file configuration options.
```java
DeviceApi deviceApi = new DeviceApi();
String dataFileUrl = <data file download URL>;
// Load using custom configuration
DataFile dataFile = new DataFile.Builder(dataFileUrl).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile);
// Load using default configuration
deviceApi.downloadAndLoadDataFile(dataFileUrl);
```
#### Loading an existing data file ####
The following examples show how to load a data file that is already on the filesystem.
```java
DeviceApi deviceApi = new DeviceApi();
// Load data from a file on the class path
deviceApi.loadDataFromClassPath(<data file name on class path>);
// Load data from file path
deviceApi.loadDataFromFile(<data file path>);
```
#### Loading data from an `InputStream` ####
The following examples show how to load a data file from an `InputStream` object.
This can be used if you do not wish to load the data file from the local file system.
```java
DeviceApi deviceApi = new DeviceApi();
InputStream inputStream = <Obtain InputStream>;
deviceApi.loadDataFromStream(inputStream);
```
The exception DataLoadingException is thrown by the above methods in case the data file cannot be loaded.
## Client Side Library - Apple Device Identification ##
In addition to the server-side API, an optional client-side Javascript library
is available. This library is important for two reasons:
1. It facilitates identification of Apple devices. Apple devices are _not_
identifiable using only HTTP User-Agent data.
2. It allows for the collection of dynamic or changing properties.
When the client-side library is embedded in a web page it collects additional
properties from the client's web browser. This data is then sent back to the
server and must be passed to the DeviceAtlas API along with the HTTP headers.
The combination of the client data and the server side data allow for accurate
identification of Apple devices.
The client-side library may be included on a webpage by adding the following
snippet:
```Javascript
<!-- Adding the DeviceAtlas client side component to get client side properties -->
<script type="text/javascript" src="https://cs.deviceatlas-cdn.com/dacs.js" async></script>
```
By default, the client-side library returns the data via a cookie. If this is
present in the `HttpServletRequest` object it will be automatically used. The
cookie name is configurable via the `Config` class.
Alternatively, the client data may be returned via AJAX and passed to the server
side API manually.
For additional information, please see the [Client Side Library](https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html) documentation.
## Setup & Usage ##
The usage of the DeviceAtlas server side library is straightforward. In all
cases, the data file must be loaded before any device identification calls are
made.
> **Note:** It is highly recommended to ensure the data file is only loaded once.
This is particularly important for batch processing and web applications.
### Java Version ###
The DeviceAtlas API requires at least Java 8.
### Usage Examples ###
The following sections shows how to call the DeviceApi. Please note that
exception handling has been omitted for brevity.
#### EXAMPLE 1: Basic Usage - Single User-Agent ####
```java
DeviceApi deviceApi = new DeviceApi();
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile);
// pass an identifier to the API
String userAgent = "Mozilla/5.0 (Linux; Android 11; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.141 Mobile Safari/537.36";
Properties properties = deviceApi.getProperties(userAgent);
// print all properties
for(Map.Entry<String, Property> kv : properties.entrySet()) {
System.out.println(kv.getKey()+": "+kv.getValue()+ " ("+kv.getValue().getDataType()+")");
}
// use a property
if(properties.containsKey("mobileDevice")) {
boolean mobileDevice = properties.get("mobileDevice").asBoolean();
// do something
}
// or get the property value as a string with an internal check to verify if the property exists in the set,
// otherwise the defaultValue is returned instead.
String browserName = properties.getOrDefault("browserName", "");
```
#### EXAMPLE 2: Detection via HttpServletRequest ####
To use the API in a web application where a `HttpServletRequest` object is
available the following two step approach could be taken. Please note the
following:
> **Note 1:** This will automatically use HTTP Client Hints if they are present in
the `HttpServletRequest` object.
>
> **Note 2:** This will automatically read the client side library cookie if it
is available and use the data to detect Apple devices.
##### Step 1: Create an API instance and load the data file when the servlet starts:
```java
public class ServletContextExample implements ServletContextListener {
public void contextInitialized(ServletContextEvent contextEvent) {
// load the data file in a try/catch block as exceptions may be thrown
DeviceApiWeb deviceApi = new DeviceApiWeb();
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile);
// store the DeviceApiWeb instance on the servlet context
ServletContext context = contextEvent.getServletContext();
context.setAttribute("DeviceApiWeb", deviceApi);
}
}
```
##### Step 2: Lookup the device properties when processing requests:
```java
ServletContext context = getServletContext();
DeviceApiWeb deviceApi = (DeviceApiWeb)context.getAttribute("DeviceApiWeb");
Properties properties = deviceApi.getProperties(request); // pass HttpServletRequest object
// use the properties
```
#### EXAMPLE 3: Passing Multiple Headers Without A HttpServletRequest Object ####
In some cases, it may not be possible to use a `HttpServletRequest` object. In
this scenario, a `Map` of headers may be passed to the `DeviceApi`
`getProperties()` method. It is recommended to pass all of the HTTP headers
provided by the client. The below example shows passing a User-Agent along with
a Client Hint header. In the example, the device properties are detected from
the User-Agent and the browser properties are detected from the Client Hint
header.
```java
DeviceApi deviceApi = new DeviceApi();
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile);
// pass a collection of HTTP headers
Map<String, String> headers = new HashMap<>();
headers.put("User-Agent", "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/102.0.0.0 Mobile Safari/537.36");
headers.put("Sec-CH-UA-Full-Version-List", "\" Not A;Brand\";v=\"99.0.0.0\", \"Chromium\";v=\"102.0.5005.125\", \"Google Chrome\";v=\"102.0.5005.25\"");
Properties properties = deviceApi.getProperties(headers);
// use the properties
Properties properties = deviceApi.getProperties(ua);
if(properties.containsKey("browserVersion")) {
String browserVersion = properties.get("browserVersion").asString();
// do something
}
// or get the property value as a string with an internal check to verify if the property exists in the set,
// otherwise the defaultValue is returned instead.
String browserName = properties.getOrDefault("browserName", "");
```
#### EXAMPLE 4: Passing Client Side Data ####
The data collected by the DeviceAtlas Client-side Library is automatically
passed when a `HttpServletRequest` is used. If a `HttpServletRequest` object
is not available the client-side data can be passed manually as a second
parameter to the `getProperties()` method.
```java
DeviceApi deviceApi = new DeviceApi();
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile);
String userAgent = "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/102.0.0.0 Mobile Safari/537.36";
String clientSideData = "scsVersion:2.1|bcookieSupport:1|bcss.animations:1|bcss.columns:1|bcss.transforms:1|bcss.transitions:1|sdeviceAspectRatio:1795/1010"
Properties properties = deviceApi.getProperties(userAgent, clientSideData);
// use the properties
```
#### EXAMPLE 5: Configuration ####
During instantiation of the `DeviceApi` object an optional config parameter may
be passed. The example below shows the setting of a custom cookie name that the
DeviceAtlas client-side data should be found in.
```java
Config config = new Config();
config.setCookieName("DeviceAtlasClientSide"); // override default cookie name
config.setMaxCacheEntries(4096); // override default cache size
DeviceApi deviceApi = new DeviceApi(config);
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile);
// ... use the API as per previous examples
```
#### Additional Examples ####
Please find more complete examples in the /Examples directory.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2023. All Rights Reserved. _
_ https://deviceatlas.com _
<!-- HTML+JS for document formatting when opened in browser -->
<div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li><a href="README.Installation.html">Enterprise API Installation</a></li><li><a href="README.DataFile.html">Data File Configuration</a></li><li class="disabled"><a href="README.DeviceApi.html">Device API Usage</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="./Javadoc/index.html">Javadoc</a></li></ul></div>]]>