DeviceAtlas Device API Upgrade

# DeviceAtlas Device API Upgrade # This document is intended for users of the 2.x APIs to assist in upgrading. It has four main sections: 1. Why upgrade? 2. Upgrading from 2.x to 3.1.9 3. Data differences 4. Running comparison tests ## 1. Why upgrade? ## Version 3.1.9 of the API has higher identification speed, reduced memory and improved identification capabilities including full support for Client Hints. ## 2. Upgrading From 2.x To 3.1.9 ## The upgrade from the 2.x API to the 3.1.9 API is straightforward with minimal code changes required. The 3.1.9 API uses a new improved data file format. Data files in use with the 2.x API are not compatible. ### API Changes ### API changes between 2.x and 3.1.9 APIs are as follows: #### Change 1 - Package Naming #### The C++ namespace has changed from `mobi.mtld.*` to `com.deviceatlas.*`. #### Change 2 - Config Fields #### The following config fields have been removed: * `lang_props`. * `ua_props`. The following config field has been added: * `cache_size`. #### Change 3 - C++ interface API specific changes #### The following config field has been added: * `cache_size`. * `clname` (client side header's name, `DAPROPS` by default). The fundamental types such as Property, Value, HeaderMap are held into the `com.deviceatlas` namespace to be shared with the Carrier Identification API. The following methods DeviceAtlas::hasUAProps, DeviceAtlas::hasLangProps, DeviceAtlas::hasMatchedProps, DeviceAtlas::hasCh and DeviceAtlas::setConfig have been removed. The following accessors DeviceAtlas::getUAR, DeviceAtlas::getCPR and DeviceAtlas::getCH have been removed. The following members DeviceAtlas::treeUA, DeviceAtlas::treeAll and their accessors have been removed. It was not recommended to access those in the previous 2.x API anyway and were solely kept for backward compatibility. The DeviceAtlas::loadDataFromStream have been removed. It was deprecated previously, the API taking care of I/O to memory mapping details internally for better reliability. The DeliveryContext::getProperty\* methods have been removed. They were deprecated previously, the [] access operator is available. The DeliveryContext::refine methods have been removed. Now client-side is to be set like other headers (headers's name, by default, is `DAPROPS`). The following methods DeliveryContext::findGlobalProperty, DeliveryContext::findLocalProperty DeliveryContext::findProperty\*, DeliveryContext::setProperty, DelliveryContext::totalsize and DeliveryContext::getAtlas have been removed. The DeliveryContext::rfskp member have been removed. The libcommon.(so|a) library is no longer built. #### Change 4 - More Headers support #### More headers are supported, the code consumer needs to take in consideration if, for the input gathering part, it allocates on the stack. ## 3. Data Differences ## The 3.1.9 API contains some data differences when compared to the 2.x APIs. #### Chrome Mobile #### The `Chrome Mobile` browser name has been changed to `Chrome` to be consistent with Google's naming policy. #### macOS & iOS osVersion #### The 2.x API returns the osVersion for macOS and iOS User-Agents in the form it is found in the User-Agent. For these User-Agents, it appears like `10_5_7`. For consistency with other version numbers, the 3.1.9 API converts the osVersion to have dot-notation so the example `10_5_7` becomes `10.5.7`. #### Browser Vendor & Model #### In the 2.x API some desktop browsers set the device vendor and model to be the browser vendor and browser name if no device was identified. The 3.1.9 API no longer has this behaviour. Please use the `browserVendor` and `browserName` properties instead. #### Android Browser #### The 2.x API incorrectly returned the browser name `Android Browser` for some app WebView and Set Top box User-Agents. This has been corrected in the 3.1.9 API. The API returns `Chrome` instead The 2.x API incorrectly returned the browser name `Android Browser` for some Amazon devices running the Silk browser. This has been corrected in the 3.1.9 API. The API returns `Amazon Silk` instead #### HuaweiBrowser #### The Huawei browser naming has changed from `HuaweiBrowser` to `Huawei Browser`. #### macOS #### The osName for the macOS family of operating systems has been updated to better reflect the correct naming for each version of macOS. The names `Mac OS X`, `OS X` and `macOS` will be returned depending on what osVersion is detected. #### Linux #### The osVersionName for Linux distros is not currently well populated and will improve over time. #### isApp / appName #### The current version of the data provided with the API has limited support for isApp and appName. Subsequent releases will correct this. #### Other Properties #### The 3.1.9 API has improved support for non-standard User-Agents. Differences may be observed compared to the 2.x APIs. ## 4. Running Comparison Tests ## If a comparison between the 2.x API and the 3.1.9 API is being performed. It is recommended to compare some key properties such as: * id * vendor * model * primaryHardwareType * osName * browserName ## Known bugs ## * If a property coming from the client side contains the `:` character, its value will be then truncated. * If a property identifier contains an opening quote without the related closing quote, the property will still be created. ## Support ## Please get in touch if you have any questions about the data or the 3.1.9 API by using the support email address: <support@deviceatlas.com> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) DeviceAtlas Limited 2023. All Rights Reserved. _ _ https://deviceatlas.com _  <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.DeviceApi.html">Device API Usage C</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="disabled"><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.Cpp.html">Device API C++</a></li><li><a href="README.Nginx.html">NGINX Module</a></li><li><a href="README.Apache2.html">Apache2 Module</a></li><li><a href="README.JsonConverter.html">Device Identification API C JSONConverter</a></li><li><a href="README.Go-DeviceApi.html">Device API Usage Go</a></li><li><a href="README.Go-Upgrade.html">Device API Upgrade Go</a></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side component</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">C ApiDocs</a></li><li><a href="./ApiCppDocs/index.html">C ++ interface ApiDocs</a></li><li><a href="./Go-ApiDocs/carrier.html">Go ApiDocs Carrier</a></li><li><a href="./Go-ApiDocs/device.html">Go ApiDocs Device</a></li></ul></div>