Documentation

Client

in package

• DeviceAtlas
• Cloud

DeviceAtlas Cloud API. This client library can be used to easily get device data from the DeviceAtlas Cloud service. To reduce cloud calls and improve performance the API locally caches the data returned from the cloud service.

try {
    $data = Client::getDeviceData();
} catch (Exception $x) {
    // handle exceptions ...
}

// legacy: (class constant DEBUG = false)
// the errors have to be checked manually from the returned array
$data = Client::getDeviceData();

$data[Client::KEY_ERROR]
    will exist if errors happened while fetching data
$data[Client::KEY_PROPERTIES]
    an array of device properties
$data[Client::KEY_USERAGENT]
    the user-agent string that was used to get the properties
$data[Client::KEY_SOURCE]
    shows where the data came from and is one of:
    Client::SOURCE_FILE_CACHE
    Client::SOURCE_CLOUD
    Client::SOURCE_NONE

// get properties for a user-agent
try {
    $data = Client::getDeviceData("user-agent-string ...");
} catch (Exception $x) {
    // handle exceptions ...
}

// get properties for a set of headers
$headers = array(
    "User-Agent"      => "Mozilla/5.0 (SymbianOS/9.2; ...",
    "X-Profile"       => "http://nds.nokia.com/uaprof/NN95_8GB-1r100.xml",
    "Accept"          => "text/html,text/css,multipart/mixed,application...",
    "Accept-Language" => "en-us,en;q=0.5",
);
try {
    $data = Client::getDeviceData($headers);
} catch (Exception $x) {
    // handle exceptions ...
}

Tags

author

DeviceAtlas Limited

copyright

Copyright (c) DeviceAtlas Ltd 2023. All Rights Reserved.

Table of Contents

Constants

API_VERSION  = '2.1'

DeviceAtlas Cloud API version

CLIENT_COOKIE_HEADER  = 'Client-Properties'

For API internal usage

CLOUD_PATH  = '/v1/detect/properties?licencekey=%s&useragent=%s'

For API internal usage

DA_HEADER_PREFIX  = 'X-DA-'

For API internal usage

FAILOVER_CONTINUE  = 2

Action to be taken after an end-point responds: If the error controller returns this the fail-over mechanism must try the next end-point

FAILOVER_NOT_REQUIRED  = 0

Action to be taken after an end-point responds: If an-endpoint response was fine

FAILOVER_STOP  = 1

Action to be taken after an end-point responds: If the error controller returns this the fail-over mechanism must stop trying the next end-point

KEY_ERROR  = 'error'

A key of array returned by getDeviceData() - the error message is set to this key

KEY_PROPERTIES  = 'properties'

A key of array returned by getDeviceData() - the device properties are set to this key

KEY_SOURCE  = 'source'

A key of array returned by getDeviceData() - the source of data is set to this key

KEY_USERAGENT  = 'useragent'

A key of array returned by getDeviceData() - the user-agent is set to this key

MIN_PHP_VERSION  = '5.2.1'

Min DeviceAtlas Cloud API required PHP version

SOURCE_CLOUD  = 'cloud'

Device data source value set to KEY_SOURCE - device data source was cloud service

SOURCE_COOKIE  = 'cookie'

Device data source value set to KEY_SOURCE - device data source was cookie

SOURCE_FILE_CACHE  = 'file'

Device data source value set to KEY_SOURCE - device data source was file cache

SOURCE_NONE  = 'none'

Device data source value set to KEY_SOURCE - no device data, indicates an error

TEST_USERAGENT  = 'Mozilla/5.0 (Linux; U; Android 2.3.3; en-gb; GT-I9100 Build/GINGERBREAD) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1'

Properties

$autoServerRanking  : bool

true: server preference is decided by the API (faster server is preferred) false: server preference is $SERVERS sort order (top server is preferred)

$autoServerRankingLifetimeMinutes  : int

Server preferred list will be updated when older than this amount of minutes

$autoServerRankingMaxFailures  : int

When ranking servers, if a server fails more than this number phase it out

$autoServerRankingNumRequests  : int

Number of requests to send when testing server latency

$cacheCookieName  : string

Cookie name for items cached in cookies

$cacheDir  : string

The file path that cache items will be stored at. If null the system temp dir is used

$cacheExpirySeconds  : int

Cache expire (for both file and cookie) 2592000 = 30 days in seconds

$cacheName  : string

File cache > directory name

$calledServers  : mixed

$clientCookieName  : string

Name of the cookie created by "DeviceAtlas Client Side Component

$fatalErrors  : mixed

$headers  : mixed

$lastUsedCloudUrl  : mixed

$licenceKey  : string

$rankingStatus  : mixed

$selfAutoRanking  : mixed

$serverPhaseoutLifetimeMinutes  : int

Auto ranking = false > if top server fails it will be phased out for this amount of minutes

$servers  : array<string|int, mixed>

List of cloud service provider end-points.

$timeoutSeconds  : int

Max time (seconds) to wait for each cloud server to give service

$useClientCookie  : bool

Use device data which is created by the DeviceAtlas Client Side Component if present

$useCookieCache  : bool

Cache cloud results in cookies

$useFileCache  : bool

Cache cloud results in files

Methods

getAutoServerRankingLifetimeMinutes()  : int

getAutoServerRankingMaxFailures()  : int

getAutoServerRankingNumRequests()  : int

getCacheBasePath()  : string

Get the directory path in which the DeviceAtlas CloudApi puts cache files in (device data cache and server fail-over list).

getCacheCookieName()  : string

getCacheDir()  : string

getCacheExpirySeconds()  : int

getCacheName()  : string

getCalledServers()  : array<string|int, mixed>

getClientCookieName()  : string

getCloudUrl()  : string

Get the URL of the last DeviceAtlas cloud end-point which was called to get device properties.

getDaClientUserAgent()  : mixed

getDeviceData()  : array<string|int, mixed>

getFatalErrors()  : mixed

getHeaders()  : mixed

getLastUsedCloudUrl()  : mixed

getLicenceKey()  : string

getRankedServers()  : array<string|int, mixed>

Get DeviceAtlas cloud end-point list in the same order used by the API.

getRankingStatus()  : mixed

getSelfAutoRanking()  : mixed

getServerPhaseoutLifetimeMinutes()  : int

getServers()  : array<string|int, mixed>

getServersLatencies()  : array<string|int, mixed>

Get a list of cloud end-points and their service latencies.

getTimeoutSeconds()  : int

isAutoServerRanking()  : bool

isUseClientCookie()  : bool

isUseCookieCache()  : bool

isUseFileCache()  : bool

rankServers()  : array<string|int, mixed>

If auto-ranking is on then rank the DeviceAtlas cloud end-points and put in cache.

setAutoServerRanking()  : mixed

setAutoServerRankingLifetimeMinutes()  : mixed

setAutoServerRankingMaxFailures()  : mixed

setAutoServerRankingNumRequests()  : mixed

setCacheCookieName()  : mixed

setCacheDir()  : mixed

setCacheExpirySeconds()  : mixed

setCacheName()  : mixed

setClientCookieName()  : mixed

setLicenceKey()  : mixed

setServerPhaseoutLifetimeMinutes()  : mixed

setServers()  : mixed

setTimeoutSeconds()  : mixed

setUseClientCookie()  : mixed

setUseCookieCache()  : mixed

setUseFileCache()  : mixed

__rankServers()  : mixed

servers=null rank and cache end-points servers=array cache servers (for updating the manual fail-over list)

getNormalisedHeaders()  : mixed

normalize the HTTP header keys

prepareHeaders()  : string

Prepare cloud request headers which can help the detection

connectCloud()  : array<string|int, mixed>

connect to a cloud server and get device data, return data or null

errorControler()  : array<string|int, mixed>

when an end-point returns an array (action, error-message) this method will check it

getCloudService()  : mixed

get data from the DeviceAtlas Cloud service

getCookieCache()  : mixed

COOKIE CACHE > if device data is cached in a cookie then fetch data cookie cache remains in the API only to be compatible with older versions

getDaHeaders()  : mixed

getDeviceCachePath()  : mixed

FILE CACHE > get the device data cache file-path

getFileCache()  : mixed

FILE CACHE > if device data is cached in a file then fetch data

getServerLatency()  : mixed

send request(s) to a DA cloud server and return the latencies

rankSort()  : mixed

sort by latency

setCookieCache()  : mixed

COOKIE CACHE > cache device data into two cookies on the client cookie cache remains in the API only to be compatible with older versions

setFileCache()  : mixed

FILE CACHE > cache device data into a file

writeCacheToFile()  : mixed

lock cache file and write to it

{
     Client::KEY_USERAGENT: "UA" | null,
     Client::KEY_SOURCE: "data source",
     Client::KEY_PROPERTIES: {"propertyName": "PropertyVal",} | null,
     Client::KEY_ERROR: err-msg-string | null,
}