diff --git a/docs/recommendations/raptor_integration/hybrid_tracking.md b/docs/recommendations/raptor_integration/hybrid_tracking.md new file mode 100644 index 0000000000..4f17dffca7 --- /dev/null +++ b/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..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' +``` + +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) }} +``` 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