diff --git a/code_samples/recommendations/EventMapper.php b/code_samples/recommendations/EventMapper.php index df39c9da5e..cf0bd3bd8e 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,12 @@ 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 VisitEventData automatically, override its category + $eventData = $this->eventMapper->map(EventType::VISIT, $product, [ + EventContext::CATEGORY_IDENTIFIER => 'electronics', + ]); // Send tracking event $this->trackingDispatcher->dispatch($eventData); 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-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-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'
+
+
+
+ + +
+
+ +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + 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 5bdc261705..e90093a6cd 100644 --- a/docs/recommendations/raptor_integration/tracking_php_api.md +++ b/docs/recommendations/raptor_integration/tracking_php_api.md @@ -9,15 +9,37 @@ 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 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 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, 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). +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). + +| 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` | + +!!! 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 -[[= include_file('code_samples/recommendations/EventMapper.php') =]] +[[= include_file('code_samples/recommendations/EventMapper.php', 4, 8) =]]//… + +[[= include_file('code_samples/recommendations/EventMapper.php', 20, 27, remove_indent=True) =]] ``` ### Manual `EventData` creation @@ -39,16 +61,20 @@ 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). + +!!! 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](../../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 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 [[= 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).