Introduction🔗

Use our Nginx module to run Device Detection in Nginx. This page explains installation and configuration.

Prerequisites🔗

See our tested versions page for tested versions and platforms.

Installing🔗

If you haven’t already, you can obtain the latest version of the API from the 51degrees-nginx repository.

To build the module only, run the following command. This will output to ngx_http_51D_module.so in the build/modules directory.

make module

To build the module and Nginx, run the following command.

make install

By default, this will use the latest version of Nginx specified in the Makefile. To use a specific version of Nginx, run the above command with the FIFTYONEDEGREES_NGINX_VERSION variable. e.g.,

make install FIFTYONEDEGREES_NGINX_VERSION=[Version]

To build and link the module statically with Nginx, use the STATIC_BUILD variable. e.g.,

make install STATIC_BUILD=1

Finally, run the 51Degrees tests with the default 51Degrees Lite data file, which the tests read from the cxx/data/device-detection folder. Download it first by running sh cxx/data/get-data-files.sh 51Degrees-LiteV4.1.hash from the repository root. The script is part of the data repository, which the cxx submodule includes at cxx/data. Make sure to build the module with make install command as the tests do not work on a static build.

make test

To run the 51Degrees tests together with the Nginx test suite, run:

make test-full

These do not run all the required tests as some tests require properties that are not supported with the Lite version of the data file. To run all tests, obtain a data file that provides properties: JavascriptHardwareProfile, ScreenPixelsWidthJavascript, and ScreenPixelsWidth. Then, use the 51DEGREES_DD_PATH variable to give the path of the data file to run the tests with. If tests still fail, obtain a data file with any other properties used in the tests. Below is an example of running tests with a different data file named 51Degrees-EnterpriseV4.1.hash:

make [test|test-full] 51DEGREES_DD_PATH=/path/to/51Degrees-EnterpriseV4.1.hash

Configuring the Nginx API🔗

Before you start performing any detections, you may wish to configure the detection.

Initialization settings🔗

Detection configuration directives.

Directives

Syntax: 51D_file_path filename;
Default: —
Context: main
Specify the data file to used for 51Degrees Device Detection V4 engine

Syntax: 51D_drift drift;
Default: 51D_drift 0;
Context: main
Specify the drift value that a detection can allow. Details about how setting drift value effects the results can be found at False Positive.

Syntax: 51D_difference difference;
Default: 51D_difference 0;
Context: main
Specify the difference value that a detection can allow. Details about how setting difference value effects the results can be found at False Positive.

Syntax: 51D_allow_unmatched on | off;
Default: 51D_allow_unmatched off;
Context: main
Specify if AllowUnmatched should be allowed. Details about how setting AllowUnmatched value effects the results can be found at False Positive.

Syntax: 51D_use_performance_graph on | off;
Default: 51D_use_performance_graph off;
Context: main
Specify if performance graph should be used in detection. Deprecated since version 4.5. The performance graph is now an alias of the predictive graph, so this setting does not change the results. More details about performance graph can be found at Hash.

Syntax: 51D_use_predictive_graph on | off;
Default: 51D_use_predictive_graph on;
Context: main
Specify if predictive graph should be used in detection. More details about predictive graph can be found at Hash.

Syntax: 51D_value_separator separator;
Default: 51D_value_separator ',';
Context: main
Specify the separator to be used in the value string returned from a detection. Each value in the returned result string corresponds to a requested property.

Match settings🔗

Match directives.

Directives

Syntax: 51D_match_single header properties [argument];
Default: —
Context: main, server, location (NOTE: This directive can be used in main, server and location blocks. Specified properties are aggregated and eventually queried in the location. header value is set after the query is performed and is only available within location block)
Perform a detection using a single request header User-Agent. header specifies which request header the returned properties values should be stored at. properties is a comma separated list string. argument specifies if User-Agent is supplied as a query argument. This will override the value in the User-Agent header. The argument is optional.
If a property is not available for any reason, the value being returned for that property will be NoMatch

Syntax: 51D_match_all header properties;
Default: —
Context: main, server, location (NOTE: This directive can be used in main, server and location blocks. Specified properties are aggregated and eventually queried in the location. header value is set after the query is performed and is only available within location block)
Perform a detection using all headers, query argument and cookie from a http request. header specifies which request header the returned properties values should be stored at. properties is a comma separated list string.
If a property is not available for any reason, the value being returned for that property will be NoMatch

Syntax: 51D_get_javascript_single javascript_property [argument];
Default: —
Context: location
Perform a detection using a single request header User-Agent. The returned value of javascript_property is set in the response body. This works in a similar way as CDN to serve static content. argument specifies if User-Agent is supplied as a query argument. This will override the value in the User-Agent header. The argument is optional.
If the Javascript property is not available for any reason, a Javascript block comment will be returned so that it will not cause syntax error when the client s it.
The whole response body is used for the returned content so only one of these directives can be used in a single location block. Also, since the static content does not actually exist as a static file, the nginx http core module will log an error, so it is recommended to use this directive with log_not_found set to off.

Syntax: 51D_get_javascript_all javascript_property;
Default: —
Context: location
Perform a detection using all headers, cookie and query arguments from a http request. The returned value of javascript_property is set in the response body. This works in a similar way as CDN to serve static content.
If the Javascript property is not available for any reason, a Javascript block comment will be returned so that it will not cause syntax error when the client executes it.
The whole response body is used for the returned content so only one of these directives can be used in a single location block. Also, since the static content does not actually exist as a static file, the nginx http core module will log an error, so it is recommended to use this directive with log_not_found set to off.

Syntax: 51D_set_resp_headers on | off;
Default: 51D_set_resp_headers off
Context: main, server, location
Allow Client Hints to be set in response headers where it is applicable to the user agent (e.g. Chrome 89 or above) so that more evidence can be returned in subsequent requests, allowing more accurate detection. Value set in a block overwrites values set in precedent blocks (e.g. value set in location block will overwrite value set in server and main blocks). This will only be available from the 4.3.0 version onwards.

New features🔗

The Nginx Device Detection V4 module supports:

Detection match metrics
Javascript and property overrides
False Positive controls
User-Agent Client Hints support

Detection match metrics🔗

This V3 functionality is extended with more options available in V4. These metrics can be used in the same way as the properties.

51D_match_all x-metrics IsMobile,Iterations,Drift,Difference,Method,UserAgents,MatchedNodes,DeviceId;

JavaScript and property overrides🔗

Some properties require JavaScript to run in the browser. For example, run the JavaScript from ScreenPixelsWidthJavascript to obtain ScreenPixelsWidth. Use 51D_get_javascript_single or 51D_get_javascript_all to serve the JavaScript as response content.

Once the value has been obtained by executing the Javascript in client user agent, it can be added as evidence in the next request's cookie or query argument. 51Degrees module will override the returned value with what it found in the request.

False positive controls🔗

Nginx Device Detection V4 module supports False Positives features as described at False Positives via settings of directives 51D_drift, 51D_difference, and 51D_allow_unmatched. When AllowUnmatched is set to off, if HasValue is false, a NoMatch will be returned. Else, if AllowUnmatched is set to on, when a match can not be found, default profile will be returned such as Unknown, N/A, or similar.

User-Agent Client Hints support🔗

User-Agent Client Hint was introduced by Google in Chrome, preventing traditional detection using User-Agents from performing accurate matches. In Nginx Device Detection V4 module, 51D_set_resp_headers was implemented to allow Client Hint request headers to be set in responses so that more evidence is provided in subsequent requests, allowing better matches.

Other resources🔗

More details can be found at: