# DeviceAtlas Device Identification API # The DeviceAtlas Device Identification API provides a way to detect devices based on the HTTP headers, user-agent or Make/Model string. The API returns device information such as screen width, screen height, is mobile, vendor, model etc. To see a full list of properties in DeviceAtlas please visit: https://deviceatlas.com/resources/available-properties ## Library ## The DeviceAtlas Enterprise API can be installed either from source or built distribution packages. ** Install DeviceAtlas Python API using pip zipped package ** ```sh $ pip install API/deviceatlas-enterprise-3.1.zip ``` ** Install DeviceAtlas Python API using pip whl package ** ```sh $ pip install API/deviceatlas_enterprise-3.1-py3-none-any.whl ``` ** Install DeviceAtlas Python API using setuptools source ** extract source zip and setup.py ```sh $ unzip API/deviceatlas-enterprise-3.1.zip $ python API/deviceatlas-enterprise-3.1/setup.py install ``` ** Install DeviceAtlas Python API using source directly ** extract source zip and copy `src/com` folder to personal project source root. ```sh $ unzip API/deviceatlas-enterprise-3.1.zip $ cp -r API/deviceatlas-enterprise-3.1/src/com ./com ``` ** Third Party Dependencies ** This library does not depend on any third party libraries. ## Data File ## The DeviceAtlas API relies on a device data file to function. The download package contains a full sample data file. For a full list of the available properties please see the [properties](https://deviceatlas.com/properties) page. > **Note:** The 3.x API is only compatible with the version 3 data file which is downloadable from the DeviceAtlas website. The version 2 data file is only compatible with the production 2x APIs. ### Loading The Data File ### The DeviceAtlas API provides a function to load the data file: * `device_api.load_data_from_file("/path/to/datafile.json")` The exception DataLoadingException is thrown by the above methods in case the data file cannot be loaded. Please see the sample code later in this document for how to call these methods. ## 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-cdn.deviceatlas.com/dacs.2.2.beta.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. ### Python Version ### The DeviceAtlas API requires at least the Python 3.6.x (or above) ### Usage Examples ### The following sections shows how to call the DeviceApi. Please note that exception handling has been omitted for brevity. #### EXAMPLE 1: Detection via HTTP headers ### To look up the properties by manually passing a dictionary of HTTP headers to the API. 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. ```python from com.deviceatlas.device.device_api import DeviceApi from com.deviceatlas.exception.data_loading_exception import DataLoadingException headers = { "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", "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\"" } device_api = DeviceApi() try: device_api.load_data_from_file("/path/to/datafile.json") properties = device_api.get_properties(headers) except DataLoadingException: # Handle the exceptions related to loading the data file ``` #### EXAMPLE 2: Detection via User-Agent ### To lookup the properties by manually passing a user-agent string to the API: ```python from com.deviceatlas.device.device_api import DeviceApi from com.deviceatlas.exception.data_loading_exception import DataLoadingException 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" device_api = DeviceApi() try: device_api.load_data_from_file("/path/to/datafile.json") properties = device_api.get_properties(user_agent) except DataLoadingException: # Handle the exceptions related to loading the data file ``` #### EXAMPLE 3: Detection via Make/Model ### To lookup the properties by manually 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). ```python from com.deviceatlas.device.device_api import DeviceApi from com.deviceatlas.exception.data_loading_exception import DataLoadingException make_model = "samsung sm-n9005" device_api = DeviceApi() try: device_api.load_data_from_file("/path/to/datafile.json") properties = device_api.get_properties(make_model) except DataLoadingException: # Handle the exceptions related to loading the data file ``` #### EXAMPLE 4: Using the properties #### ```python # If there is a property named "mobileDevice" and the value is True if properties.contains("mobileDevice", True): # Example 1: Get the screen width for image optimization display_width = 0 if "displayWidth" in properties: display_width = int(properties.get("displayWidth")) # Example 2: Get the screen width for image optimization vendor = "" if "vendor" in properties: vendor = str(properties.get("vendor")) # Example 3: Get the screen width for image optimization use_bigger_icons = properties.contains("touchScreen", True) # Example 4: Send Geo Location JS to client? support_geo_location = properties.contains("js.geoLocation", True) # Example 5: 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. browser_name = properties.get_or_default_str("browserName", "") ``` #### 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. ```python from com.deviceatlas.device.device_api import DeviceApi from com.deviceatlas.device.config import Config config = Config() config.set_cookie_name("DeviceAtlasClientSide") # override default cache size config.set_max_cache_entries(4096) device_api = DeviceApi(config) ``` #### Additional Examples #### Please find more complete examples in the /Examples directory. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) DeviceAtlas Limited 2022. 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 Identification API</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="./ApiDocs/index.html">DeviceAtlas API Docs</a></li></ul></div>