IBX-11100: Hybrid tracking described in Dev-doc

docs/recommendations/raptor_integration/hybrid_tracking.md

@@ -0,0 +1,112 @@
+---
+description: Enable hybrid tracking to avoid ad blockers and proxy events through your server.
+month_change: true
+---
+
+# Raptor hybrid tracking
+
+Hybrid tracking mode is an additional tracking mode available alongside [`client` and `server`](tracking_functions.md).
+In hybrid mode, the bundle includes a client side shim that captures Raptor tracking events and sends them to a same-origin endpoint instead of communicating directly with Raptor SaaS.
+The server enriches each event with identifiers resolved from request cookies (`cookieId`, `sessionId`, and `userId`) and forwards it to Raptor asynchronously through [Messenger](background_tasks.md).
+Since the browser never connects to the Raptor domain, ad blockers cannot block the requests.
+
+## Hybrid vs server or client side tracking
+
+Both `server` and `hybrid` tracking modes deliver pageviews and events server side, so tracking requests are not affected by ad blockers.
+The main difference is that `hybrid` mode loads a local, first-party tracking JavaScript (`raptor-proxy.js`) provided by the DXP instance, instead of the Raptor SaaS JavaScript.
+The Raptor script itself (`//deliver.raptorstatic.com/script/raptor-3.0.min.js`) is loaded only in `client` mode.
+
+The browser script only forwards captured tracking events to the same-origin proxy endpoint on your DXP instance. First-party visitor cookies are created and refreshed server side, which is what helps them survive Safari ITP.
+Event tracking still happens on the server, so ad blockers cannot block it.
+
+The main advantage of `hybrid` mode over `server` mode is its ability to capture client side tracking events.
+Visitor cookies are also refreshed more frequently than in `server` mode.
+
+Check the table below to compare the behavior of different tracking modes:
+
+|Tracking type|Browser script|Event delivery|Works with ad blockers|Cookie refresh                       |
+|-------------|--------------|--------------|----------------------|-------------------------------------|
+|client       |yes           |Browser       |no                    |yes                                  |
+|server       |no            |Server        |yes                   |yes (server side, on full page loads)|
+|hybrid       |yes           |Server        |yes                   |yes                                  |
+
+## Hybrid tracking flow
+
+When hybrid tracking is enabled, `TrackingScriptExtension` renders the proxy bootstrap template and loads the `raptor-proxy.js` shim, which replaces the `window.raptor.push` and drains the initial event queue.
+The shim sends events to the configured proxy endpoint, by default, `/raptor/track`.
+Each event is sent in a separate request using a batch-compatible format.
+The `TrackingProxyController::track` controller validates the `EventPayloadParser` payload, enriches each event with identifiers resolved from cookies, and dispatches one `TrackProxiedEventMessage` for every event.
+Messages are then processed asynchronously via Messenger and `TrackProxiedEventMessageHandler` ultimately forwards them to Raptor through `TrackingService::trackRawParameters`.
+
+### Hybrid tracking configuration
+
+To configure the Raptor hybrid tracking, use the `ibexa.system.<scope>.connector_raptor` configuration key in the `config/packages/ibexa_connector_raptor.yaml` file:
+
+``` yaml
+ibexa_connector_raptor:
+    hybrid_tracking_proxy_path: '/track'
+
+ibexa:
+    system:
+        default:
+            connector_raptor:
+                enabled: true
+                customer_id: '<id>'
+                tracking_type: hybrid
+```
+
+### Routing import
+
+Hybrid tracking requires routing import.
+It means that the proxy endpoint route must be imported in the project, for example in the `config/routes.yaml` file:
+
+``` yaml
+ibexa.connector_raptor:
+    resource: '@IbexaConnectorRaptorBundle/Resources/config/routing.yaml'
+```
+
+This import is required only in `hybrid` mode.
+Without it, the proxy endpoint returns 404 responses and tracking events are not processed.
+
+### Proxy path configuration
+
+You can configure the proxy endpoint path globally.
+By default, it's set to `/raptor/track`.
+The client side shim sends tracking events to this same-origin endpoint, which forwards them to Raptor asynchronously.
+
+``` yaml
+ibexa_connector_raptor:
+    hybrid_tracking_proxy_path: '/track'
+```
+
+!!! note
+
+   The path must start with a `/` symbol and cannot overlap with any existing routes.
+   The route is generated from this value, so updating it automatically updates the route as well.
+   You don't need to modify the routing import.
+
+After changing the configuration, clear the application cache:
+
+``` bash
+php bin/console cache:clear
+```
+
+Verify that the route has been registered correctly.
+To do it, run the following command:
+
+``` bash
+php bin/console debug:router | grep raptor
+```
+
+### Template usage
+
+By default, the tracking script waits for user consent before sending tracking events.
+Consent can be provided either by rendering the script with `ibexa_tracking_script` (`has_consented` = `true`) or by triggering the `enableTracking` JavaScript event.
+The same template syntax is used across all tracking modes, so changing `tracking_type` does not require any template changes.
+
+The Twig API remains identical regardless of the configured tracking mode:
+
+``` html+twig
+{{ ibexa_tracking_script() }}
+{{ ibexa_tracking_track_event('visit', product) }}
+```

mkdocs.yml

@@ -526,6 +526,7 @@ nav:
             - Raptor connector guide: recommendations/raptor_integration/raptor_connector_guide.md
             - Installation and configuration: recommendations/raptor_integration/connector_installation_configuration.md
             - Tracking functions: recommendations/raptor_integration/tracking_functions.md
+            - Hybrid tracking: recommendations/raptor_integration/hybrid_tracking.md
             - Tracking with PHP API: recommendations/raptor_integration/tracking_php_api.md
             - Recommendations blocks: recommendations/raptor_integration/recommendation_blocks.md
             - Custom recommendation rendering: recommendations/raptor_integration/custom_recommendation_rendering.md