Skip to content
  • Documentation >
  • Recommendations >
  • Integration with Raptor >
  • Tracking functions

Raptor tracking functions

Raptor connector introduces visit tracking functionality for collecting user interactions with products and content. The implementation includes product visit tracking with mapping to tracking parameters, as well as Twig functions for straightforward integration.

Raptor integration introduces two Twig functions:

Embed tracking script

To enable tracking, tracking script must be embedded into the website’s layout. To embed tracking script, add the twig function ibexa_tracking_script() into the section of your base layout template, for example, pagelayout.html.twig:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{# templates/pagelayout.html.twig #}
<!DOCTYPE html>
<html>
<head>
    {# ... other head content ... #}

    {# Initialize Raptor tracking - must be called before any tracking events #}
    {{ ibexa_tracking_script() }}
</head>
<body>
    {# ... page content ... #}
</body>
</html>

Tracking modes

Tracking user interactions can be implemented on the client-side or the server-side. Each approach differs in where events are captured and how they are sent to the tracking backend.

The tracking Twig function outputs different content depending on the mode:

1
2
3
4
5
6
7
# Server-side tracking
connector_raptor:
    tracking_type: 'server'  # Returns HTML comments

# Client-side tracking
connector_raptor:
    tracking_type: 'client'  # Returns <script> tags
  • server - returns HTML comments, placeholders that do not perform any action. Instead, the tracking is done server-side.
  • client - returns script tags to load the tracking script in the browser.

You can switch tracking mode anytime by changing the tracking_type parameter.

For more information on Tracking modes, see Raptor documentation:

Complex integration

For more complex integrations, the Ibexa Design Engine can be used to override parts or entire templates that render the tracking script.

Template Description Example project path
@ibexadesign/ibexa/tracking/script.html.twig Responsible for creating the window.raptor object and handling consent. Loads tracking only if consent is given and listens for the enableTracking event. templates/themes/standard/ibexa/tracking/script.html.twig
@ibexadesign/ibexa/tracking/script.js.twig Handles the loading of the tracking JavaScript. templates/themes/standard/ibexa/tracking/script.js.twig

Available variables are:

  • customer_id - type: string, Raptor account ID used for tracking
  • script_url - type: string, URL of the tracking script, by default //deliver.raptorstatic.com/script/raptor-3.0.min.js, configurable through ibexa.connector.raptor.tracking_script.url Symfony Dependency Injection container parameter (not SiteAccess-aware)
  • has_consented - type: boolean, indicates whether the user has given consent, default value: false (unless explicitly passed as function argument)
  • debug - type: boolean, kernel.debug Symfony dependency injection container parameter, typically true in development environments and false in production

The default template defines a Twig block that includes script.js.twig. When extending the template, this block can be overridden to customize the script’s behavior.

You can override the default templates, either individually or both at the same time.

Extension

It's possible to extend script.html.twig by combining the Ibexa Design Engine with standard Symfony template reference in templates/themes/standard/ibexa/tracking/script.html.twig:

1
2
3
4
{% extends '@IbexaConnectorRaptor/themes/standard/ibexa/tracking/script.html.twig' %}
{% block ibexa_tracking_script %}
    console.log('My custom tracking script, but relying on loadTracking function.');
{% endblock %}

In most cases, the preferred approach is to do the opposite:

1
2
3
4
5
<script type="text/javascript">
    if (myCustomConsentIsGiven) {
           {{ include('@ibexadesign/ibexa/tracking/script.js.twig', {'customer_id': customer_id}) }}
    }
</script>

Example custom integration

Example custom integration with TermsFeed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
``` html
<!-- Cookie Consent by TermsFeed https://www.TermsFeed.com -->
<script type="text/javascript" src="https://www.termsfeed.com/public/cookie-consent/4.2.0/cookie-consent.js" charset="UTF-8"></script>
<script type="text/javascript" charset="UTF-8">
    document.addEventListener('DOMContentLoaded', function () {
        cookieconsent.run({
            "notice_banner_type": "simple",
            "consent_type": "implied",
            "palette": "dark",
            "language": "en",
            "page_load_consent_levels": ["strictly-necessary"],
            "notice_banner_reject_button_hide": false,
            "preferences_center_close_button_hide": false,
            "page_refresh_confirmation_buttons": false,
            "website_name": "Ibexa Storefront",
            "callbacks": {
                "scripts_specific_loaded": (level) => {
                    switch(level) {
                        case 'tracking':
                            document.dispatchEvent(new CustomEvent('enableTracking'));
                            break;
                    }
                }
            },
            "callbacks_force": true
        });
    });
</script>
<noscript>Free cookie consent management tool by <a href="https://www.termsfeed.com/">TermsFeed</a></noscript>
<!-- End Cookie Consent by TermsFeed https://www.TermsFeed.com -->

```