Introduction
There are two ways to access the device detection API, a
self-hosted on-premise version and a cloud version accessed through calls to
the 51Degrees servers.
The new 51Degrees PHP common API aims to make switch from Cloud based Device-Detection to the On-Premise version much easier for developers. It allows you to switch without the need to re-write your code by providing a common API between the two solutions connected by an interface which communicates with the core software.
Php Sessions
The common API uses PHP sessions to store information (in
variables) to be used across multiple pages.
Download
You can download the PHP Common API from the Device Detection Github repository here .
Installation
Getting started is as simple as copying the contents of the common-api/51Degrees directory into your webservers document root.
# For apache based webservers
$ cp -R Device-Detection/php/common-api/51Degrees /var/www/html/
Configuration
Edit the
config.php
file within the
common-api/51Degrees
directory to configure the Common API. Include this file using
require()
in a PHP script before initialising the provider:
require("../config.php");
$provider = FiftyOneDegrees\FiftyOneDegreesGetProvider($settings);
Both cloud and on Premise
Passed in during provider initialisation.
Property | Type | Required | Default | Description |
---|---|---|---|---|
FiftyOneProvider | String | Mandatory | None | Set to Cloud/TRIE/Pattern |
FiftyoneShareUsage | Boolean | Optional | True | Whether the API should send usage data. |
FiftyOneLicence | String | See description | None | Not required for On-Premise as manual datafile updates can be used rather than automatic updates. Required for Cloud. |
FiftyOneLogLevel | String | Optional | Fatal | Either Debug, Info, Warn or Fatal – minimum log level to log to file. |
FiftyOneLogFile | String | Optional | ./51Degrees.log | Path to log file. |
Cloud only
Passed in during provider initialisation, these can be left blank when using On-Premise Device-Detection.
Property | Type | Required | Default | Description |
---|---|---|---|---|
FiftyOneUseSession | Boolean | Optional | True | Whether the cloud API should store detection results in the session. |
FiftyOneSessionLifetime | Integer | Optional | None | length of time to keep matches in session for. |
FiftyOneProperties | String Array | Optional | All Properties | An array of which properties to fetch (if left blank all are fetched). For the On-Premise version this is set in the extension properties. For more information about available properties see the Property Dictionary. |
Example configuration
The following shows an example of the contents of config.php.
$settings = array(
"FiftyOneProvider"=>"Cloud",
"FiftyoneShareUsage"=>true,
"FiftyOneLicence"=>"***YOUR_LICENCE_KEY***",
"FiftyOneLogLevel"=>"fatal",
"FiftyOneLogFile"=>"51degrees.log",
"FiftyOneUseSession"=>true,
"FiftyOneSessionLifetime"=>"60",
"FiftyOneProperties"=>array("IsMobile","HardwareVendor","PlatformName")
);
Usage
To use the 51Degrees PHP Common API, create a new session then require the common API and configuration files. Fetch the provider, this will have been initialised on server startup if you have migrated to an On-Premise extension. This object can be called to process a new match object which can return properties of the specific mathced device.
<?php
session_start();
require("../51degrees.php");
require("../config.php");
$provider = FiftyOneDegrees\FiftyOneDegreesGetProvider($settings);
$match = $provider->getMatch($_SERVER['HTTP_USER_AGENT']);
echo $match->getValue('IsMobile');
?>
Logging
The PHP common API supports logging.
This is handled by the ‘ logger.php ’ script
Events are logged in ‘ ./51degrees.log ’ which is the default setting.
Make sure that the webserver user group has write access to the current working drectory or create the file ' 51degrees.log '. On Linux systems, set the file permissions so that the server user/group has write access.
Best practise dictates that the location for the log file should be set to ' /var/log/51degrees/ ' this can be setting when passing parameters to the provider.