Detector v4
API Documentation

2021-05-04, 08:23
Martin Kæstel Nielsen
- think.dk

As of Detector v3 it is also possible to build a static version of Detector for production implementations to reduce dependencies of the API.

The Detector v4 API provides tools for identification, submission, building and debugging.

The recommended identification request method is made using a server-side request and storing the segment in the users session, as this provides the best user experience and fewest possible requests to the Detector server. See our implementation guide for simplified examples.

Be aware of our terms.

The API is available at http://detector-v4.dearapi.com and https://detector-v4.dearapi.com.

You can also use http://detector.dearapi.com or https://detector.dearapi.com, which will always point to the latest version.

Identification

http://detector-v4.dearapi.com/

Performs segment identification based on device useragent, with the purpose of returning segment as a HTML snippet.

Useragent defaults to requesting device but specific useragent can be sent using the ua parameter.

POST or GET parameters

ua: Optional useragent to be identified. Defaults to requesting device useragent.
site: Optional origin site. We recommend you to add this parameter to your request to provide better usage statistics.
file: Optional origin file. We recommend you to add this parameter to your request to provide better usage statistics.

Request

http://detector-v4.dearapi.com/

Returns HTML formatted segment, like this:

<!DOCTYPE html>
<html>
<body>
<div id="device">
	<span id="segment" class="proporty">desktop_light</span>
</div>
</body>
</html>

Test this endpoint

http://detector-v4.dearapi.com/text

Performs segment identification based on device useragent, with the purpose of returning segment as a text string.

Useragent defaults to requesting device but specific useragent can be sent using the ua parameter.

POST or GET parameters

ua: Optional useragent to be identified. Defaults to requesting device useragent.
site: Optional origin site. We recommend you to add this parameter to your request to provide better usage statistics.
file: Optional origin file. We recommend you to add this parameter to your request to provide better usage statistics.

Request

http://detector-v4.dearapi.com/text

Returns text string segment, like this:

desktop_light

Test this endpoint

http://detector-v4.dearapi.com/xml

Performs segment identification based on device useragent, with the purpose of returning segment as a XML snippet.

Useragent defaults to requesting device but specific useragent can be sent using the ua parameter.

POST or GET parameters

ua: Optional useragent to be identified. Defaults to requesting device useragent.
site: Optional origin site. We recommend you to add this parameter to your request to provide better usage statistics.
file: Optional origin file. We recommend you to add this parameter to your request to provide better usage statistics.

Request

http://detector-v4.dearapi.com/xml

Returns XML formatted segment, like this:

<?xml version="1.0" encoding="UTF-8"?>
<device>
    <segment>desktop_light</segment>
</device>

Test this endpoint

http://detector-v4.dearapi.com/json

Performs segment identification based on device useragent, with the purpose of returning segment as a JSON object.

Useragent defaults to requesting device but specific useragent can be sent using the ua parameter.

POST or GET parameters

ua: Optional useragent to be identified. Defaults to requesting device useragent.
site: Optional origin site. We recommend you to add this parameter to your request to provide better usage statistics.
file: Optional origin file. We recommend you to add this parameter to your request to provide better usage statistics.

Request

http://detector-v4.dearapi.com/json

Returns segment in JSON object, like this:

{segment:"desktop_light"}

Test this endpoint

http://detector-v4.dearapi.com/jsonp

Performs segment identification based on device useragent, with the purpose of returning segment to local callback function.

Useragent defaults to requesting device but specific useragent can be sent using the ua parameter.

POST or GET parameters

ua: Optional useragent to be identified. Defaults to requesting device useragent.
site: Optional origin site. We recommend you to add this parameter to your request to provide better usage statistics.
file: Optional origin file. We recommend you to add this parameter to your request to provide better usage statistics.
callback: Optional callback function. Defaults to "callback"

Default request

http://detector-v4.dearapi.com/jsonp

Returns JSONP callback function with segment.

callback({"segment":"desktop_light"});

Request with custom callback

http://detector-v4.dearapi.com/jsonp?callback=initSegment

Returns JSONP initSegment callback function with segment.

initSegment({"segment":"desktop_light"});

Test this endpoint

http://detector-v4.dearapi.com/js-include

Performs segment identification based on device useragent, with the purpose of including the appropriate segment js and css, without using local server-side technology. This method uses the original Detector/Janitor filenaming conventions.

Requesting page should save segment in client-side cookie to avoid making repeating requests from same browsing session.

Useragent defaults to requesting device but specific useragent can be sent using the ua parameter.

GET parameters

ua: Optional useragent to be identified. Defaults to requesting device useragent.
site: Optional origin site. We recommend you to add this parameter to your request to provide better usage statistics.
file: Optional origin file. We recommend you to add this parameter to your request to provide better usage statistics.
path: Optional general include path. Defaults to /js and /css.
css_path: Optional CSS include path.
css_param: Optional CSS include file parameter.
js_path: Optional JavaScript include path.
js_param: Optional JavaScript include file parameter.
dev: Optional development include. Will include /css/lib/seg_segment_include.css and /js/lib/seg_segment_include.js following the recommended structure from http://janitor.parentnode.dk.

Standard usage

<script type="text/javascript" src="http://detector-v4.dearapi.com/js-include"></script>

Returns a JavaScript snippet with the appropriate JavaScript and CSS include statements.

document.write('<link type="text/css" rel="stylesheet" media="all" href="/css/seg_desktop_light.css" />');
document.write('<script type="text/javascript" src="/js/seg_desktop_light.js"></script>');

With js_path parameter

<script type="text/javascript" src="http://detector-v4.dearapi.com/js-include?js_path=/custom_path&js_param=cb=123"></script>

Returns a JavaScript snippet with the appropriate JavaScript and CSS include statements.

document.write('<link type="text/css" rel="stylesheet" media="all" href="/css/seg_desktop_light.css" />');
document.write('<script type="text/javascript" src="/custom_path/seg_desktop_light.js?cb=123"></script>');

Test this endpoint

Submission

http://detector-v4.dearapi.com/submit

Submit useragent to Detectors indexing system. Useragents submitted here will be considered when the Detector core is updated.

GET parameters

ua: Useragent to be submitted.
site: Optional origin site. We recommend you to add this parameter to your request to provide better usage statistics.
file: Optional origin file. We recommend you to add this parameter to your request to provide better usage statistics.

Request

http://detector-v4.dearapi.com/submit

Returns

success

Build

http://detector-v4.dearapi.com/build

Build static Detector-v4, using the latest available data.

Add optional custom grouping of segments to make the detection return exactly what you need. See the build page for more information.

POST or GET parameters

language: Required - programming language to export detector v4 in.
grouping: Optional custom segment grouping as JSON object.

Supported languages

PHP, JavaScript and Java.

Need it in another language? Then help us make it.

Grouping syntax

{
	"group-name":[
		"segment-name-1",
		"segment-name-2"
	]
}

Example 1

{
	"desktop":[
		"desktop",
		"desktop_ie10",
		"desktop_ie11",
		"tablet"
	],
	"mobile":[
		"smartphone",
		"mobile",
		"tablet_light",
	],
	"unsupported":[
		"tv",
		"desktop_light",
		"desktop_ie9",
		"mobile_light"
	]
}

Returns static standalone Detector v4 class in specified language, where detection will result in one of 4 custom segments: desktop, mobile, unsupported and the unmentioned seo.

Example 2

{
	"supported":[
		"desktop",
		"desktop_ie10",
		"desktop_ie11",
		"tablet"
		"smartphone",
	],
	"unsupported":[
		"mobile",
		"tablet_light",
		"tv",
		"desktop_light",
		"desktop_ie9",
		"mobile_light",
		"seo"
	]
}

Returns static standalone Detector v4 class in specified language, where detection will result in one of 2 custom segments: supported or unsupported.

Debugging

http://detector-v4.dearapi.com/debug

Performs segment identification based on device useragent, but collects and sends additional information to the development team.

Useragent defaults to requesting device but specific useragent can be sent using the ua parameter.

POST or GET parameters

ua: Optional useragent to be identified. Defaults to requesting device useragent.

Request

http://detector-v4.dearapi.com/debug

Returns extended set of device details as below, and sends email with debug information to development team.

<!DOCTYPE html>
<html>
<body>

<h1>Thank you for submitting your information</h1>
<p>Your browser details has been emailed to the API administrator.</p>

<div id="device">
	<div id="useragent" class="proporty">UserAgent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:58.0) Gecko/20100101 Firefox/58.0</div>
	<div id="segment" class="proporty">Segment: desktop_edge</div>
	<div id="model" class="proporty">Name: Firefox, Desktop edge</div>
	<div id="description" class="proporty">Description: Firefox 22+</div>
	<div id="published_at" class="proporty">Published at: 2013-05</div>
</div>

</body>
</html>

Detector v4 API Documentation

Identification

http://detector-v4.dearapi.com/

Request

http://detector-v4.dearapi.com/text

Request

http://detector-v4.dearapi.com/xml

Request

http://detector-v4.dearapi.com/json

Request

http://detector-v4.dearapi.com/jsonp

Default request

Request with custom callback

http://detector-v4.dearapi.com/js-include

Standard usage

With js_path parameter

Submission

http://detector-v4.dearapi.com/submit

Request

Build

http://detector-v4.dearapi.com/build

Supported languages

Grouping syntax

Example 1

Example 2

Debugging

http://detector-v4.dearapi.com/debug

Request

Detector v4
API Documentation