ibexa · mnocon · Apr 14, 2026 · Apr 3, 2026 · Apr 3, 2026 · Apr 3, 2026
diff --git a/code_samples/recommendations/EventData.php b/code_samples/recommendations/EventData.php
@@ -0,0 +1,13 @@
+<php>
+use Ibexa\Contracts\ConnectorRaptor\Tracking\Event\VisitEventData;
+
+$eventData = new VisitEventData(
+    productId: $product->getCode(),
+    productName: $product->getName(),
+    categoryPath: '25#Electronics;26#Smartphones',  // Build manually
+        currency: 'USD',
+    itemPrice: '999.99'
+);
+
+$this->trackingDispatcher->dispatch($eventData);
+</php>
diff --git a/code_samples/recommendations/EventMapper.php b/code_samples/recommendations/EventMapper.php
@@ -0,0 +1,22 @@
+<php>
+use Ibexa\Contracts\ConnectorRaptor\Tracking\EventMapperInterface;
+use Ibexa\Contracts\ConnectorRaptor\Tracking\ServerSideTrackingDispatcherInterface;
+use Ibexa\Contracts\ConnectorRaptor\Tracking\EventType;
+
+class MyCustomService
+{
+    public function __construct(
+        private readonly EventMapperInterface $eventMapper,
+        private ServerSideTrackingDispatcherInterface $trackingDispatcher,
+    ) {}
+
+    public function trackProductView(ProductInterface $product, string $url): void
+    {
+        // Map product to VisitEventData automatically
+        $eventData = $this->eventMapper->map(EventType::VISIT, $product);
+
+        // Send tracking event
+        $this->trackingDispatcher->dispatch($eventData);
+    }
+}
+</php>
diff --git a/code_samples/recommendations/EventSubscriber.php b/code_samples/recommendations/EventSubscriber.php
@@ -0,0 +1,39 @@
+<php>
+use Ibexa\Contracts\ConnectorRaptor\Tracking\EventMapperInterface;
+use Ibexa\Contracts\ConnectorRaptor\Tracking\ServerSideTrackingDispatcherInterface;
+use Ibexa\Contracts\ConnectorRaptor\Tracking\EventType;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\HttpKernel\Event\ResponseEvent;
+use Symfony\Component\HttpKernel\KernelEvents;
+
+class ProductViewTrackingSubscriber implements EventSubscriberInterface
+{
+    public function __construct(
+        private readonly EventMapperInterface $eventMapper,
+        private ServerSideTrackingDispatcherInterface $trackingDispatcher,
+    ) {}
+
+    public static function getSubscribedEvents(): array
+    {
+        return [KernelEvents::RESPONSE => ['onResponse', -10]];
+    }
+
+    public function onResponse(ResponseEvent $event): void
+    {
+        if (!$event->isMainRequest()) {
+            return;
+        }
+
+        $request = $event->getRequest();
+
+        // Example: track only if request has specific attribute
+        $product = $request->attributes->get('product');
+        if (!$product) {
+            return;
+        }
+
+        $eventData = $this->eventMapper->map(EventType::VISIT, $product);
+        $this->trackingDispatcher->dispatch($eventData);
+    }
+}
+</php>
diff --git a/code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml b/code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml
@@ -0,0 +1,16 @@
+ibexa:
+    system:
+        <scope>:
+            connector_raptor:
+                enabled:              true
+                customer_id:          ~ # Required
+                tracking_type:        client # One of: "client" or "server"
+
+                # Raptor Recommendations API key
+                recommendations_api_key: ~ # Required
+
+                # Raptor Recommendations API URL, optional, set by default
+                recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'
+ibexa_connector_raptor:
+    # When enabled, tracking exceptions are thrown instead of being silently handled
+    strict_exceptions: true
diff --git a/code_samples/recommendations/custom_integration.html b/code_samples/recommendations/custom_integration.html
@@ -0,0 +1,31 @@
+``` 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 -->
+```
diff --git a/code_samples/recommendations/events/basket_event.html.twig b/code_samples/recommendations/events/basket_event.html.twig
@@ -0,0 +1,39 @@
+# 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:
+
+``` html+twig
+{# 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) }}
diff --git a/code_samples/recommendations/events/product_visit_event.html.twig b/code_samples/recommendations/events/product_visit_event.html.twig
@@ -0,0 +1,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 %}
diff --git a/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.html.twig b/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.html.twig
@@ -0,0 +1,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 %}
diff --git a/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.js.twig b/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.js.twig
@@ -0,0 +1,5 @@
+<script type="text/javascript">
+    if (myCustomConsentIsGiven) {
+           {{ include('@ibexadesign/ibexa/tracking/script.js.twig', {'customer_id': customer_id}) }}
+    }
+</script>
diff --git a/code_samples/recommendations/templates/themes/standard/pagelayout.html.twig b/code_samples/recommendations/templates/themes/standard/pagelayout.html.twig
@@ -0,0 +1,14 @@
+{# 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>
+```
diff --git a/docs/recommendations/raptor_integration/connector_installation_configuration.md b/docs/recommendations/raptor_integration/connector_installation_configuration.md
@@ -0,0 +1,69 @@
+---
+description: Step-by-step configuration procedure of the Raptor connector.
+month_change: true
+---
+
+# Installation
+
+First, install the Raptor connector.
+To do it, run the following command:
+
+``` bash
+composer require ibexa/connector-raptor
+```
+
+# SiteAccess-aware configuration
+
+To configure Raptor connector, use the `ibexa.system.<scope>.connector_raptor` configuration key in the `config/packages/ibexa_connector_raptor.yaml` file:
+
+``` yaml
+[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml', 1, 14) =]]
+```
+
+- `enabled` - enables or disables the Connector for a given scope, default value: `true`. If set to `false`, no tracking or recommendation requests are executed.
+- `customer_id` - an identifier used to authenticate requests to the Recommendation Engine. This value can be found as `Account number` in [Raptor Control Panel](https://controlpanel.raptorsmartadvisor.com/).
+- `tracking_type` - defines how user events are sent to the tracking API. Default value: `client`. Possible values:
+    - `client` - tracking is executed in the browser using JavaScript snippets generated by [Twig functions](../../templating/twig_function_reference/recommendations_twig_functions.md) and included in templates. This approach may be blocked by ad blockers.
+    - `server` - tracking is handled on the backend, with events sent directly to the tracking API. It's not affected by ad blockers.
+- `recommendations_api_key` - an API key used to authenticate requests to the Recommendations API. This key allows the Connector to retrieve personalized recommendations from the Recommendation Engine. This value can be found as `API key` in Raptor Control Panel.
+- `recommendations_api_url` (optional) - overrides the default Raptor address, should be left unset unless a custom endpoint is required.
+
+By default, `tracking_type` is set to `client` as client-side tracking is the standard Raptor mode.
+To understand the differences between client and server tracking types, including their advantages and disadvantages, refer to the [Raptor documentation](https://content.raptorservices.com/help-center/client-side-vs.-server-side-tracking).
+
+!!! note
+
+    Only one tracking mode can be enabled at a time.
+    Client-side and server-side tracking cannot be used together.
+
+## Customer ID
+
+To find the value for the `customer_id` identifier, log in to Raptor Control Panel, and look for "Account number":
+
+A. In the top-left corner, above the account name, you can find the account number for the currently active account.
+B. Click the arrow icon in the top-left corner to expand the window. There you can see a list of all your accounts, with their numbers shown in the “Account number” column on the right (if you have multiple accounts, you can easily locate and copy the number of any of your accounts, not just the active one).
+
+![Account number](account_number.png)
+
+## Recommendations API key
+
+To find the value for the `recommendations_api_key`, log in to Raptor Control Panel, and look for "API key".
+To do it, in the left panel, open the **Recommendations** section, and select **Website**.
+Next, click on the Web module you’re interested in.
+In the top-right corner, click the three-dot icon and select **API information**.
+A new window appears, where you can find the "API key" value.
+Click on the **Show API information** and copy the value.
+
+![API key](api_key.png)
+
+# Global configuration (non-SiteAccess-aware)
+
+The following settings are global and apply to the entire application (they are not scoped per SiteAccess):
+
+- `strict_exceptions` – when enabled, tracking exceptions are thrown instead of being silently handled. Default value: `%kernel.debug%`.
+
+This value can be overriden in `config/packages/ibexa_connector_raptor.yaml` file, for example:
+
+``` yaml hl_lines="14-17"
+[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml') =]]
+```
diff --git a/docs/recommendations/raptor_integration/img/account_number.png b/docs/recommendations/raptor_integration/img/account_number.png
diff --git a/docs/recommendations/raptor_integration/img/advanced_settings.png b/docs/recommendations/raptor_integration/img/advanced_settings.png
diff --git a/docs/recommendations/raptor_integration/img/api_key.png b/docs/recommendations/raptor_integration/img/api_key.png
diff --git a/docs/recommendations/raptor_integration/img/raptor_module.png b/docs/recommendations/raptor_integration/img/raptor_module.png
diff --git a/docs/recommendations/raptor_integration/img/recommendation_blocks.png b/docs/recommendations/raptor_integration/img/recommendation_blocks.png
diff --git a/docs/recommendations/raptor_integration/raptor_connector.md b/docs/recommendations/raptor_integration/raptor_connector.md
@@ -0,0 +1,34 @@
+---
+description: Step-by-step activation procedure of setting up the Raptor connector.
+page_type: landing_page
+month_change: true
+---
+
+# Raptor connector
+
+The [Raptor](https://www.raptorservices.com/) connector provides a seamless integration between [[= product_name =]] and Raptor Recommendation Engine.
+
+Its primary goal is to enable editors and managers to deliver personalized experiences across digital channels, which helps to increase conversion rates, drive sales, and improve user engagement.
+
+By combining content management capabilities with advanced recommendation features, the connector allows teams to build and manage personalized experiences directly within a single platform.
+
+This connector ensures a smooth and unified integration layer, enabling:
+
+- event tracking through the tracking API
+- personalized content delivery through the Recommendations API
+- flexible, SiteAccess-aware configuration
+
+This approach reduces integration complexity while providing a scalable foundation for personalization use cases across multiple sites and markets.
+
+To configure the Raptor integration, follow a step-by-step procedure that allows you to activate the Raptor connector.
+Activation includes [configuration](connector_installation_configuration.md), adding tracking scripts and events, and using [Page Builder](page_builder_guide.md) blocks.
+
+For more information on tracking, check the Raptor documentation: [Implementing tracking](https://content.raptorservices.com/help-center/data-management#implementing-tracking).
+
+[[= cards([
+    "recommendations/raptor_integration/connector_installation_configuration",
+    "recommendations/raptor_integration/tracking_functions",
+    "recommendations/raptor_integration/tracking_php_api",
+    "recommendations/raptor_integration/recommendation_blocks",
+    "templating/twig_function_reference/recommendations_twig_functions",
+], columns=3) =]]
diff --git a/docs/recommendations/raptor_integration/recommendation_blocks.md b/docs/recommendations/raptor_integration/recommendation_blocks.md
@@ -0,0 +1,41 @@
+---
+description: Recommendation blocks in Page Builder
+edition: experience
+month_change: true
+---
+
+# Recommendation blocks in Page Builder
+
+One of the Raptor Integration elements is the introduction of recommendation blocks available in the [Page Builder](page_builder_guide.md).
+
+Each Content, Product, and Commerce recommendation can be added to a landing page using the blocks.
+
+Editors can configure these blocks to display:
+
+- personalized product recommendations
+- related articles or content
+- recently viewed or popular items
+
+In the toolbar, corresponding categories for recommendation blocks are available, containing sets of blocks depending on the recommendation type:
+
+- **Recommendations: Content** - presents content recommendations:
+    - [Most popular content]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-content-block)
+    - [Other customers have also seen this content]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-seen-this-content-block)
+    - [Personalized content recommendations]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#personalized-content-recommendations-block)
+- **Recommendations: Product** - displays product suggestions based on visitors’ browsing history:
+    - [Most popular products]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-products-block)
+    - [Most popular products in category]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-products-in-category-block)
+    - [Other customers have also seen]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-seen-block)
+- **Recommendations: Commerce** - shows recommendations based on visitors' purchase history (buy and basket events):
+    - [The Personal Shopping Assistant]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#the-personal-shopping-assistant-block)
+    - [User's item history or current basket items sorted by recent items or top items]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#users-item-history-or-current-basket-items-sorted-by-recent-items-or-top-items-block)
+
+![Recommendation blocks](img/recommendation_blocks.png)
+
+After opening the settings of a recommendation block, a link is available at the bottom of the window.
+It leads to the [Raptor Control Panel](https://controlpanel.raptorsmartadvisor.com/) (opens in a separate tab), where you can configure advanced settings and fine-tune the recommendation strategy.
+
+![Advanced settings](img/advanced_settings.png)
+
+For a complete description of Recommendation blocks see [Recommendation blocks]([[= user_doc =]]/recommendations/raptor_integration/raptor_recommendation_blocks/).
+For the list of all page blocks that are available in Page Builder, see [Block reference page]([[= user_doc =]]/content_management/block_reference/).