From ee88b9421455ff5ded10085a9bde391ff62bc34f Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 13 Apr 2026 10:30:28 +0200 Subject: [PATCH 01/10] EventMapper.php: Format --- code_samples/recommendations/EventMapper.php | 3 +++ 1 file changed, 3 insertions(+) diff --git a/code_samples/recommendations/EventMapper.php b/code_samples/recommendations/EventMapper.php index b89ec50fc4..0716954234 100644 --- a/code_samples/recommendations/EventMapper.php +++ b/code_samples/recommendations/EventMapper.php @@ -1,4 +1,7 @@ Date: Mon, 13 Apr 2026 10:31:17 +0200 Subject: [PATCH 02/10] EventData.php: Wrap into a class Should fix PhpStan errors "Variable $product might not be defined." --- code_samples/recommendations/EventData.php | 31 ++++++++++++++----- .../raptor_integration/tracking_php_api.md | 4 ++- 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/code_samples/recommendations/EventData.php b/code_samples/recommendations/EventData.php index aa50de626c..5ea0fce894 100644 --- a/code_samples/recommendations/EventData.php +++ b/code_samples/recommendations/EventData.php @@ -1,12 +1,27 @@ getCode(), - productName: $product->getName(), - categoryPath: '25#Electronics;26#Smartphones', // Build manually - currency: 'USD', - itemPrice: '999.99' -); + public function dispatchVisitEvent(ProductInterface $product): void + { + $eventData = new VisitEventData( + productCode: $product->getCode(), + productName: $product->getName(), + categoryPath: '25#Electronics;26#Smartphones', // Build manually + currency: 'USD', + itemPrice: '999.99' + ); -$this->trackingDispatcher->dispatch($eventData); + $this->trackingDispatcher->dispatch($eventData); + } +} diff --git a/docs/recommendations/raptor_integration/tracking_php_api.md b/docs/recommendations/raptor_integration/tracking_php_api.md index 7a07cefcf0..2f93cfac48 100644 --- a/docs/recommendations/raptor_integration/tracking_php_api.md +++ b/docs/recommendations/raptor_integration/tracking_php_api.md @@ -28,7 +28,9 @@ It enables you to define custom event parameters, track specific user interactio Check the following example: ``` php -[[= include_file('code_samples/recommendations/EventData.php') =]] +[[= include_file('code_samples/recommendations/EventData.php', 4, 6) =]]// … + +[[= include_file('code_samples/recommendations/EventData.php', 16, 25, remove_indent=True) =]] ``` `categoryPath` parameter sets the category path for recommendations and needs to be composed manually following the specified format and rules: From 1413a1674344f68ab0ab8d6dd705149b0f0268fe Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 13 Apr 2026 10:35:52 +0200 Subject: [PATCH 03/10] EventData.php: ProductInterface; Should fix PhpStan error "invalid type App\Tracking\ProductInterface" --- code_samples/recommendations/EventData.php | 1 + 1 file changed, 1 insertion(+) diff --git a/code_samples/recommendations/EventData.php b/code_samples/recommendations/EventData.php index 5ea0fce894..622d1a8a12 100644 --- a/code_samples/recommendations/EventData.php +++ b/code_samples/recommendations/EventData.php @@ -4,6 +4,7 @@ use Ibexa\Contracts\ConnectorRaptor\Tracking\Event\VisitEventData; use Ibexa\Contracts\ConnectorRaptor\Tracking\ServerSideTrackingDispatcherInterface; +use Ibexa\Contracts\ProductCatalog\Values\ProductInterface; class TrackingEventDispatchingExample { From 975a1e725acc40b6300a0759616770705e8c937d Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 13 Apr 2026 10:39:41 +0200 Subject: [PATCH 04/10] Event*.php: Format --- code_samples/recommendations/EventMapper.php | 2 +- code_samples/recommendations/EventSubscriber.php | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/code_samples/recommendations/EventMapper.php b/code_samples/recommendations/EventMapper.php index 0716954234..df39c9da5e 100644 --- a/code_samples/recommendations/EventMapper.php +++ b/code_samples/recommendations/EventMapper.php @@ -11,7 +11,7 @@ class EventMapper { public function __construct( private readonly EventMapperInterface $eventMapper, - private ServerSideTrackingDispatcherInterface $trackingDispatcher, + private readonly ServerSideTrackingDispatcherInterface $trackingDispatcher, ) { } diff --git a/code_samples/recommendations/EventSubscriber.php b/code_samples/recommendations/EventSubscriber.php index 3144d4fd84..175784efc4 100644 --- a/code_samples/recommendations/EventSubscriber.php +++ b/code_samples/recommendations/EventSubscriber.php @@ -1,4 +1,7 @@ Date: Mon, 13 Apr 2026 10:43:00 +0200 Subject: [PATCH 05/10] Event*.php: Format --- code_samples/recommendations/EventData.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code_samples/recommendations/EventData.php b/code_samples/recommendations/EventData.php index 622d1a8a12..4825ed6114 100644 --- a/code_samples/recommendations/EventData.php +++ b/code_samples/recommendations/EventData.php @@ -6,10 +6,10 @@ use Ibexa\Contracts\ConnectorRaptor\Tracking\ServerSideTrackingDispatcherInterface; use Ibexa\Contracts\ProductCatalog\Values\ProductInterface; -class TrackingEventDispatchingExample +class EventData { public function __construct( - private ServerSideTrackingDispatcherInterface $trackingDispatcher, + private readonly ServerSideTrackingDispatcherInterface $trackingDispatcher, ) { } From ee41423a4b1864bd95ab408a5bfabe1244427f59 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 13 Apr 2026 12:28:14 +0200 Subject: [PATCH 06/10] tracking_php_api.md: Add intro, detail mapping --- code_samples/recommendations/EventMapper.php | 11 +- ...ConnectorRaptor-Tracking-EventContext.html | 645 ++++++++++++++++++ ...ServerSideTrackingDispatcherInterface.html | 379 ++++++++++ .../raptor_integration/tracking_php_api.md | 32 +- 4 files changed, 1057 insertions(+), 10 deletions(-) create mode 100644 docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventContext.html create mode 100644 docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-ServerSideTrackingDispatcherInterface.html diff --git a/code_samples/recommendations/EventMapper.php b/code_samples/recommendations/EventMapper.php index df39c9da5e..e48d166850 100644 --- a/code_samples/recommendations/EventMapper.php +++ b/code_samples/recommendations/EventMapper.php @@ -2,6 +2,7 @@ namespace App\Tracking; +use Ibexa\Contracts\ConnectorRaptor\Tracking\EventContext; use Ibexa\Contracts\ConnectorRaptor\Tracking\EventMapperInterface; use Ibexa\Contracts\ConnectorRaptor\Tracking\EventType; use Ibexa\Contracts\ConnectorRaptor\Tracking\ServerSideTrackingDispatcherInterface; @@ -15,10 +16,14 @@ public function __construct( ) { } - public function trackProductView(ProductInterface $product, string $url): void + public function trackProductView(ProductInterface $product): void { - // Map product to VisitEventData automatically - $eventData = $this->eventMapper->map(EventType::VISIT, $product); + // Map product to BuyEventData automatically + $eventData = $this->eventMapper->map(EventType::BUY, $product, [ + EventContext::SUBTOTAL => '200', + EventContext::CURRENCY => 'EUR', + EventContext::QUANTITY => '2', + ]); // Send tracking event $this->trackingDispatcher->dispatch($eventData); diff --git a/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventContext.html b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventContext.html new file mode 100644 index 0000000000..b3858c4e7f --- /dev/null +++ b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventContext.html @@ -0,0 +1,645 @@ + + + + + EventContext | PHP API Reference (Ibexa Documentation) + + + + + + + + + + + + + + + + +
Copied!
+ + + +
+ +
+ +
+
+
+ + + + + + + + +
+
+
+ + + +
+
+ + +
+
+

+ EventContext

+ +
+ EventContext.php + : + 14 + +
+
Read-only
+
Final
+ + + +
+

Context keys for tracking events.

+ + + + + + + + + + + + +

+ Constants +

+
+

+ publicBASKET_CONTENT +

+
+ EventContext.php + : + 22 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed BASKET_CONTENT = 'basketContent'
+
+
+
+ + +
+

+ publicBASKET_ID +

+
+ EventContext.php + : + 24 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed BASKET_ID = 'basketId'
+
+
+
+ + +
+

+ publicCATEGORY_IDENTIFIER +

+
+ EventContext.php + : + 32 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed CATEGORY_IDENTIFIER = 'categoryIdentifier'
+
+
+
+ + +
+

+ publicCURRENCY +

+
+ EventContext.php + : + 20 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed CURRENCY = 'currency'
+
+
+
+ + +
+

+ publicMODULE_NAME +

+
+ EventContext.php + : + 26 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed MODULE_NAME = 'moduleName'
+
+
+
+ + +
+

+ publicQUANTITY +

+
+ EventContext.php + : + 16 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed QUANTITY = 'quantity'
+
+
+
+ + +
+

+ publicREDIRECT_URL +

+
+ EventContext.php + : + 28 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed REDIRECT_URL = 'redirectUrl'
+
+
+
+ + +
+

+ publicSUBTOTAL +

+
+ EventContext.php + : + 18 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed SUBTOTAL = 'subtotal'
+
+
+
+ + +
+

+ publicWEBSITE_ID +

+
+ EventContext.php + : + 30 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public mixed WEBSITE_ID = 'websiteId'
+
+
+
+ + + + +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + diff --git a/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-ServerSideTrackingDispatcherInterface.html b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-ServerSideTrackingDispatcherInterface.html new file mode 100644 index 0000000000..3e6efd311c --- /dev/null +++ b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-ServerSideTrackingDispatcherInterface.html @@ -0,0 +1,379 @@ + + + + + ServerSideTrackingDispatcherInterface | PHP API Reference (Ibexa Documentation) + + + + + + + + + + + + + + + + +
Copied!
+ + + +
+ +
+ +
+
+
+ + + + + + + + +
+
+
+ + + +
+
+ + +
+
+

+ ServerSideTrackingDispatcherInterface

+ +
+ ServerSideTrackingDispatcherInterface.php + : + 16 + +
+
Interface
+ +
+

Dispatches server-side tracking events asynchronously via message queue.

+ + + + + + + + + + + + + +

+ Methods +

+ +
+

+ publicdispatch() + +

+
+ ServerSideTrackingDispatcherInterface.php + : + 21 + +
+
+

Dispatches tracking event for asynchronous processing.

+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public dispatch(EventDataInterface $eventData) : string
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $eventData + + EventDataInterface + + - + + - +
+

Return values

+

string

+ + +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + diff --git a/docs/recommendations/raptor_integration/tracking_php_api.md b/docs/recommendations/raptor_integration/tracking_php_api.md index 2f93cfac48..8bcd3a1681 100644 --- a/docs/recommendations/raptor_integration/tracking_php_api.md +++ b/docs/recommendations/raptor_integration/tracking_php_api.md @@ -9,15 +9,33 @@ You can interact directly with the [Raptor connector](raptor_connector.md)'s ser ## Advanced usage – direct interaction with the service +The [`ServerSideTrackingDispatcherInterface::dispatch()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-ServerSideTrackingDispatcherInterface.html#method_dispatch) method allows to send tracking data fom the server side. +It can be used in controllers, event subscribers, or any other part of the application. +This method receives an [`EventDataInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-Event-EventDataInterface.html). +For more information, see available events in the [tracking event namespace](/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html). + ### Mapping event data -The recommended method, providing full control over event tracking, is [`EventMapperInterface::map()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventMapperInterface.html#method_map) method. -It allows you to interact directly with the service, supporting advanced use cases not covered by default implementation. +The recommended method is [`EventMapperInterface::map()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventMapperInterface.html#method_map) method. +This method receives an [`EventType`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventType.html#cases) case, a data depending on the event type, +and a context's associative array using [`EventContext`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventContext.html) constants as keys. + +For more information, see the same arguments of the Twig function [`ibexa_tracking_track_event`](recommendations_twig_functions.md#ibexa_tracking_track_event-function). + +| Event type | Data class | Context keys | +|:---------------------------|:------------------------|:-------------------------------------------------------------------------------------------------------------------------| +| `EventType::VISIT` | `ProductInterface` | (optional) `EventContext::WEBSITE_ID` | +| `EventType::CONTENT_VISIT` | `Content` | (optional) `EventContext::WEBSITE_ID` | +| `EventType::BUY` | `ProductInterface` | `EventContext::SUBTOTAL`,
`EventContext::CURRENCY`,
`EventContext::QUANTITY`,
(optional) `EventContext::WEBSITE_ID` | +| `EventType::BASKET` | `ProductInterface` | `EventContext::BASKET_CONTENT`,
`EventContext::BASKET_ID`,
(optional) `EventContext::QUANTITY`,
(optional) `EventContext::WEBSITE_ID` | +| `EventType::ITEM_CLICK` | `string` (product code) | `EventContext::MODULE_NAME`,
`EventContext::REDIRECT_URL` | Check the following example: ``` php -[[= include_file('code_samples/recommendations/EventMapper.php') =]] +[[= include_file('code_samples/recommendations/EventMapper.php', 4, 8) =]]//… + +[[= include_file('code_samples/recommendations/EventMapper.php', 20, 29, remove_indent=True) =]] ``` ### Manual `EventData` creation @@ -30,7 +48,7 @@ Check the following example: ``` php [[= include_file('code_samples/recommendations/EventData.php', 4, 6) =]]// … -[[= include_file('code_samples/recommendations/EventData.php', 16, 25, remove_indent=True) =]] +[[= include_file('code_samples/recommendations/EventData.php', 17, 26, remove_indent=True) =]] ``` `categoryPath` parameter sets the category path for recommendations and needs to be composed manually following the specified format and rules: @@ -39,16 +57,16 @@ Check the following example: - if `CategoryName` is missing, repeat the ID, for example, `25#25;26#26` - if `CategoryId` is missing, use the `CategoryName`, for example, `Electronics;Smartphones` -For more information, see available events in the [tracking event namespace](/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html) +For more information, see available events in the [tracking event namespace](/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html). ### Example - event subscriber -If you need to track [events](../../api/event_reference/event_reference.md) automatically based on application events, you can use Event Subscriber. +If you need to track [events](event_reference.md) automatically based on application events, you can use Event Subscriber. It reacts to specific events in the application and triggers tracking logic without the need to add it manually in templates. ``` php [[= include_file('code_samples/recommendations/EventSubscriber.php') =]] ``` -You can also use [[= product_name =]] events, for example `CreateOrderEvent` from [Order management events](../../api/event_reference/order_management_events.md). +You can also use [[= product_name =]] events, for example `CreateOrderEvent` from [Order management events](order_management_events.md). For more information, see [Event reference](event_reference.md). From 04b3d39963b9b2b6182261148e8ae7897d795f3e Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 13 Apr 2026 12:34:25 +0200 Subject: [PATCH 07/10] Missing PHP API pages --- ...tor-Tracking-Event-EventDataInterface.html | 441 +++++++++++++++ ...ts-ConnectorRaptor-Tracking-EventType.html | 508 ++++++++++++++++++ 2 files changed, 949 insertions(+) create mode 100644 docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-Event-EventDataInterface.html create mode 100644 docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventType.html diff --git a/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-Event-EventDataInterface.html b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-Event-EventDataInterface.html new file mode 100644 index 0000000000..4557eb6f90 --- /dev/null +++ b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-Event-EventDataInterface.html @@ -0,0 +1,441 @@ + + + + + EventDataInterface | PHP API Reference (Ibexa Documentation) + + + + + + + + + + + + + + + + +
Copied!
+ + + +
+ +
+ +
+
+
+ + + + + + + + +
+
+
+ + + +
+
+ + +
+
+

+ EventDataInterface

+ +
+ EventDataInterface.php + : + 16 + +
+
Interface
+ +
+

Base interface for tracking event data.

+ + + + + + + + + + + + + +

+ Methods +

+ +
+

+ publicgetEventType() + +

+
+ EventDataInterface.php + : + 18 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getEventType() : EventType
+
+
+
+
+
+

Return values

+

EventType

+ + +
+

+ publicgetTemplateHint() + +

+
+ EventDataInterface.php + : + 30 + +
+
+

Returns optional template hint for special rendering needs.

+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getTemplateHint() : string|null
+
+
+
+
+
+

Return values

+

string|null

+ + +
+

+ publictoArray() + +

+
+ EventDataInterface.php + : + 25 + +
+
+

Returns Raptor tracking parameters.

+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public toArray() : array<string, mixed>
+
+
+
+
+
+

Return values

+

array<string, mixed>

+ + +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + diff --git a/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventType.html b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventType.html new file mode 100644 index 0000000000..333665d154 --- /dev/null +++ b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventType.html @@ -0,0 +1,508 @@ + + + + + EventType | PHP API Reference (Ibexa Documentation) + + + + + + + + + + + + + + + + +
Copied!
+ + + +
+ +
+ +
+
+
+ + + + + + + + +
+
+
+ + + +
+
+ + +
+
+

+ EventType +

+ +
+ EventType.php + : + 14 + +
+
+ Enum: string +
+
+

Defines supported Raptor tracking event types.

+ + + + + + + + + + + +
+

+ Cases + + +

+
+
+

+ VISIT +

+
+ EventType.php + : + 16 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
string VISIT = 'visit'
+
+
+
+ + +
+
+
+

+ CONTENT_VISIT +

+
+ EventType.php + : + 17 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
string CONTENT_VISIT = 'contentvisit'
+
+
+
+ + +
+
+
+

+ BUY +

+
+ EventType.php + : + 18 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
string BUY = 'buy'
+
+
+
+ + +
+
+
+

+ BASKET +

+
+ EventType.php + : + 19 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
string BASKET = 'basket'
+
+
+
+ + +
+
+
+

+ ITEM_CLICK +

+
+ EventType.php + : + 20 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
string ITEM_CLICK = 'itemclick'
+
+
+
+ + +
+
+ +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + From 0f18cfd2f74a7a361d2c15cad31f1c88db5687ee Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 13 Apr 2026 13:09:26 +0200 Subject: [PATCH 08/10] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tomasz Dąbrowski <64841871+dabrt@users.noreply.github.com> --- .../raptor_integration/tracking_php_api.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/recommendations/raptor_integration/tracking_php_api.md b/docs/recommendations/raptor_integration/tracking_php_api.md index 8bcd3a1681..9054950d1f 100644 --- a/docs/recommendations/raptor_integration/tracking_php_api.md +++ b/docs/recommendations/raptor_integration/tracking_php_api.md @@ -9,16 +9,15 @@ You can interact directly with the [Raptor connector](raptor_connector.md)'s ser ## Advanced usage – direct interaction with the service -The [`ServerSideTrackingDispatcherInterface::dispatch()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-ServerSideTrackingDispatcherInterface.html#method_dispatch) method allows to send tracking data fom the server side. +The [`ServerSideTrackingDispatcherInterface::dispatch()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-ServerSideTrackingDispatcherInterface.html#method_dispatch) method allows to send tracking data from the server side. It can be used in controllers, event subscribers, or any other part of the application. This method receives an [`EventDataInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-Event-EventDataInterface.html). -For more information, see available events in the [tracking event namespace](/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html). +For more information, see the available events in the [tracking event namespace](/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html). ### Mapping event data -The recommended method is [`EventMapperInterface::map()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventMapperInterface.html#method_map) method. -This method receives an [`EventType`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventType.html#cases) case, a data depending on the event type, -and a context's associative array using [`EventContext`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventContext.html) constants as keys. +The recommended method is [`EventMapperInterface::map()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventMapperInterface.html#method_map). +This method receives an [`EventType`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventType.html#cases) case, a data depending on the event type, and a context's associative array that uses [`EventContext`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventContext.html) constants as keys. For more information, see the same arguments of the Twig function [`ibexa_tracking_track_event`](recommendations_twig_functions.md#ibexa_tracking_track_event-function). @@ -57,11 +56,11 @@ Check the following example: - if `CategoryName` is missing, repeat the ID, for example, `25#25;26#26` - if `CategoryId` is missing, use the `CategoryName`, for example, `Electronics;Smartphones` -For more information, see available events in the [tracking event namespace](/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html). +For more information, see the available events in the [tracking event namespace](/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html). ### Example - event subscriber -If you need to track [events](event_reference.md) automatically based on application events, you can use Event Subscriber. +If you need to track [events](event_reference.md) automatically based on application events, you can use an event subscriber. It reacts to specific events in the application and triggers tracking logic without the need to add it manually in templates. ``` php From b4b744a7d92bf15c0b60d46290bab9873f182bc5 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 13 Apr 2026 15:00:09 +0200 Subject: [PATCH 09/10] tracking_php_api.md: EventContext::CATEGORY_IDENTIFIER --- code_samples/recommendations/EventMapper.php | 8 +++----- .../raptor_integration/tracking_php_api.md | 16 ++++++++-------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/code_samples/recommendations/EventMapper.php b/code_samples/recommendations/EventMapper.php index e48d166850..cf0bd3bd8e 100644 --- a/code_samples/recommendations/EventMapper.php +++ b/code_samples/recommendations/EventMapper.php @@ -18,11 +18,9 @@ public function __construct( public function trackProductView(ProductInterface $product): void { - // Map product to BuyEventData automatically - $eventData = $this->eventMapper->map(EventType::BUY, $product, [ - EventContext::SUBTOTAL => '200', - EventContext::CURRENCY => 'EUR', - EventContext::QUANTITY => '2', + // Map product to VisitEventData automatically, override its category + $eventData = $this->eventMapper->map(EventType::VISIT, $product, [ + EventContext::CATEGORY_IDENTIFIER => 'electronics', ]); // Send tracking event diff --git a/docs/recommendations/raptor_integration/tracking_php_api.md b/docs/recommendations/raptor_integration/tracking_php_api.md index 9054950d1f..13e5e6884f 100644 --- a/docs/recommendations/raptor_integration/tracking_php_api.md +++ b/docs/recommendations/raptor_integration/tracking_php_api.md @@ -21,20 +21,20 @@ This method receives an [`EventType`](/api/php_api/php_api_reference/classes/Ibe For more information, see the same arguments of the Twig function [`ibexa_tracking_track_event`](recommendations_twig_functions.md#ibexa_tracking_track_event-function). -| Event type | Data class | Context keys | -|:---------------------------|:------------------------|:-------------------------------------------------------------------------------------------------------------------------| -| `EventType::VISIT` | `ProductInterface` | (optional) `EventContext::WEBSITE_ID` | -| `EventType::CONTENT_VISIT` | `Content` | (optional) `EventContext::WEBSITE_ID` | -| `EventType::BUY` | `ProductInterface` | `EventContext::SUBTOTAL`,
`EventContext::CURRENCY`,
`EventContext::QUANTITY`,
(optional) `EventContext::WEBSITE_ID` | -| `EventType::BASKET` | `ProductInterface` | `EventContext::BASKET_CONTENT`,
`EventContext::BASKET_ID`,
(optional) `EventContext::QUANTITY`,
(optional) `EventContext::WEBSITE_ID` | -| `EventType::ITEM_CLICK` | `string` (product code) | `EventContext::MODULE_NAME`,
`EventContext::REDIRECT_URL` | +| Event type | Data class | Context keys | +|:---------------------------|:------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------| +| `EventType::VISIT` | `ProductInterface` | (optional) `EventContext::CATEGORY_IDENTIFIER`,
(optional) `EventContext::WEBSITE_ID` | +| `EventType::CONTENT_VISIT` | `Content` | (optional) `EventContext::WEBSITE_ID` | +| `EventType::BUY` | `ProductInterface` | `EventContext::SUBTOTAL`,
`EventContext::CURRENCY`,
`EventContext::QUANTITY`,
(optional) `EventContext::CATEGORY_IDENTIFIER`,
(optional) `EventContext::WEBSITE_ID` | +| `EventType::BASKET` | `ProductInterface` | `EventContext::BASKET_CONTENT`,
`EventContext::BASKET_ID`,
(optional) `EventContext::CATEGORY_IDENTIFIER`,
(optional) `EventContext::QUANTITY`,
(optional) `EventContext::WEBSITE_ID` | +| `EventType::ITEM_CLICK` | `string` (product code) | `EventContext::MODULE_NAME`,
`EventContext::REDIRECT_URL` | Check the following example: ``` php [[= include_file('code_samples/recommendations/EventMapper.php', 4, 8) =]]//… -[[= include_file('code_samples/recommendations/EventMapper.php', 20, 29, remove_indent=True) =]] +[[= include_file('code_samples/recommendations/EventMapper.php', 20, 27, remove_indent=True) =]] ``` ### Manual `EventData` creation From 70cc0a93f02b836f42d1df73eef0fc7d158bfa76 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 13 Apr 2026 15:46:25 +0200 Subject: [PATCH 10/10] tracking_php_api.md: caution about buy event --- .../raptor_integration/tracking_php_api.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/recommendations/raptor_integration/tracking_php_api.md b/docs/recommendations/raptor_integration/tracking_php_api.md index 13e5e6884f..e90093a6cd 100644 --- a/docs/recommendations/raptor_integration/tracking_php_api.md +++ b/docs/recommendations/raptor_integration/tracking_php_api.md @@ -29,6 +29,11 @@ For more information, see the same arguments of the Twig function [`ibexa_tracki | `EventType::BASKET` | `ProductInterface` | `EventContext::BASKET_CONTENT`,
`EventContext::BASKET_ID`,
(optional) `EventContext::CATEGORY_IDENTIFIER`,
(optional) `EventContext::QUANTITY`,
(optional) `EventContext::WEBSITE_ID` | | `EventType::ITEM_CLICK` | `string` (product code) | `EventContext::MODULE_NAME`,
`EventContext::REDIRECT_URL` | +!!! caution + + The `EventType::BUY` type and the `BuyEventData` class aren't production-ready yet, they're missing the [`BrandId` parameter (P8)](https://content.raptorservices.com/help-center/tracking-events-for-recommendation), and their usage may change in the future. + + Check the following example: ``` php @@ -58,6 +63,10 @@ Check the following example: For more information, see the available events in the [tracking event namespace](/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html). +!!! caution + + The `BuyEventData` class isn't production-ready yet, it's missing the [`BrandId` parameter (P8)](https://content.raptorservices.com/help-center/tracking-events-for-recommendation), and its usage may change in the future. + ### Example - event subscriber If you need to track [events](event_reference.md) automatically based on application events, you can use an event subscriber.