# 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
3. Upgrading from 1.x to 2.x
## Why upgrade? ##
Version 2.1 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 ##
The 2.1 API is a drop-in replacement for the 2.0.x APIs. It should not cause any
compatibility issues except for the cases described below.
To upgrade to version 2.1 replace rename the current folder containing the api files,
and extract the new version in a new folder with the name of the api files before renaming.
## API behaviour changes ##
API changes between 2.0.x and 2.1 APIs are as follows:
### Change 1 - Config class ###
In 2.0.x it was possible to change a value in the config class after the API had
been initialised. In some rare situations this could cause unexpected behavior.
Version 2.1 adds a new method `set_config()` to DeviceApi to apply changes after the
API has been initialised. Any change made to the config without called
`set_config()` will no longer have any effect.
#### Example of 2.0.x behaviour ####
Change to config directly affects API behaviour:
```python
config = Config()
config.include_ua_props = False
device_api = DeviceApi(config)
props = device_api.get_properties(user_agent)
// properties does not contain dynamic properties
// in 2.0.x API changing a config parameter after instantiation
// _will_ affect API behaviour.
config.include_ua_props = True
props = device_api.get_properties(user_agent)
// props contain dynamic properties
```
#### Example of new 2.1 behaviour ####
Change to config does not change API behaviour unless config is passed to
the DeviceApi instance with calling the `set_config()` method.
```python
config = Config()
config.include_ua_props = False
device_api = DeviceApi(config)
props = device_api.get_properties(user_agent)
// props does not contain dynamic properties
// in 2.1 API changing a config parameter after instantiation
// will not affect API behaviour.
config.include_ua_props = True
props = device_api.get_properties(user_agent)
// properties still do not contain dynamic properties
device_api.set_config(config); // apply config
props = device_api.get_properties(user_agent);
// props now contain dynamic properties as per config
```
## Upgrading from 1.x to 2.x ##
Version 2.x 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 delivered as part of the 2.x upgrade will work with API versions
1.5, 1.6 and 1.7. Please see section "Why upgrade?".
### 2. Adopt new API, utilising the deprecated 1.x API interface ###
This option has the benefit of avoiding any interface changes, but does not
deliver the benefits of the 2.x 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.x ###
The DeviceAtlas Device Detection API version 2.x 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.x.
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 get_properties() method for getting the
properties. The getPropertiesAsTyped(), and getProperty() calls must be
replaced with the code shown below:
```python
# Previously
properties = DaApi.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 = DaApi.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 = DaApi.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 = DaApi.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"))
```
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved. _
https://deviceatlas.com