<![CDATA[
# 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.2
3. Data differences
4. Running comparison tests
## 1. Why upgrade? ##
Version 3.1.2 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.2 ##
The upgrade from the 2.x API to the 3.1.2 API is straightforward with minimal
code changes required.
The 3.1.2 API uses a new improved data file format.
> Data files in use with the 2.x API are not compatible.
### PHP Version ###
The DeviceAtlas API requires at least the PHP 7.0 (or above).
### API Changes ###
API changes between 2.x and 3.1.2 APIs are as follows:
#### Namespace ####
The classes dropped `Mobi_Mtld_DA_` and `Mobi_Mtld_DA_*_` prefixes in
favor of a proper namespace `DeviceAtlas` and `DeviceAtlas/*` definitions accordingly.
_Now_
```
use DeviceAtlas\Device\DeviceApi;
$deviceApi = new DeviceApi();
```
_Previously_
```
$deviceApi = new Mobi_Mtld_DA_Device_DeviceApi();
```
#### Config options ####
The following config options have been removed:
* `setIncludeMatchInfo(...)` / `getIncludeMatchInfo()`
* `setIncludeUaProps(...)` / `getIncludeUaProps()`
* `setReturnNullWhenNoProperties(...)` / `getReturnNullWhenNoProperties()`
* `setIncludeLangProps(...)` / `getIncludeLangProps()`
* The language and languageLocale properties are no longer configurable via the
Device API config, instead they are configured via "Data File Options" page
on the DeviceAtlas account.
#### Exception handling ####
- `DataFileException` and `DataReadException` - unified as `DataLoadingException`.
- `InvalidPropertyException` - not used anymore. Originally used by already deprecated `Api::getProperty()` method.
- `UnknownPropertyException` - not used anymore. Originally used by already deprecated `Api::getProperty()` method.
- `FileWriteException` - not used anymore. Originally part of the `TreeOptimized` class.
#### DeviceApi interface ####
- The `getDataCreationTimestamp()` method returns int (epoch time) instead of string.
- Added new `getDataCreationIso8601()` method to return string date in ISO 8601 format.
- The `DeviceApi->getProperties(...)` method is now able to accept array of headers directly.
## 3. Data Differences ##
The 3.1.2 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.2 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.2 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.2
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.2
API. The API returns `Amazon Silk` instead
#### Huawei Browser ####
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.2 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.2 API is being performed. It
is recommended to compare some key properties such as:
* id
* vendor
* model
* primaryHardwareType
* osName
* browserName
## Support ##
Please get in touch if you have any questions about the data or the 3.1.2 API by
using the support email address: <support@deviceatlas.com>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2023. 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.DataFile.html">Data File Configuration</a></li><li><a href="README.DeviceApi.html">Device API Usage</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li class="disabled"><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">DeviceAtlas API Docs</a></li></ul></div>]]>