# DeviceAtlas Device API Usage # This document describes the DeviceAtlas API and how it is used. The DeviceAtlas Device Identification API consists of two libraries. A core library containing all of the main identification logic and a secondary extension library to allow for easier integration into a web application context. ## Data File ## The DeviceAtlas API relies on a device data file to function. DeviceAtlas provides daily data file updates. It is recommended to download the data file on a regular basis. This can be done from your account page or automated via the https://deviceatlas.com/getJSON page. Please see 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. #### Loading an existing data file #### The following examples show how to load a data file that is already on the filesystem. ```go import ( "deviceatlas/device" ) da := device.New() defer da.Free() // Load data from a file on the class path _, err := da.LoadDataFromFile(<data file name>) ``` ## 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. ### Usage Examples ### The following sections shows how to call the DeviceApi. Please note that exception handling has been omitted for brevity. #### Detection via User-Agent #### Lookup the properties by passing a User-Agent string to the API: ```go da := device.New() defer da.Free() _, err := da.LoadDataFromFile(<data file name>) // pass an identifier to the API 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, err := da.DetectV(userAgent) // print all properties for k, v := range properties { fmt.Printf("%v: %v\n", k, v) } // use a property if mobileDevice, ok := properties["mobileDevice"]; ok { // 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", ""); ``` #### Detection via Make/Model #### Lookup the properties by passing a Make/Model string to the API. DeviceAtlas expects the make/model string in a specific format, this format and how to obtain the Make/Model string can be found under the "Expected string format for DeviceAtlas lookup" section [here](https://deviceatlas.com/resources/getting-started-enterprise-for-apps). ```go da := device.New() defer da.Free() _, err := da.LoadDataFromFile(<data file name>) // The Make/Model identifier may be looked up by directly passing the string makeModel := "samsung sm-n9005"; properties, err := da.DetectV(makeModel) // It is also possible to add the Make/Model identifier to a map for the lookup identifiers := make(map[string]string) identifiers["make-model"] = makeModel properties, err := da.Detect(identifiers) ``` #### 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. ```go da := device.New() defer da.Free() _, err := da.LoadDataFromFile(<data file name>) userAgent := "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/ Mobile Safari/537.36"; clientSideData := "scsVersion:2.2|bcookieSupport:1|bcss.animations:1|bcss.columns:1|bcss.transforms:1|bcss.transitions:1|sdeviceAspectRatio:1795/1010" Properties properties = da.DetectV(userAgent, clientSideData); // use the properties ``` #### Additional Examples #### Please find more complete examples in the /Examples directory. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) DeviceAtlas 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 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 class="divider"></li><li><a href="./ApiDocs/device.html">Device API Docs</a></li></ul></div>