Skip to content
  • Documentation >
  • Templating >
  • Twig function reference >
  • Recommendations Twig functions

Recommendations Twig functions

The following Twig functions are supported while using Raptor connector:

ibexa_tracking_script() function

ibexa_tracking_script() Twig function allows you to embed main tracking script into the website. It loads the initial script into window.raptor, enabling events tracking, for example, page visits, product views, or buys, from the front-end. It can be overridden in multiple ways to support custom implementations and to render code snippet through Ibexa in Design Engine.

Tracking can be conditionally initialized depending on cookie consent logic. By default, the function returns the script for client-side use, while it can return nothing when used server-side.

This function accepts the following parameters:

Parameter Type Default value Remarks
customerId string From SiteAccess configuration Raptor account ID. Can be overridden for custom customer IDs.
hasConsented boolean false Controls loading of tracking based on user consent at render time.

Default setup:

1
{{ ibexa_tracking_script() }}
Example setup using parameters:

1
{{ ibexa_tracking_script(customerId: '123', hasConsented: true) }}

Without setting custom customerId parameter, the function renders the tracking script using the configured customerID from the connector configuration. It can be overridden by providing a custom value if needed.

If hasConsented is set to true in the template, the tracking script is initialized automatically. This value should be set if user consent for tracking cookies is already known at render time. If hasConsented parameter is set to false, tracking should be enabled by dispatching a custom JavaScript event after consent is granted, for example through a custom script in layout. When set dynamically, avoid enabling the HTTP cache for users without consent.

The recommended method to integrate the tracking script with custom front-end logic is to dispatch the enableTracking JavaScript event after tracking cookie consent is granted:

1
document.dispatchEvent(new CustomEvent('enableTracking'));

Note

In Symfony's debug mode, the provided script outputs diagnostic information to the console. This output is not included in production environment.

ibexa_tracking_track_event() function

The ibexa_tracking_track_event() function is responsible for sending event data to the service, enabling tracking of user interactions and behaviors.

Tracking is handled through twig function that accept following parameters:

1
2
3
4
5
6
ibexa_tracking_track_event(
    eventType,     {# string: 'visit', 'contentvisit', 'buy', 'basket', 'itemclick' #}
    data,          {# mixed: product, content, or null (optional) #}
    context,       {# array: additional context data (optional) #}
    template       {# string: custom template path (optional) #}
)
  • eventType - type: string, defines the type of tracking event to be sent, for example, visit, contentvisit, buy, basket, itemclick
  • data (optional) - type: mixed, accepts the primary object associated with the event, such as a Product or Content, can be null if not required. For more information, check tracking event examples.
  • context (optional)- type: array, additional event data, such as quantity, basket details, or custom parameters. For more information, see example usage.
  • template (optional) - type: string, path to a custom Twig template used to render the tracking event, allows overriding the default tracking output

Tracking events

The following events are supported and can be triggered from Twig templates:

Product visit event

This event tracks product page visits by users. It's the most common e-commerce tracking event used to capture product views for analytics, recommendation models, and user behavior processing.

Required data:

  • Product object - defines the product being tracked. It implements ProductInterface so the system can read its information (for example, ID, price, category).

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# templates/product/view.html.twig #}
{% extends 'base.html.twig' %}

{% block content %}
    <div class="product-details">
        <h1>{{ product.name }}</h1>
        <p>{{ product.description }}</p>
        <div class="price">{{ product.price }}</div>
    </div>

    {# Track product visit #}
    {{ ibexa_tracking_track_event('visit', product) }}
{% endblock %}

Content visit event

This event tracks content page visits by users. It can used to check content views for analytics, personalization, and user behavior tracking.

  • Content object - defines the content being tracked.

Basket event

This event tracks when a product is added to the shopping basket.

It catches user interest and helps with conversion tracking and product recommendations.

Required data:

  • Product object - defines the product being added to the basket.
  • Context array with basket information - provides optional data about the basket, like quantity or basket ID, to provide context for the event.

Example:

 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
# templates/cart/add_confirmation.html.twig #}
{% extends 'base.html.twig' %}

{% block content %}
    <div class="cart-notification">
        <p>Product "{{ product.name }}" has been added to your cart!</p>
        <p>Quantity: {{ addedQuantity }}</p>
    </div>

    {# Build basket content string: "SKU:quantity;SKU:quantity" #}
    {% set basketContent = [] %}
    {% for item in basket.items %}
        {% set basketContent = basketContent|merge([item.product.code ~ ':' ~ item.quantity]) %}
    {% endfor %}

    {# Track basket addition #}
    {% set basketContext = {
        'basketContent': basketContent|join(';'),
        'basketId': basket.id,
        'quantity': addedQuantity
    } %}

    {{ ibexa_tracking_track_event('basket', product, basketContext) }}

    <a href="{{ path('cart_view') }}">View Cart</a>
{% endblock %}

Simplified example with Twig filter:

1
2
3
4
5
6
7
8
{# If you have a custom Twig filter to format basket content #}
{% set basketContext = {
    'basketContent': basket|format_basket_content,  {# Returns "SKU-1:2;SKU-2:1;SKU-3:5" #}
    'basketId': basket.id,
    'quantity': addedQuantity
} %}

{{ ibexa_tracking_track_event('basket', product, basketContext) }}

Simplified example with Twig filter:

1
2
3
4
5
6
7
8
{# If you have a custom Twig filter to format basket content #}
{% set basketContext = {
    'basketContent': basket|format_basket_content,  {# Returns "SKU-1:2;SKU-2:1;SKU-3:5" #}
    'basketId': basket.id,
    'quantity': addedQuantity
} %}

{{ ibexa_tracking_track_event('basket', product, basketContext) }}

context parameter - example usage

You can use context parameter to add additional data.

During tracking, for products assigned to multiple categories, the system uses the first category. In this case, context parameter allows to override the product category by passing a category identifier:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{% block content %}
    <div class="product-details">
        <h1>{{ product.name }}</h1>
        {# ... product content ... #}
    </div>

    {# Track with category identifier - automatic loading and formatting #}
        {{ ibexa_tracking_track_event('visit', product, {
        'categoryIdentifier': 'electronics'
    }) }}
{% endblock %}

For another example of context parameter usage, see Basket event.

Custom Templates

You can override the default tracking templates by providing a custom template path:

1
2
3
4
5
6
{{ ibexa_tracking_track_event(
    'visit',
    product,
    {},
    '@MyBundle/tracking/custom_visit.html.twig'
) }}