iframe-proxy

julitafalcondusza · 2026-06-23T12:17:02Z

Hybrid tracking described in Dev-doc

Checklist

Text renders correctly
Text has been checked with vale
Description metadata is up to date
Redirects cover removed/moved pages
Code samples are working
PHP code samples have been fixed with PHP CS fixer
Added link to this PR in relevant JIRA ticket or code PR

github-actions · 2026-06-23T12:17:23Z

Preview of modified files

Preview of modified Markdown:

mnocon

Hybrid tracking must be mentioned in other places, it's not enough to describe it just in a separate article - right now it feels disconnected from other parts of the doc.

Examples:

https://ez-systems-developer-documentation--3250.com.readthedocs.build/en/3250/recommendations/raptor_integration/connector_installation_configuration/#siteaccess-aware-configuration

tracking_type: hybrid must be mentioned, in the YAML and in the list

https://ez-systems-developer-documentation--3250.com.readthedocs.build/en/3250/recommendations/raptor_integration/connector_installation_configuration/#global-configuration-non-siteaccess-aware

hybrid_tracking_proxy_path should be mentioned in the global configuration reference?

https://ez-systems-developer-documentation--3250.com.readthedocs.build/en/3250/recommendations/raptor_integration/tracking_functions/#embed-tracking-script

The function output must be expanded to mention the hybrid type

github-actions · 2026-06-29T11:03:39Z

code_samples/ change report

Before (on target branch)	After (in current PR)
`code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml` docs/recommendations/raptor_integration/connector_installation_configuration.md@28:``` yaml `docs/recommendations/raptor_integration/connector_installation_configuration.md@29:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml', 0, 17) =]]` docs/recommendations/raptor_integration/connector_installation_configuration.md@30:``` `001⫶ibexa:` `002⫶ system:` `003⫶ <scope>:` `004⫶ connector_raptor:` `005⫶ enabled: true` `006⫶ customer_id: ~ # Required`	`code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml` docs/recommendations/raptor_integration/connector_installation_configuration.md@28:``` yaml `docs/recommendations/raptor_integration/connector_installation_configuration.md@29:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml', 0, 17) =]]` docs/recommendations/raptor_integration/connector_installation_configuration.md@30:``` `001⫶ibexa:` `002⫶ system:` `003⫶ <scope>:` `004⫶ connector_raptor:` `005⫶ enabled: true` `006⫶ customer_id: ~ # Required`
`007⫶ tracking_type: client # One of: "client" or "server"`	`007⫶ tracking_type: client # One of: "client", "server", or "hybrid"`
`008⫶` `009⫶ # Raptor Recommendations API key` `010⫶ recommendations_api_key: ~ # Required` `011⫶` `012⫶ # Raptor Recommendations API URL, optional, set by default` `013⫶ recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'` `014⫶` `015⫶ # Cookie lifetime in days for server-side tracking identifier` `016⫶ # Default: 365 days. Minimum: 1 day.` `017⫶ cookie_id_lifetime_days: 365`	`008⫶` `009⫶ # Raptor Recommendations API key` `010⫶ recommendations_api_key: ~ # Required` `011⫶` `012⫶ # Raptor Recommendations API URL, optional, set by default` `013⫶ recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'` `014⫶` `015⫶ # Cookie lifetime in days for server-side tracking identifier` `016⫶ # Default: 365 days. Minimum: 1 day.` `017⫶ cookie_id_lifetime_days: 365`
docs/recommendations/raptor_integration/connector_installation_configuration.md@77:``` yaml hl_lines="18-20" `docs/recommendations/raptor_integration/connector_installation_configuration.md@78:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml') =]]` docs/recommendations/raptor_integration/connector_installation_configuration.md@79:```	docs/recommendations/raptor_integration/connector_installation_configuration.md@80:``` yaml hl_lines="18-21" `docs/recommendations/raptor_integration/connector_installation_configuration.md@81:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml') =]]` docs/recommendations/raptor_integration/connector_installation_configuration.md@82:```
`001⫶ibexa:` `002⫶ system:` `003⫶ <scope>:` `004⫶ connector_raptor:` `005⫶ enabled: true` `006⫶ customer_id: ~ # Required`	`001⫶ibexa:` `002⫶ system:` `003⫶ <scope>:` `004⫶ connector_raptor:` `005⫶ enabled: true` `006⫶ customer_id: ~ # Required`
`007⫶ tracking_type: client # One of: "client" or "server"`	`007⫶ tracking_type: client # One of: "client", "server", or "hybrid"`
`008⫶` `009⫶ # Raptor Recommendations API key` `010⫶ recommendations_api_key: ~ # Required` `011⫶` `012⫶ # Raptor Recommendations API URL, optional, set by default` `013⫶ recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'` `014⫶` `015⫶ # Cookie lifetime in days for server-side tracking identifier` `016⫶ # Default: 365 days. Minimum: 1 day.` `017⫶ cookie_id_lifetime_days: 365` `018❇️ibexa_connector_raptor:` `019❇️ # When enabled, tracking exceptions are thrown instead of being silently handled` `020❇️ strict_exceptions: true`	`008⫶` `009⫶ # Raptor Recommendations API key` `010⫶ recommendations_api_key: ~ # Required` `011⫶` `012⫶ # Raptor Recommendations API URL, optional, set by default` `013⫶ recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'` `014⫶` `015⫶ # Cookie lifetime in days for server-side tracking identifier` `016⫶ # Default: 365 days. Minimum: 1 day.` `017⫶ cookie_id_lifetime_days: 365` `018❇️ibexa_connector_raptor:` `019❇️ # When enabled, tracking exceptions are thrown instead of being silently handled` `020❇️ strict_exceptions: true`
	`021❇️ hybrid_tracking_proxy_path: '/track'`

Download colorized diff

mnocon

Hybrid tracking should be added to the cards in https://ez-systems-developer-documentation--3250.com.readthedocs.build/en/3250/recommendations/raptor_integration/raptor_connector/
Let's mention hybrid tracking in https://ez-systems-developer-documentation--3250.com.readthedocs.build/en/3250/recommendations/raptor_integration/raptor_connector_guide/ as well (https://ez-systems-developer-documentation--3250.com.readthedocs.build/en/3250/recommendations/raptor_integration/raptor_connector_guide/#availability mentions the two already existing types)

mnocon · 2026-06-29T14:27:30Z

 ibexa_connector_raptor:
    # When enabled, tracking exceptions are thrown instead of being silently handled
    strict_exceptions: true
+    hybrid_tracking_proxy_path: '/track'


Suggested change

hybrid_tracking_proxy_path: '/track'

hybrid_tracking_proxy_path: '/raptor/track'

I don't think a lot of people will customize this, let's just use the default value here

mnocon · 2026-06-29T14:52:49Z


 - `strict_exceptions` – when enabled, tracking exceptions are thrown instead of being silently handled. Default value: `%kernel.debug%`.

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


Suggested change

- `hybrid_tracking_proxy_path` - 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.

- `hybrid_tracking_proxy_path` - 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.

mnocon · 2026-06-29T14:53:21Z

 - `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 the [Twig functions](recommendations_twig_functions.md) and included in the 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.
+    - `hybrid` - loads a local, first-party tracking JavaScript provided by the DXP instance, instead of the Raptor SaaS JavaScript.


Suggested change

- `hybrid` - loads a local, first-party tracking JavaScript provided by the DXP instance, instead of the Raptor SaaS JavaScript.

- `hybrid` - loads a local, first-party tracking JavaScript provided by the DXP instance, instead of the Raptor SaaS JavaScript. For more information, see [Hybrid tracking](hybrid_tracking.md).

mnocon · 2026-06-29T14:58:55Z

+
+## 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` function and drains the initial event queue.


Ok, so let's make it clearer:

Suggested change

When hybrid tracking is enabled, `TrackingScriptExtension` renders the proxy bootstrap template and loads the `raptor-proxy.js` shim, which replaces the `window.raptor.push` function and drains the initial event queue.

When hybrid tracking is enabled, `TrackingScriptExtension` renders the proxy bootstrap template and loads the `raptor-proxy.js` shim, which replaces the `window.raptor.push` function and sends out the events queued before the tracking consent was given.

mnocon · 2026-06-29T15:03:29Z

+    hybrid_tracking_proxy_path: '/track'
+```
+
+!!! note


This note is broken in rendering

hybrid tracking described

fd1598b

julitafalcondusza added 3 commits June 25, 2026 11:29

fixes after review

cdbbe8d

content added + fixes

499ff95

mkdocs updated

097056f

julitafalcondusza marked this pull request as ready for review June 25, 2026 10:38

julitafalcondusza added the Needs DEV review label Jun 25, 2026

julitafalcondusza requested a review from tbialcz June 25, 2026 10:38

tbialcz reviewed Jun 29, 2026

View reviewed changes

Comment thread docs/recommendations/raptor_integration/hybrid_tracking.md

note added

590b7a4

tbialcz approved these changes Jun 29, 2026

View reviewed changes

blank lines removed

c249d43

julitafalcondusza added Needs DOC review and removed Needs DEV review labels Jun 29, 2026

mnocon requested changes Jun 29, 2026

View reviewed changes

fixes after review

cc5a81b

julitafalcondusza requested a review from mnocon June 29, 2026 10:56

mnocon reviewed Jun 29, 2026

View reviewed changes

Question	Answer
JIRA Ticket	(https://github.com/ibexa/connector-raptor/pull/59)
Versions	5.0
Edition	all

	hybrid_tracking_proxy_path: '/track'
	hybrid_tracking_proxy_path: '/raptor/track'


		- `strict_exceptions` – when enabled, tracking exceptions are thrown instead of being silently handled. Default value: `%kernel.debug%`.

		- `hybrid_tracking_proxy_path` - 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.

	- `hybrid` - loads a local, first-party tracking JavaScript provided by the DXP instance, instead of the Raptor SaaS JavaScript.
	- `hybrid` - loads a local, first-party tracking JavaScript provided by the DXP instance, instead of the Raptor SaaS JavaScript. For more information, see [Hybrid tracking](hybrid_tracking.md).


		## 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` function and drains the initial event queue.

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

Conversation

julitafalcondusza commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

github-actions Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview of modified files

Uh oh!

Uh oh!

mnocon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 29, 2026

code_samples/ change report

Uh oh!

mnocon left a comment

Choose a reason for hiding this comment

Uh oh!

mnocon Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

mnocon Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

mnocon Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

mnocon Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

mnocon Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

julitafalcondusza commented Jun 23, 2026 •

edited

Loading

github-actions Bot commented Jun 23, 2026 •

edited

Loading