blob: bb4e3699bacbffc0742a56085296069589337088 [file] [log] [blame]
Willy Tarreau29b25312016-11-08 14:57:29 +01001DeviceAtlas Device Detection
2----------------------------
3
4In order to add DeviceAtlas Device Detection support, you would need to download
David Carlier019dbd72021-02-16 11:37:45 +00005the API source code from https://deviceatlas.com/deviceatlas-haproxy-module.
6The build supports the USE_PCRE and USE_PCRE2 options. Once extracted :
Willy Tarreau29b25312016-11-08 14:57:29 +01007
David Carliere0724582021-02-19 12:01:38 +00008 $ make TARGET=<target> USE_PCRE=1 (or USE_PCRE2=1) USE_DEVICEATLAS=1 DEVICEATLAS_SRC=<path to the API root folder>
Willy Tarreau29b25312016-11-08 14:57:29 +01009
10Optionally DEVICEATLAS_INC and DEVICEATLAS_LIB may be set to override the path
11to the include files and libraries respectively if they're not in the source
12directory.
13
Michael Prokop4438c602019-05-24 10:25:45 +020014For HAProxy developers who need to verify that their changes didn't accidentally
David Carlier0470d702019-04-26 12:02:28 +000015break the DeviceAtlas code, it is possible to build a dummy library provided in
16the contrib/deviceatlas directory and to use it as an alternative for the full
17library. This will not provide the full functionalities, it will just allow
18haproxy to start with a deviceatlas configuration, which generally is enough to
19validate API changes :
20
21 $ make TARGET=<target> USE_PCRE=1 USE_DEVICEATLAS=1 DEVICEATLAS_SRC=$PWD/contrib/deviceatlas
22
Willy Tarreau29b25312016-11-08 14:57:29 +010023These are supported DeviceAtlas directives (see doc/configuration.txt) :
24 - deviceatlas-json-file <path to the DeviceAtlas JSON data file>.
25 - deviceatlas-log-level <number> (0 to 3, level of information returned by
26 the API, 0 by default).
27 - deviceatlas-property-separator <character> (character used to separate the
28 properties produced by the API, | by default).
29
30Sample configuration :
31
32 global
33 deviceatlas-json-file <path to json file>
34
35 ...
36 frontend
37 bind *:8881
38 default_backend servers
39
40There are two distinct methods available, one which leverages all HTTP headers
41and one which uses only a single HTTP header for the detection. The former
42method is highly recommended and more accurate. There are several possible use
43cases.
44
45# To transmit the DeviceAtlas data downstream to the target application
46
47All HTTP headers via the sample / fetch
48
49 http-request set-header X-DeviceAtlas-Data %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
50
Michael Prokop4438c602019-05-24 10:25:45 +020051Single HTTP header (e.g. User-Agent) via the converter
Willy Tarreau29b25312016-11-08 14:57:29 +010052
53 http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
54
55# Mobile content switching with ACL
56
57All HTTP headers
58
59 acl is_mobile da-csv-fetch(mobileDevice) 1
60
61Single HTTP header
62
63 acl device_type_tablet req.fhdr(User-Agent),da-csv-conv(primaryHardwareType) "Tablet"
64
65
66Please find more information about DeviceAtlas and the detection methods at https://deviceatlas.com/resources .