Skip to main content

NGINX Tutorial

This guide explains how to integrate SmartSezam into your application using automatic script injection via NGINX, without modifying your source code.

I - Technical​ Prerequisites​

Before proceeding with the integration, ensure the following prerequisites are met:

  • Access to your NGINX configuration (typically located at /etc/nginx/nginx.conf or within the /etc/nginx/conf.d/ directory).
  • Basic knowledge of NGINX configuration and Linux commands.
  • The following variables prepared beforehand:
    • $instanceDomainName = The full domain of your SmartSezam instance
    • $domainName = The domain name of your SmartSezam instance.
  • The ngx_http_sub_module enabled on your NGINX installation.

II - Installing​

  1. Open your NGINX configuration file (for example: /etc/nginx/sites-available/your-app.conf).

  2. Inside the appropriate server or location block, add the following directives:

    sub_filter_types text/html;
    sub_filter '</head>' ' <script src="https://$instanceDomainName/client.js"></script> </head>';
    sub_filter_once on;

    These directives use the ngx_http_sub_module, which allows NGINX to modify HTML responses dynamically by inserting the SmartSezam script before the closing </head> tag.

  3. Reload NGINX to apply changes:

    sudo systemctl reload nginx

⚡ Important​

The ngx_http_sub_module is not compiled by default in some distributions of NGINX.

  • On Ubuntu/Debian with the nginx-full package, it is usually included by default.
  • On minimal or custom installations (nginx-light, nginx-core, or custom builds), the module is typically not included and must be added manually.

You can check if the module is available with the following command:

nginx -V 2>&1 | grep -o http_sub_module

If nothing appears, you may need to install nginx-full or recompile NGINX with the --with-http_sub_module option.

III - Testing and Validation​

The validation process may vary depending on the chosen integration method :

  • In some cases, validation is handled by the SmartSezam team as part of the setup process.
  • In other cases, it can be performed manually via the real-time monitoring console :
  1. Open the real-time activity view in your SmartSezam dashboard.
  2. In a separate window or device, load the application where the tracker has been installed.

(Clearing the browser cache may be necessary if changes were made recently.)

  1. Return to the console and check that the session appears, confirming that the tracker is active.

If no activity appears, verify that the script is correctly included and configured, or contact SmartSezam support for help.