• 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

The ibexa_tracking_script() Twig function allows you to embed the main tracking script into the website. It loads the initial script into window.raptor. The script then enables event tracking, such as 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 the design engine.

Tracking can be conditionally initialized depending on cookie consent logic. By default, for client-side use, the function returns a script, but 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:

{{ ibexa_tracking_script() }}

Example setup using parameters:

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

If the custom customerId parameter is not set, the function uses the customerID from the connector configuration to render the tracking script. It can be overridden by providing a custom value if needed.

If the hasConsented parameter 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 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. If it's 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:

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, which enables tracking of user interactions and behaviors.

Tracking is handled through a twig function that accept following parameters:

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. For more information, see Tracking events for recommendations.
• 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, see 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 Ibexa\Contracts\ProductCatalog\Values\ProductInterface so the system can read its information (for example, code, price, category).

Example:

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

contentvisit event

This event tracks content page visits by users. It implements Ibexa\Contracts\Core\Repository\Values\Content\Content and can be used to check content views for analytics, personalization, and user behavior tracking.

• Content object - defines the content being tracked.

Example:

{# templates/bundles/IbexaCoreBundle/default/content/full.html.twig #}
{% extends '@!IbexaCore/default/content/full.html.twig' %}

{% block content %}
    {{ parent() }}
    {{ ibexa_tracking_track_event('contentvisit', content) }}
{% endblock %}

itemclicked event

This event tracks when a user clicks a Raptor recommendation, including adding products to the cart from the recommendation module.

Required data:

• Product code - defines the product code added to the cart.
• Context - provides optional data, like moduleName or redirectUrl, to provide context for the event.

Example:

{{ ibexa_tracking_track_event('itemclick', product.code, {
    'moduleName': 'homepage-recommendations',
    'redirectUrl': path('ibexa.product.view', {'productCode': product.code})
}) }}

Basket event

This event tracks when a product is added to the cart.

It captures user interactions that indicate interest, which can be used for conversion tracking and to improve product recommendations.

Required data:

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

Example:

{# 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: "product-code:quantity;product-code:quantity" #}
    {% set basketContent = [] %}
    {% for entry in cart.entries %}
        {% set basketContent = basketContent|merge([entry.product.code ~ ':' ~ entry.quantity]) %}
    {% endfor %}
    {# Track basket addition #}
    {% set basketContext = {
        'basketContent': basketContent|join(';'),
        'basketId': cart.id,
        'quantity': addedQuantity
    } %}

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

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

context parameter - example usage

You can use the context parameter to pass additional data.

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

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

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

For another usage example, see the Basket event.

Custom templates

You can create a custom template for tracking in the /templates/tracking/ directory. See the following example of custom_visit.html.twig:

{{ ibexa_tracking_track_event(
      'visit',
      product,
      {},
      '@App/tracking/custom_visit.html.twig'
) }}

{# templates/tracking/custom_visit.html.twig #}

{# # Custom visit tracking template # # Available variables: # - parameters: array of Raptor tracking parameters (p1, p2, p3, etc.) # - debug: boolean flag to enable debug console messages #}

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

``` html+twig
{{ ibexa_tracking_track_event(
      'visit',
      product,
      {},
      '@App/tracking/custom_visit.html.twig'
) }}