Introduction
We have also integrated our Device Detection to Nginx. This page describes in detail how you can install and use our module in your Nginx environment.
Prerequisites
For the latest dependencies, tested version, and tested platforms information, please refer to our tested versions and dependencies pages.
Installing
If you haven’t already, you can obtain a copy of the latest version of the API here.
To build the module only, run the following command. This will output to ngx_http_51D_module.so in the build/modules directory.
To build the module and Nginx, run the following command.
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.,
To build and link the module statically with Nginx, use the STATIC_BUILD variable. e.g.,
Finally, run the 51Degrees tests with the default 51Degrees Lite data file included in the device-detection-cxx\device-detection-data directory. Make sure to build the module with make install command as the tests do not work on a static build.
To run the 51Degrees together with the Nginx test suite, run the following command:
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 FIFTYONEDEGREES_DATAFILE variable to specify the file name to run the tests with. The new data file should be placed in the device-detection-cxx\device-detection-data folder and should have a different name to 51Degrees-LiteV4.1.hash. 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:
Configuring the Nginx API
Before you start performing any detections, you may wish to configure the detection.
Init 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. 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 NA |
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 NA |
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
Following set of new features has been introduced in Nginx Device Detection V4 module:
- Detection match metrics
- Javascript and property overrides
- False Positive controls
- User-Agent Client Hint supports
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.
Javascript and property overrides
Some certain properties might require further steps to obtain. For example, to determine ScreenPixelsWidth, users might need to execute the Javascript returned from ScreenPixelsWidthJavascript property in client User-Agents. In V4, we allow users to request the Javascript as static content via using 51D_get_javascript_single and 51D_get_javascript_all directives.
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 Hint supports
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: