Raptor integration - feature branch

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>

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>

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>

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

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

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

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

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

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>

code_samples/recommendations/templates/themes/standard/pagelayout.html.twig

@@ -0,0 +1,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>

docs/product_guides/product_guides.md

@@ -23,4 +23,5 @@ Discover the primary ones with the help of product guides. Condensed content all
     "commerce/shopping_list/shopping_list_guide",
     "ibexa_cloud/ibexa_cloud_guide",
     "cdp/cdp_guide",
+    "recommendations/raptor_integration/raptor_connector_guide",
 ], columns=4) =]]

docs/recommendations/raptor_integration/connector_installation_configuration.md

@@ -0,0 +1,73 @@
+---
+description: Step-by-step configuration procedure of the Raptor connector.
+month_change: true
+---
+
+# Configuration procedure
+
+To configure the Raptor integration, follow a step-by-step procedure that allows you to activate the Raptor connector.
+
+## Install Raptor connector
+
+Before you can proceed to configuring the integration with Raptor, install the [Raptor](https://www.raptorservices.com/) connector.
+To do it, run the following command:
+
+``` bash
+composer require ibexa/connector-raptor
+```
+
+## SiteAccess-aware configuration
+
+To configure the 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. You can find this value 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. You can find this value as "API key" in [Raptor Control Panel](https://controlpanel.raptorsmartadvisor.com/).
+- `recommendations_api_url` (optional) - overrides the default Raptor address, do not set 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. This way, if you have multiple accounts, you can 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 **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') =]]
+```

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 is an add-on that 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 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.
+
+The 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 integration with Raptor, 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) =]]