# DeviceAtlas Device Detection API Upgrade # This document is for users who are already using a DeviceAtlas DeviceAPI version prior to 2.0. There are three scenarios that may be considered. **1) Do nothing.** The new data file (JSON) delivered as part of the 2.0 upgrade will work with API versions 1.5, 1.6 and 1.7. However, it is recommended to implement the new 2.0 interface. **2) Adopt new API, utilising the 1.x API interface** This option has the benefit of avoiding any interface changes, but does not deliver the benefits of the 2.0 API. **3) Adopt new API, utilising new interface** This is the recommended approach, and it delivers improved accuracy of detection for third party browsers. It is an improved architecture and will form the basis of future API evolutions. ### 1.x API Interface ### The interface used in the DeviceAtlas Device Detection API versions prior to 2.0 is marked as deprecated. It is highly recommended to upgrade your source code to work with the new interface instead. As it may be inconvenient for some current users to upgrade their source code to use the new interface, the old interface is supported by DeviceAtlas but limited to bug fixes. The new libraries include the old interface (marked as deprecated) as "Api". Existing source code will work without the need to be changed simply by replacing the old reference to the dir where you place the "api.py" file. It will internally use the new "mobi" module. However, new users should avoid using the 1.x interface and current users are encouraged to upgrade to the new interface. ### Upgrading to 2.0 ### The DeviceAtlas Device Detection API version 2.0 and higher is shipped with a different interface than previous versions. This section shows the steps to upgrade a system which is currently using a DeviceAtlas Device Detection API prior to version 2.0. 1. Replace the previous DeviceAtlas Device Detection API "api.py" file with the new "mobi" module. This module contains the new api. 2. References to the API change. The previous import must be replaced with the one shown below. ```python from mobi.mtld.da.device_api import DeviceApi ``` 3. Creating an instance. Unlike the 1.x interface, which was a set of static methods, accessing the methods of the new interface requires an instance. ```python device_api = DeviceApi() ``` You can also change the default API config: ```python from mobi.mtld.da.device.config import Config config = Config() device_api = DeviceApi(config) # Configure the API with the "config" object. # Check out the documentation for further details. ``` 4. Loading the data. In the 1.x interface it was necessary to load the data and get the tree (as a Hash) from the loadTreeFromFile() or loadTreeFromString() and manually pass it to all the other related methods, however this is not the case in the new interface. The data may be loaded into the API instance from a file or string and no tree will be returned and the tree does not have to be passed to other methods. This interface keeps the tree encapsulated. ```python # method 1 device_api.load_data_from_file("/path/to/datafile.json") # method 2 device_api.load_data_from_string("data_string_in_json_format") ``` 5. Getting properties. There is only one properties() method for getting the properties. The getPropertiesAsTyped(), and getProperty() calls must be replaced with the code shown below: ```python # Previously properties = Api.getProperties(tree, userAgent) if "model" in properties: value = properties.get("model") # Now properties = device_api.get_properties(user_agent) if "model" in properties: value = str(properties.get("model")) ``` ```python # Previously properties = Api.getPropertiesAsTyped(tree, userAgent) if "mobileDevice" in properties: value = properties.get("mobileDevice").asBoolean() # Now properties = device_api.get_properties(user_agent) if "mobileDevice" in properties: value = bool(properties.get("mobileDevice")) ``` ```python # Previously try: isMobile = Api.getPropertyAsBoolean(tree, userAgent, "mobileDevice") if isMobile except... # Now - method 1 properties = device_api.get_properties(user_agent) if properties.contains("mobileDevice", true): # Now - method 2 properties = device_api.get_properties(user_agent) if "mobileDevice" in properties: is_mobile = bool(properties.get("mobileDevice")) if is_mobile ``` ```python # Previously properties = Api.getProperties(tree, userAgent, clientSideProperties) if "model" in properties: value = properties.get("model").asString() # Now properties = device_api.get_properties(user_agent, client_side_properties) if "model" in properties: value = str(properties.get("model")) ``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ (c) 2021 DeviceAtlas Limited. 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.DeviceApi.html">Device Detection API</a></li><li class="disabled"><a href="README.Upgrade.html">Device Detection API Upgrade</a></li><li><a href="DeviceApiDocs/mobi.mtld.da.device.device_api.DeviceApi-class.html">Device API docs</a></li><li class="divider"></li><li><a href="README.ClientSide.html">Client Side Component</a></li><li><a href="README.ConnectivityAnalyser.html">Connectivity Analyser</a></li><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="CarrierApiDocs/mobi.mtld.da.carrier.carrier_api.CarrierApi-class.html">Carrier API docs</a></li></ul></div>