Troubleshooting

Is the device-type module loaded correctly?

If you encounter issues with device detection, the module may not be loaded. The load_module directive is required to use the device-type module.

To check if the module is loaded, look for the load_module directive in your nginx.conf file. It should point to the correct .so file.

load_module modules/ngx_http_device_type_module.so;

If it's missing, add the line above to the top of your nginx.conf and reload NGINX.

nginx -s reload

Why does $is_mobile return 1 for tablets?

The $is_mobile variable may return 1 for tablets due to the classification logic in the module. Some tablets are detected as mobile devices based on their user-agent strings.

To refine the detection, you can use the $device_type variable instead, which provides more specific classifications.

if ($device_type = "tablet") {
    # Handle tablet-specific logic here
}

Why are client hints not being respected?

If client hints are not being processed, ensure that your NGINX configuration is set up to accept them. The module supports Sec-CH-UA, Sec-CH-UA-Mobile, and Sec-CH-UA-Platform.

Check your configuration to ensure that these headers are being passed correctly to the device-type module.

proxy_set_header Sec-CH-UA $http_sec_ch_ua;
proxy_set_header Sec-CH-UA-Mobile $http_sec_ch_ua_mobile;
proxy_set_header Sec-CH-UA-Platform $http_sec_ch_ua_platform;

Why does $device_json return empty?

An empty $device_json variable may indicate that the module did not detect any device information from the request. This can happen if the user-agent string is not recognized.

To troubleshoot, log the user-agent string to see if it matches any of the regex patterns.

log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status '
                 '"$http_user_agent" "$device_json"';
access_log /var/log/nginx/access.log custom;

Are there false positives for tablets?

The module may incorrectly classify some devices as tablets due to overlapping user-agent strings. This is a known limitation of regex-based detection.

To address this, consider implementing additional logic based on the $device_type variable.

if ($device_type = "tablet") {
    # Adjust handling for tablets here
}

How can I improve regex performance?

If you experience performance issues, ensure that PCRE JIT is enabled. This can significantly enhance regex processing speed.

Add the following directive at the top level of your nginx.conf:

pcre_jit on;

After making changes, reload NGINX to apply the new settings.

nginx -s reload