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, and Twig functions for straightforward integration.

Raptor integration introduces two Twig functions:

Embed tracking script

You must embed the tracking script into the website’s layout to enable tracking. To do it, add the ibexa_tracking_script() twig function into the section of your base layout template, for example, @ibexadesign/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 ibexa_tracking_script Twig block that includes the script.js.twig template. 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.

Extending default templates

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 %}

As an alternative approach, you can override the template by providing a custom template path:

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 -->

```