# 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
"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
```
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ (c) 2021 DeviceAtlas Limited. All rights reserved. https://deviceatlas.com _