From fd1598bb33dd3ea68b9bc5e41c8a01c9edfd5ef3 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Tue, 23 Jun 2026 14:16:07 +0200 Subject: [PATCH 1/4] hybrid tracking described --- .../raptor_integration/hybrid_tracking.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/recommendations/raptor_integration/hybrid_tracking.md diff --git a/docs/recommendations/raptor_integration/hybrid_tracking.md b/docs/recommendations/raptor_integration/hybrid_tracking.md new file mode 100644 index 0000000000..0c2a606a78 --- /dev/null +++ b/docs/recommendations/raptor_integration/hybrid_tracking.md @@ -0,0 +1,91 @@ +--- +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 difference is that `hybrid` mode also loads the Raptor JavaScript in the browser. + +The browser script is used only to manage first-party cookies. +It can create and refresh visitor cookies, which helps them last longer in Safari ITP. +Event tracking still happens on the server, so ad blockers cannot block it. + +Server mode should be used when browser side cookie management is not necessary. +While hybrid mode is useful when you want the benefits of server side tracking together with improved cookie persistence. + +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 |no | +|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 batched events to the configured proxy endpoint, by default, `/raptor/track`. +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 through `MessageProvider` and `SendersLocator`, and `TrackProxiedEventMessageHandler` ultimately forwards them to Raptor through `TrackingService::trackRawParameters`. + +### Hybrid tracking configuration + +To configure the Raptor hybrid tracking, use the `ibexa.system..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: '' + 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' +``` + +### 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. + 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. + +### Template usage + +The Twig API remains identical regardless of the configured tracking mode: + +``` html+twig +{{ ibexa_tracking_script() }} +{{ ibexa_tracking_track_event('visit', product) }} +``` From cdbbe8d158f2835e3e5d089b54921fd6afe33e9e Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Thu, 25 Jun 2026 11:29:16 +0200 Subject: [PATCH 2/4] fixes after review --- .../raptor_integration/hybrid_tracking.md | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/recommendations/raptor_integration/hybrid_tracking.md b/docs/recommendations/raptor_integration/hybrid_tracking.md index 0c2a606a78..355659a74c 100644 --- a/docs/recommendations/raptor_integration/hybrid_tracking.md +++ b/docs/recommendations/raptor_integration/hybrid_tracking.md @@ -13,27 +13,28 @@ Since the browser never connects to the Raptor domain, ad blockers cannot block ## 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 difference is that `hybrid` mode also loads the Raptor JavaScript in the browser. +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 is used only to manage first-party cookies. -It can create and refresh visitor cookies, which helps them last longer in Safari ITP. +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. -Server mode should be used when browser side cookie management is not necessary. -While hybrid mode is useful when you want the benefits of server side tracking together with improved cookie persistence. +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 |no | -|hybrid |yes |Server |yes |yes | +|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 batched events to the configured proxy endpoint, by default, `/raptor/track`. +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 through `MessageProvider` and `SendersLocator`, and `TrackProxiedEventMessageHandler` ultimately forwards them to Raptor through `TrackingService::trackRawParameters`. From 499ff952dd2f8b9de4a19ee749d1c571df8e83ed Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Thu, 25 Jun 2026 12:26:54 +0200 Subject: [PATCH 3/4] content added + fixes --- .../raptor_integration/hybrid_tracking.md | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/recommendations/raptor_integration/hybrid_tracking.md b/docs/recommendations/raptor_integration/hybrid_tracking.md index 355659a74c..4f17dffca7 100644 --- a/docs/recommendations/raptor_integration/hybrid_tracking.md +++ b/docs/recommendations/raptor_integration/hybrid_tracking.md @@ -36,7 +36,7 @@ When hybrid tracking is enabled, `TrackingScriptExtension` renders the proxy boo 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 through `MessageProvider` and `SendersLocator`, and `TrackProxiedEventMessageHandler` ultimately forwards them to Raptor through `TrackingService::trackRawParameters`. +Messages are then processed asynchronously via Messenger and `TrackProxiedEventMessageHandler` ultimately forwards them to Raptor through `TrackingService::trackRawParameters`. ### Hybrid tracking configuration @@ -65,6 +65,9 @@ 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. @@ -78,12 +81,29 @@ ibexa_connector_raptor: !!! note - The path must start with a `/` symbol. + 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 From 097056fd09dfe385157d90d16beb88329e2d8214 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Thu, 25 Jun 2026 12:30:14 +0200 Subject: [PATCH 4/4] mkdocs updated --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 6ecfc86c8c..11f1459020 100644 --- a/mkdocs.yml +++ b/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