# DeviceAtlas Device Detection API Upgrade # This document is intended for users of APIs prior to version 2.1. It has three main sections: 1. Why Upgrade? 2. Upgrading From 2.0.x to 2.1 and later 3. Upgrading From 1.x to 2.0.x ## Why Upgrade? ## Version 2.1 and later of the API has higher detection speed, reduced memory and improved detection capabilities. It is a recommended upgrade for all users. The API is compatible with all existing DeviceAtlas data files. Version 2.1 adds support for additional improvements to the data file format. To enable these improvements please follow the below steps: 1. Login into your account at deviceatlas.com 2. Go to "Data File Options" under "MY ACCOUNT" page 3. Un-tick the "API 2.0 compatible JSON file" option 4. Save Options 5. Download the new data file 6. Use new data file with the API Note: It is recommended to only use the updated data file with APIs of version 2.1 and above. ## Upgrading From 2.0.x To 2.1 ## ### API Behavior Changes ### API changes between 2.0.x to 2.1 APIs are as follows: - There is only one gem file which includes both the Device and Carrier Identification APIs with a simplified name. _Before 2.1_ ```ruby require "mobi_mtld_da_device_api" device_api = Mobi::Mtld::Da::Device::DeviceApi.new ``` _2.1 and later_ ```ruby require "deviceatlas" device_api = DeviceAtlas::Device::DeviceApi.new ``` - A return object from calling `get_properties()` is a simple Hash with symbols used as a key having typed values. _Before 2.1_ ```ruby properties = device_api.get_properties(user_agent) string_property = properties.get("model").to_s boolean_property = properties.get("mobileDevice").to_b ``` _2.1 and later_ ```ruby properties = device_api.get_properties(user_agent) string_property = properties[:model] boolean_property = properties[:mobileDevice] ``` - There is no `properties.contains` method anymore. _Before 2.1_ ```ruby if properties.contains?("mobileDevice", true) ... end ``` _2.1 and later_ ```ruby if properties.key?(:mobileDevice) && properties[:mobileDevice] ... end ``` ## Upgrading From 1.x to 2.0.x ## Version 2.0 of the API introduces a new better interface and improved performance. The following sections detail upgrading from v1.x versions. Version 1.x of the API has been deprecated. There are three options: **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. **The 1.x interface is no longer supported in version 2.1 and later.** 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 "DeviceAtlas". Existing source code will work without the need to be changed simply by replacing the old reference to the "deviceatlas.rb" file by the new "mobi_mtld_da_device_api" gem file: ```ruby # Before 2.0 require "/path/to/deviceatlas.rb" # In 2.0+ from a stand-alone script require "mobi_mtld_da_device_api" # In 2.0+ from a Rails controller # method 1: automatically getting request headers (or passing them optionally) require "mobi_mtld_da_device_api_web" # method 2: explicitly passing headers as parameter require "mobi_mtld_da_device_api" ``` However, new users should avoid using the 1.x interface and current users are encouraged to upgrade to the new interface. Note that if you are not willing to upgrade your source code, and you have not been advised by the DeviceAtlas support team, you don't have to replace your current DeviceAtlas Device Detection API libraries with the new libraries. ### 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 .rb files with installation of the three gem files shipped in this package for this API: * mobi_mtld_da.gem * mobi_mtld_da_device_api.gem * mobi_mtld_da_device_api_web.gem These gems contain both the new Mobi::Mtld::Da::Device::DeviceApi and the 1.x DeviceAtlas classes. 2. References to the API change. The previous import must be replaced with the one shown below. ```ruby # in a Rails controller require "mobi_mtld_da_device_api_web" # and include the controller helper inside your controller class include Mobi::Mtld::Da::Device::ControllerHelper ``` ```ruby # in a stand-alone script require "mobi_mtld_da_device_api" ``` 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. ```ruby # in a Rails controller device_api = get_deviceatlas_device_api_web_instance() ``` ```ruby # in a stand-alone script device_api = Mobi::Mtld::Da::Device::DeviceApi.new ``` You can also change the default API config: ```ruby # in a Rails controller config = Mobi::Mtld::Da::Device::Config.new device_api = get_deviceatlas_device_api_web_instance config # Configure the API with the "config" object. # Check out the documentation for further details. ``` ```ruby # in a stand-alone script config = Mobi::Mtld::Da::Device::Config.new device_api = Mobi::Mtld::Da::Device::DeviceApi.new 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. ```ruby # 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: ```ruby # Previously properties = DeviceAtlas.getProperties(tree, userAgent) if properties.has_key?("model") value = properties.get("model") end # Now properties = device_api.get_properties(user_agent) if properties.has_key?(:model) # or with the "model" String value = properties.get(:model).to_s end ``` ```ruby # Previously properties = DeviceApi.getPropertiesAsTyped(tree, userAgent) if properties.has_key?("mobileDevice") value = properties.get("mobileDevice").to_b end # Now properties = device_api.get_properties(user_agent) if properties.has_key?(:mobileDevice) value = properties.get(:mobileDevice).to_b end ``` ```ruby # Previously begin isMobile = DeviceApi.getPropertyAsBoolean(tree, userAgent, "mobileDevice") if isMobile end rescue... # Now - method 1 properties = device_api.get_properties(user_agent) if properties.contains?(:mobileDevice, true) end # Now - method 2 properties = device_api.get_properties(user_agent) if properties.has_key?(:mobileDevice) is_mobile = properties.get(:mobileDevice).to_b if is_mobile end end ``` ```ruby # Previously properties = DeviceApi.getProperties(tree, userAgent, clientSideProperties) if properties.has_key("model") value = properties.get("model").to_s end # Now properties = device_api.get_properties(user_agent, client_side_properties) if properties.has_key?(:model) value = properties.get(:model).to_s end # Now - when using DeviceApiWeb all headers are internally handled properties = device_api.get_properties() if properties.has_key?(:model) value = properties.get(:model).to_s end ``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) DeviceAtlas Limited 2021. 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-Web.html">Device Detection for Web</a></li><li><a href="README.DeviceApi-Apps.html">Device Detection for Apps</a></li><li><a href="README.DeviceApi-Config.html">Device Detection API Config</a></li><li class="disabled"><a href="README.Upgrade.html">Device Detection API Upgrade</a></li><li><a href="./ApiDocs/DeviceAtlas/Device/DeviceApi.html">Device API Docs</a></li><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="./ApiDocs/DeviceAtlas/Carrier/CarrierApi.html">Carrier API Docs</a></li><li class="divider"></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side Component</a></li><li><a href="README.ConnectivityAnalyser.html">Connectivity Analyser</a></li></ul></div>