Raptor integration - feature branch by julitafalcondusza · Pull Request #3121 · ibexa/documentation-developer

julitafalcondusza · 2026-04-03T12:50:26Z

Question	Answer
JIRA Ticket
Versions	5.0
Edition	all

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-04-03T12:50:42Z

Preview of modified files

Preview of modified Markdown:

adriendupuis

The PHP API page content a lot of non PHP examples to move to Twig functions' pages.
It misses more link to navigate through the pages.
I added some PHP API Reference links (preview: https://ez-systems-developer-documentation--3122.com.readthedocs.build/en/3122/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor.html).

docs/recommendations/raptor_integration/connector_installation_configuration.md

docs/recommendations/raptor_integration/tracking_functions.md

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

docs/templating/twig_function_reference/recommendations_twig_functions.md

docs/recommendations/raptor_integration/tracking_php_api.md

docs/templating/twig_function_reference/recommendations_twig_functions.md

sonarqubecloud · 2026-04-07T10:16:39Z

Quality Gate failed

Failed conditions
1 Security Hotspot
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

github-actions · 2026-04-07T10:17:48Z

code_samples/ change report

Before (on target branch)	After (in current PR)
`code_samples/recommendations/EventData.php`	`code_samples/recommendations/EventData.php`
	docs/recommendations/raptor_integration/tracking_php_api.md@30:``` php `docs/recommendations/raptor_integration/tracking_php_api.md@31:[[= include_file('code_samples/recommendations/EventData.php') =]]` docs/recommendations/raptor_integration/tracking_php_api.md@32:``` `001⫶<php>` `002⫶use Ibexa\Contracts\ConnectorRaptor\Tracking\Event\VisitEventData;` `003⫶` `004⫶$eventData = new VisitEventData(` `005⫶ productId: $product->getCode(),` `006⫶ productName: $product->getName(),` `007⫶ categoryPath: '25#Electronics;26#Smartphones', // Build manually` `008⫶ currency: 'USD',` `009⫶ itemPrice: '999.99'` `010⫶);` `011⫶` `012⫶$this->trackingDispatcher->dispatch($eventData);` `013⫶</php>`
`code_samples/recommendations/EventMapper.php`	`code_samples/recommendations/EventMapper.php`
	docs/recommendations/raptor_integration/tracking_php_api.md@19:``` php `docs/recommendations/raptor_integration/tracking_php_api.md@20:[[= include_file('code_samples/recommendations/EventMapper.php') =]]` docs/recommendations/raptor_integration/tracking_php_api.md@21:``` `001⫶<php>` `002⫶use Ibexa\Contracts\ConnectorRaptor\Tracking\EventMapperInterface;` `003⫶use Ibexa\Contracts\ConnectorRaptor\Tracking\ServerSideTrackingDispatcherInterface;` `004⫶use Ibexa\Contracts\ConnectorRaptor\Tracking\EventType;` `005⫶` `006⫶class MyCustomService` `007⫶{` `008⫶ public function __construct(` `009⫶ private readonly EventMapperInterface $eventMapper,` `010⫶ private ServerSideTrackingDispatcherInterface $trackingDispatcher,` `011⫶ ) {}` `012⫶` `013⫶ public function trackProductView(ProductInterface $product, string $url): void` `014⫶ {` `015⫶ // Map product to VisitEventData automatically` `016⫶ $eventData = $this->eventMapper->map(EventType::VISIT, $product);` `017⫶` `018⫶ // Send tracking event` `019⫶ $this->trackingDispatcher->dispatch($eventData);` `020⫶ }` `021⫶}` `022⫶</php>`
`code_samples/recommendations/EventSubscriber.php`	`code_samples/recommendations/EventSubscriber.php`
	docs/recommendations/raptor_integration/tracking_php_api.md@41:``` php `docs/recommendations/raptor_integration/tracking_php_api.md@42:[[= include_file('code_samples/recommendations/EventSubscriber.php') =]]` docs/recommendations/raptor_integration/tracking_php_api.md@43:``` `001⫶<php>` `002⫶use Ibexa\Contracts\ConnectorRaptor\Tracking\EventMapperInterface;` `003⫶use Ibexa\Contracts\ConnectorRaptor\Tracking\ServerSideTrackingDispatcherInterface;` `004⫶use Ibexa\Contracts\ConnectorRaptor\Tracking\EventType;` `005⫶use Symfony\Component\EventDispatcher\EventSubscriberInterface;` `006⫶use Symfony\Component\HttpKernel\Event\ResponseEvent;` `007⫶use Symfony\Component\HttpKernel\KernelEvents;` `008⫶` `009⫶class ProductViewTrackingSubscriber implements EventSubscriberInterface` `010⫶{` `011⫶ public function __construct(` `012⫶ private readonly EventMapperInterface $eventMapper,` `013⫶ private ServerSideTrackingDispatcherInterface $trackingDispatcher,` `014⫶ ) {}` `015⫶` `016⫶ public static function getSubscribedEvents(): array` `017⫶ {` `018⫶ return [KernelEvents::RESPONSE => ['onResponse', -10]];` `019⫶ }` `020⫶` `021⫶ public function onResponse(ResponseEvent $event): void` `022⫶ {` `023⫶ if (!$event->isMainRequest()) {` `024⫶ return;` `025⫶ }` `026⫶` `027⫶ $request = $event->getRequest();` `028⫶` `029⫶ // Example: track only if request has specific attribute` `030⫶ $product = $request->attributes->get('product');` `031⫶ if (!$product) {` `032⫶ return;` `033⫶ }` `034⫶` `035⫶ $eventData = $this->eventMapper->map(EventType::VISIT, $product);` `036⫶ $this->trackingDispatcher->dispatch($eventData);` `037⫶ }` `038⫶}` `039⫶</php>`
`code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml`	`code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml`
	docs/recommendations/raptor_integration/connector_installation_configuration.md@23:``` yaml `docs/recommendations/raptor_integration/connector_installation_configuration.md@24:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml', 1, 14) =]]` docs/recommendations/raptor_integration/connector_installation_configuration.md@25:``` `001⫶ system:` `002⫶ <scope>:` `003⫶ connector_raptor:` `004⫶ enabled: true` `005⫶ customer_id: ~ # Required` `006⫶ tracking_type: client # One of: "client" or "server"` `007⫶` `008⫶ # Raptor Recommendations API key` `009⫶ recommendations_api_key: ~ # Required` `010⫶` `011⫶ # Raptor Recommendations API URL, optional, set by default` `012⫶ recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'` `013⫶ibexa_connector_raptor:` docs/recommendations/raptor_integration/connector_installation_configuration.md@71:``` yaml hl_lines="14-17" `docs/recommendations/raptor_integration/connector_installation_configuration.md@72:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml') =]]` docs/recommendations/raptor_integration/connector_installation_configuration.md@73:``` `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"` `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❇️ibexa_connector_raptor:` `015❇️ # When enabled, tracking exceptions are thrown instead of being silently handled` `016❇️ strict_exceptions: true`
`code_samples/recommendations/custom_integration.html`	`code_samples/recommendations/custom_integration.html`
	docs/recommendations/raptor_integration/tracking_functions.md@92:``` html `docs/recommendations/raptor_integration/tracking_functions.md@93:[[= include_file('code_samples/recommendations/custom_integration.html') =]]` docs/recommendations/raptor_integration/tracking_functions.md@94:``` 001⫶``` html `002⫶<!-- Cookie Consent by TermsFeed https://www.TermsFeed.com -->` `003⫶<script type="text/javascript" src="https://www.termsfeed.com/public/cookie-consent/4.2.0/cookie-consent.js" charset="UTF-8"></script>` `004⫶<script type="text/javascript" charset="UTF-8">` `005⫶ document.addEventListener('DOMContentLoaded', function () {` `006⫶ cookieconsent.run({` `007⫶ "notice_banner_type": "simple",` `008⫶ "consent_type": "implied",` `009⫶ "palette": "dark",` `010⫶ "language": "en",` `011⫶ "page_load_consent_levels": ["strictly-necessary"],` `012⫶ "notice_banner_reject_button_hide": false,` `013⫶ "preferences_center_close_button_hide": false,` `014⫶ "page_refresh_confirmation_buttons": false,` `015⫶ "website_name": "Ibexa Storefront",` `016⫶ "callbacks": {` `017⫶ "scripts_specific_loaded": (level) => {` `018⫶ switch(level) {` `019⫶ case 'tracking':` `020⫶ document.dispatchEvent(new CustomEvent('enableTracking'));` `021⫶ break;` `022⫶ }` `023⫶ }` `024⫶ },` `025⫶ "callbacks_force": true` `026⫶ });` `027⫶ });` `028⫶</script>` `029⫶<noscript>Free cookie consent management tool by <a href="https://www.termsfeed.com/">TermsFeed</a></noscript>` `030⫶<!-- End Cookie Consent by TermsFeed https://www.TermsFeed.com -->` 031⫶```
`code_samples/recommendations/events/basket_event.html.twig`	`code_samples/recommendations/events/basket_event.html.twig`
	docs/templating/twig_function_reference/recommendations_twig_functions.md@115:``` html+twig `docs/templating/twig_function_reference/recommendations_twig_functions.md@116:[[= include_file('code_samples/recommendations/events/basket_event.html.twig') =]]` docs/templating/twig_function_reference/recommendations_twig_functions.md@117:``` `001⫶# templates/cart/add_confirmation.html.twig #}` `002⫶{% extends 'base.html.twig' %}` `003⫶` `004⫶{% block content %}` `005⫶ <div class="cart-notification">` `006⫶ <p>Product "{{ product.name }}" has been added to your cart!</p>` `007⫶ <p>Quantity: {{ addedQuantity }}</p>` `008⫶ </div>` `009⫶` `010⫶ {# Build basket content string: "SKU:quantity;SKU:quantity" #}` `011⫶ {% set basketContent = [] %}` `012⫶ {% for item in basket.items %}` `013⫶ {% set basketContent = basketContent\|merge([item.product.code ~ ':' ~ item.quantity]) %}` `014⫶ {% endfor %}` `015⫶` `016⫶ {# Track basket addition #}` `017⫶ {% set basketContext = {` `018⫶ 'basketContent': basketContent\|join(';'),` `019⫶ 'basketId': basket.id,` `020⫶ 'quantity': addedQuantity` `021⫶ } %}` `022⫶` `023⫶ {{ ibexa_tracking_track_event('basket', product, basketContext) }}` `024⫶` `025⫶ <a href="{{ path('cart_view') }}">View Cart</a>` `026⫶{% endblock %}` 027⫶``` `028⫶` `029⫶Simplified example with Twig filter:` `030⫶` 031⫶``` html+twig `032⫶{# If you have a custom Twig filter to format basket content #}` `033⫶{% set basketContext = {` `034⫶ 'basketContent': basket\|format_basket_content, {# Returns "SKU-1:2;SKU-2:1;SKU-3:5" #}` `035⫶ 'basketId': basket.id,` `036⫶ 'quantity': addedQuantity` `037⫶} %}` `038⫶` `039⫶{{ ibexa_tracking_track_event('basket', product, basketContext) }}`
`code_samples/recommendations/events/product_visit_event.html.twig`	`code_samples/recommendations/events/product_visit_event.html.twig`
	docs/templating/twig_function_reference/recommendations_twig_functions.md@91:``` html+twig `docs/templating/twig_function_reference/recommendations_twig_functions.md@92:[[= include_file('code_samples/recommendations/events/product_visit_event.html.twig') =]]` docs/templating/twig_function_reference/recommendations_twig_functions.md@93:``` `001⫶# templates/product/view.html.twig #}` `002⫶{% extends 'base.html.twig' %}` `003⫶` `004⫶{% block content %}` `005⫶ <div class="product-details">` `006⫶ <h1>{{ product.name }}</h1>` `007⫶ <p>{{ product.description }}</p>` `008⫶ <div class="price">{{ product.price }}</div>` `009⫶ </div>` `010⫶` `011⫶ {# Track product visit #}` `012⫶ {{ ibexa_tracking_track_event('visit', product) }}` `013⫶{% endblock %}`
`code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.html.twig`	`code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.html.twig`
	docs/recommendations/raptor_integration/tracking_functions.md@78:``` html+twig `docs/recommendations/raptor_integration/tracking_functions.md@79:[[= include_file('code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.html.twig') =]]` docs/recommendations/raptor_integration/tracking_functions.md@80:``` `001⫶{% extends '@IbexaConnectorRaptor/themes/standard/ibexa/tracking/script.html.twig' %}` `002⫶{% block ibexa_tracking_script %}` `003⫶ console.log('My custom tracking script, but relying on loadTracking function.');` `004⫶{% endblock %}`
`code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.js.twig`	`code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.js.twig`
	docs/recommendations/raptor_integration/tracking_functions.md@84:``` html+twig `docs/recommendations/raptor_integration/tracking_functions.md@85:[[= include_file('code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.js.twig') =]]` docs/recommendations/raptor_integration/tracking_functions.md@86:``` `001⫶<script type="text/javascript">` `002⫶ if (myCustomConsentIsGiven) {` `003⫶ {{ include('@ibexadesign/ibexa/tracking/script.js.twig', {'customer_id': customer_id}) }}` `004⫶ }` `005⫶</script>`
`code_samples/recommendations/templates/themes/standard/pagelayout.html.twig`	`code_samples/recommendations/templates/themes/standard/pagelayout.html.twig`
	docs/recommendations/raptor_integration/tracking_functions.md@21:``` html+twig `docs/recommendations/raptor_integration/tracking_functions.md@22:[[= include_file('code_samples/recommendations/templates/themes/standard/pagelayout.html.twig') =]]` docs/recommendations/raptor_integration/tracking_functions.md@23:``` `001⫶{# templates/pagelayout.html.twig #}` `002⫶<!DOCTYPE html>` `003⫶<html>` `004⫶<head>` `005⫶ {# ... other head content ... #}` `006⫶` `007⫶ {# Initialize Raptor tracking - must be called before any tracking events #}` `008⫶ {{ ibexa_tracking_script() }}` `009⫶</head>` `010⫶<body>` `011⫶ {# ... page content ... #}` `012⫶</body>` `013⫶</html>`

Download colorized diff

adriendupuis

Few links to fix to get the preview again.

You can merge #3123 so you'll also have the 3 PHP API Ref pages used.

adriendupuis · 2026-04-07T12:04:34Z

docs/templating/twig_function_reference/recommendations_twig_functions.md

+```
+
+- **eventType** - type: string, defines the type of tracking event to be sent, for example, `visit`, `contentvisit`, `buy`, `basket`, `itemclick`
+- **data** (optional) - type: mixed, accepts the primary object associated with the event, such as a Product or Content, can be null if not required. For more information, check [tracking event examples](tracking_php_api.md#tracking-events).


Suggested change

- **data** (optional) - type: mixed, accepts the primary object associated with the event, such as a Product or Content, can be null if not required. For more information, check [tracking event examples](tracking_php_api.md#tracking-events).

- **data** (optional) - type: mixed, accepts the primary object associated with the event, such as a Product or Content, can be null if not required. For more information, check [tracking event examples](#tracking-events).

adriendupuis · 2026-04-07T12:05:52Z

docs/templating/twig_function_reference/recommendations_twig_functions.md

+{% endblock %}
+```
+
+For another example of `context` parameter usage, see [Basket event](tracking_php_api.md#basket-event).


Suggested change

For another example of `context` parameter usage, see [Basket event](tracking_php_api.md#basket-event).

For another example of `context` parameter usage, see [Basket event](#basket-event).

adriendupuis · 2026-04-07T12:09:27Z

docs/recommendations/raptor_integration/raptor_connector_guide.md

+
+## How does Raptor tracking work
+
+To start [tracking]((https://content.raptorservices.com/help-center/introduction-to-tracking-documentation)) user interactions, the tracking script needs to be added to the website’s layout.


Double parenthesis broke the link

WARNING - Doc file 'recommendations/raptor_integration/raptor_connector_guide.md' contains an unrecognized relative link '(https://content.raptorservices.com/help-center/introduction-to-tracking-documentation)', it was left as is.

Suggested change

To start [tracking]((https://content.raptorservices.com/help-center/introduction-to-tracking-documentation)) user interactions, the tracking script needs to be added to the website’s layout.

To start [tracking](https://content.raptorservices.com/help-center/introduction-to-tracking-documentation) user interactions, the tracking script needs to be added to the website’s layout.

julitafalcondusza added 4 commits April 3, 2026 11:56

first batch added

3583d90

content added

6be8b25

recommendations twig page added

0e888f8

updates

f99ef95

julitafalcondusza added 2 commits April 3, 2026 14:50

content moved, structure updated

2e6f571

guide added

9307035

adriendupuis requested changes Apr 7, 2026

View reviewed changes

julitafalcondusza added 3 commits April 7, 2026 11:04

guide content

0930200

fixes, content moved

5c30896

fixes after review

ae73918

adriendupuis requested changes Apr 7, 2026

View reviewed changes

	- data (optional) - type: mixed, accepts the primary object associated with the event, such as a Product or Content, can be null if not required. For more information, check [tracking event examples](tracking_php_api.md#tracking-events).
	- data (optional) - type: mixed, accepts the primary object associated with the event, such as a Product or Content, can be null if not required. For more information, check [tracking event examples](#tracking-events).

	For another example of `context` parameter usage, see [Basket event](tracking_php_api.md#basket-event).
	For another example of `context` parameter usage, see [Basket event](#basket-event).


		## How does Raptor tracking work

		To start [tracking]((https://content.raptorservices.com/help-center/introduction-to-tracking-documentation)) user interactions, the tracking script needs to be added to the website’s layout.

	To start [tracking]((https://content.raptorservices.com/help-center/introduction-to-tracking-documentation)) user interactions, the tracking script needs to be added to the website’s layout.
	To start [tracking](https://content.raptorservices.com/help-center/introduction-to-tracking-documentation) user interactions, the tracking script needs to be added to the website’s layout.

Conversation

julitafalcondusza commented Apr 3, 2026

Checklist

Uh oh!

github-actions bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview of modified files

Uh oh!

adriendupuis 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!

Uh oh!

sonarqubecloud bot commented Apr 7, 2026

Quality Gate failed

Uh oh!

github-actions bot commented Apr 7, 2026

code_samples/ change report

Uh oh!

adriendupuis left a comment

Choose a reason for hiding this comment

Uh oh!

adriendupuis Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

adriendupuis Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

adriendupuis Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Apr 3, 2026 •

edited

Loading