Mobi_Mtld_DA_Device_DeviceApiWeb

A small extension to the core DeviceApi that uses the request HTTP headers for detection and property lookup.

When detecting user's device as real-time on a website it is strongly recommend to use the DeviceApiWeb library and getProperties as shown bellow.

The getProperties of DeviceApiWeb, automatically detects the availability of the client-side properties and will use them for detection. If you want to have a more accurate detection (specially for apple devices) or have the client side properties included in the property sets, simply include the DeviceAtlas client-side component JavaScript library in the pages.

The API may be configured configured to improve performance and memory footprint, when used in a web application for real-time device detection:

1. Optimizing the data file.
2. Caching the results.

The getProperties() method in this class extracts the most suitable headers from the request headers.

Example usage:

 require_once "/PATH/TO/Mobi/Mtld/DeviceApiWeb.php";
 // default=the data optimization is on
 $deviceApi = new Mobi_Mtld_DA_Device_DeviceApiWeb();
 try {
     $deviceApi->loadDataFromFile("/path/to/datafile.json");

     // get all properties from the current request
     $properties = $deviceApi->getProperties();

     // .... use the properties ....
     if ($properties->contains("mobileDevice", true)) {
         if ($properties->containsKey("model")) {
             $deviceModel = $properties->model;
         }
     }
 } catch (...

Source: DeviceApiWeb.php
Depends on: Mobi_Mtld_DA_Device_Config
The
Extends: Mobi_Mtld_DA_Device_DeviceApi

Package: Mobi\Mtld\DA\Device
Version: 2.0.0
Author: DeviceAtlas Limited
Copyright: Copyright (c) 2021 by DeviceAtlas Limited. All rights reserved.

Constants

API_VERSION = '2.1'

Api version.

MIN_PHP_VERSION = '5.2.3'

Minimum PHP version required for this API to run. *

Static Methods

getApiVersion

string Mobi_Mtld_DA_Device_DeviceApiWeb::getApiVersion()

Get DeviceApi version.

Returns

string: DeviceApi version

Methods

__construct

Mobi_Mtld_DA_Device_DeviceApiWeb $obj = new Mobi_Mtld_DA_Device_DeviceApiWeb(
    Mobi_Mtld_DA_Device_Config config
)

Constructs a DeviceApiWeb instance with custom configs.

See also: Mobi_Mtld_DA_Device_Config

Arguments

config (Mobi_Mtld_DA_Device_Config): An instance of Config, you can change the DeviceAtlas API configs by creating an instance or Config and setting your preferences config values then passing the instance to the DeviceApi constructor. null=use default configs.

Returns

void

getDataCreationTimestamp

string $obj->getDataCreationTimestamp()

Get the device data creation (JSON file) timestamp.

Returns

string: The string data creation timestamp

getDataRevision

int $obj->getDataRevision()

Get the device data generation revision.

Returns

int: Data generation revision

getDataVersion

string $obj->getDataVersion()

Get the device data (JSON file) version.

Returns

string: The data version

getLookupSource

string $obj->getLookupSource()

Get the source properties fetch source to be used for debugging.

Returns

string: The value of one this constants: LOOKUP_SOURCE_TREE or LOOKUP_SOURCE_OPTIMIZED_TREE or LOOKUP_SOURCE_CACHE

getProperties

The $obj->getProperties()

Get the Device properties for the current request. The most suitable request headers are extracted and used for detection and property lookup.
If the client-side-component has been used and the client-side properties exists in the client-side cookie, then the properties will be included.
You can change the API's configs using class "Mobi_Mtld_DA_Device_Config". Depending on the configs the properties may include user-agent dynamic properties and language/locale properties.

Returns

The: found properties

Throws

Mobi_Mtld_DA_Esception_ClientPropertiesException

getProperties

Mobi_Mtld_DA_Properties $obj->getProperties(
    array headers,
    string clientSideProperties=null
)

Get the properties for a set of HTTP headers merged with properties from the client side component. The DeviceApi gets all the request HTTP headers and will precisely detect the device and find property values by all usable headers. Get the properties for a User-Agent merged with the client-side properties (when provided by the DeviceAtlas client side component). The DeviceAtlas client-side component (JavaScript library) collects the client-side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will over-ride any properties discovered from the main JSON data file.

Arguments

headers (array): Client's request HTTP headers

clientSideProperties=null (string): The contents of the cookie containing the client side properties

Returns

Mobi_Mtld_DA_Properties: A set of properties (Property objects) wrapped in a Properties object

Throws

Mobi_Mtld_DA_Exception_ClientPropertiesException

getPropertiesFromUa

Mobi_Mtld_DA_Properties $obj->getPropertiesFromUa(
    string userAgent,
    string clientSideProperties=null
)

Get the properties for a User-Agent merged with the client-side properties (when provided by the DeviceAtlas client side component). The DeviceAtlas client-side component (JavaScript library) collects the client-side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will over-ride any properties discovered from the main JSON data file.

Arguments

userAgent (string): The User-Agent string

clientSideProperties=null (string): The contents of the cookie containing the client side properties

Returns

Mobi_Mtld_DA_Properties: A set of properties (Property objects) wrapped in a Properties object

Throws

Mobi_Mtld_DA_Exception_ClientPropertiesException

getPropertyNames

array $obj->getPropertyNames()

Get a set of available device property names.

Returns

array: A set of available device property names as PropertyName objects. A PropertyName object holds a property-name and it's data-type

loadDataFromFile

void $obj->loadDataFromFile(string jsonDataFilePath)

Load the DeviceAtlas device detection data into the API from a JSON file. The JSON data file is provided by the DeviceAtlas web-site.

Arguments

jsonDataFilePath (string): Path to the JSON file

Returns

void

Throws

loadDataFromString

void $obj->loadDataFromString(string data)

Load the DeviceAtlas device detection data into the API from a string. The JSON data file is provided by the DeviceAtlas web-site.

Arguments

data (string): DeviceAtlas device data

Returns

void

Throws

setConfig

void $obj->setConfig(Mobi_Mtld_DA_Device_Config $config)

Set new config settings via a new Config object and drop current cache.

Arguments

$config (Mobi_Mtld_DA_Device_Config)

Returns

void