diff --git a/code_samples/recommendations/EventData.php b/code_samples/recommendations/EventData.php new file mode 100644 index 0000000000..aa50de626c --- /dev/null +++ b/code_samples/recommendations/EventData.php @@ -0,0 +1,12 @@ +getCode(), + productName: $product->getName(), + categoryPath: '25#Electronics;26#Smartphones', // Build manually + currency: 'USD', + itemPrice: '999.99' +); + +$this->trackingDispatcher->dispatch($eventData); diff --git a/code_samples/recommendations/EventMapper.php b/code_samples/recommendations/EventMapper.php new file mode 100644 index 0000000000..b89ec50fc4 --- /dev/null +++ b/code_samples/recommendations/EventMapper.php @@ -0,0 +1,23 @@ +eventMapper->map(EventType::VISIT, $product); + + // Send tracking event + $this->trackingDispatcher->dispatch($eventData); + } +} diff --git a/code_samples/recommendations/EventSubscriber.php b/code_samples/recommendations/EventSubscriber.php new file mode 100644 index 0000000000..3144d4fd84 --- /dev/null +++ b/code_samples/recommendations/EventSubscriber.php @@ -0,0 +1,39 @@ + ['onResponse', -10]]; + } + + public function onResponse(ResponseEvent $event): void + { + if (!$event->isMainRequest()) { + return; + } + + $request = $event->getRequest(); + + // Example: track only if request has specific attribute + $product = $request->attributes->get('product'); + if (null === $product) { + return; + } + + $eventData = $this->eventMapper->map(EventType::VISIT, $product); + $this->trackingDispatcher->dispatch($eventData); + } +} diff --git a/code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml b/code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml new file mode 100644 index 0000000000..61c90252b1 --- /dev/null +++ b/code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml @@ -0,0 +1,16 @@ +ibexa: + system: + : + connector_raptor: + enabled: true + customer_id: ~ # Required + tracking_type: client # One of: "client" or "server" + + # Raptor Recommendations API key + recommendations_api_key: ~ # Required + + # Raptor Recommendations API URL, optional, set by default + recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%' +ibexa_connector_raptor: + # When enabled, tracking exceptions are thrown instead of being silently handled + strict_exceptions: true diff --git a/code_samples/recommendations/custom_integration.html b/code_samples/recommendations/custom_integration.html new file mode 100644 index 0000000000..339dcd8be7 --- /dev/null +++ b/code_samples/recommendations/custom_integration.html @@ -0,0 +1,31 @@ +``` html + + + + + +``` diff --git a/code_samples/recommendations/events/basket_event.html.twig b/code_samples/recommendations/events/basket_event.html.twig new file mode 100644 index 0000000000..11df19b560 --- /dev/null +++ b/code_samples/recommendations/events/basket_event.html.twig @@ -0,0 +1,25 @@ +{# templates/cart/add_confirmation.html.twig #} +{% extends 'base.html.twig' %} + +{% block content %} +
+

Product "{{ product.name }}" has been added to your cart!

+

Quantity: {{ addedQuantity }}

+
+ + {# Build basket content string: "product-code:quantity;product-code:quantity" #} + {% set basketContent = [] %} + {% for entry in cart.entries %} + {% set basketContent = basketContent|merge([entry.product.code ~ ':' ~ entry.quantity]) %} + {% endfor %} + {# Track basket addition #} + {% set basketContext = { + 'basketContent': basketContent|join(';'), + 'basketId': cart.id, + 'quantity': addedQuantity + } %} + + {{ ibexa_tracking_track_event('basket', product, basketContext) }} + + View Cart +{% endblock %} diff --git a/code_samples/recommendations/events/content_visit_event.html.twig b/code_samples/recommendations/events/content_visit_event.html.twig new file mode 100644 index 0000000000..8723147fe6 --- /dev/null +++ b/code_samples/recommendations/events/content_visit_event.html.twig @@ -0,0 +1,7 @@ +{# templates/bundles/IbexaCoreBundle/default/content/full.html.twig #} +{% extends '@!IbexaCore/default/content/full.html.twig' %} + +{% block content %} + {{ parent() }} + {{ ibexa_tracking_track_event('contentvisit', content) }} +{% endblock %} diff --git a/code_samples/recommendations/events/itemclicked_event.html.twig b/code_samples/recommendations/events/itemclicked_event.html.twig new file mode 100644 index 0000000000..fc3cf42dfb --- /dev/null +++ b/code_samples/recommendations/events/itemclicked_event.html.twig @@ -0,0 +1,4 @@ +{{ ibexa_tracking_track_event('itemclick', product.code, { + 'moduleName': 'homepage-recommendations', + 'redirectUrl': path('ibexa.product.view', {'productCode': product.code}) +}) }} diff --git a/code_samples/recommendations/events/product_visit_event.html.twig b/code_samples/recommendations/events/product_visit_event.html.twig new file mode 100644 index 0000000000..be2c149064 --- /dev/null +++ b/code_samples/recommendations/events/product_visit_event.html.twig @@ -0,0 +1,13 @@ +# templates/product/view.html.twig #} +{% extends 'base.html.twig' %} + +{% block content %} +
+

{{ product.name }}

+

{{ product.description }}

+
{{ product.price }}
+
+ + {# Track product visit #} + {{ ibexa_tracking_track_event('visit', product) }} +{% endblock %} diff --git a/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.html.twig b/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.html.twig new file mode 100644 index 0000000000..40eedecb7d --- /dev/null +++ b/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.html.twig @@ -0,0 +1,4 @@ +{% extends '@IbexaConnectorRaptor/themes/standard/ibexa/tracking/script.html.twig' %} +{% block ibexa_tracking_script %} + console.log('My custom tracking script, but relying on loadTracking function.'); +{% endblock %} diff --git a/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.js.twig b/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.js.twig new file mode 100644 index 0000000000..c9f3ecddae --- /dev/null +++ b/code_samples/recommendations/templates/themes/standard/ibexa/tracking/script.js.twig @@ -0,0 +1,5 @@ + diff --git a/code_samples/recommendations/templates/themes/standard/pagelayout.html.twig b/code_samples/recommendations/templates/themes/standard/pagelayout.html.twig new file mode 100644 index 0000000000..33fc86b155 --- /dev/null +++ b/code_samples/recommendations/templates/themes/standard/pagelayout.html.twig @@ -0,0 +1,13 @@ +{# templates/pagelayout.html.twig #} + + + + {# ... other head content ... #} + + {# Initialize Raptor tracking - must be called before any tracking events #} + {{ ibexa_tracking_script() }} + + + {# ... page content ... #} + + diff --git a/code_samples/recommendations/templates/tracking/custom_visit.html.twig b/code_samples/recommendations/templates/tracking/custom_visit.html.twig new file mode 100644 index 0000000000..9d556bdffb --- /dev/null +++ b/code_samples/recommendations/templates/tracking/custom_visit.html.twig @@ -0,0 +1,37 @@ +{{ ibexa_tracking_track_event( + 'visit', + product, + {}, + '@App/tracking/custom_visit.html.twig' +) }} +``` + +{# templates/tracking/custom_visit.html.twig #} + + {# + # Custom visit tracking template + # + # Available variables: + # - parameters: array of Raptor tracking parameters (p1, p2, p3, etc.) + # - debug: boolean flag to enable debug console messages + #} + + diff --git a/composer.json b/composer.json index 1f8cb44b1e..dc30c5c4b2 100644 --- a/composer.json +++ b/composer.json @@ -82,6 +82,7 @@ "ibexa/phpstan": "~5.0.-dev", "deptrac/deptrac": "^3.0", "ibexa/cdp": "~5.0.x-dev", + "ibexa/connector-raptor": "~5.0.x-dev", "ibexa/image-editor": "~5.0.x-dev" }, "scripts": { diff --git a/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Recommendations-RecommendationsServiceInterface.html b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Recommendations-RecommendationsServiceInterface.html new file mode 100644 index 0000000000..acc4c3004e --- /dev/null +++ b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Recommendations-RecommendationsServiceInterface.html @@ -0,0 +1,2722 @@ + + + + + RecommendationsServiceInterface | PHP API Reference (Ibexa Documentation) + + + + + + + + + + + + + + + + +
Copied!
+ + + +
+ +
+ +
+
+
+ + + + + + + + +
+
+
+ + + +
+
+ + +
+
+

+ RecommendationsServiceInterface

+ +
+ RecommendationsServiceInterface.php + : + 18 + +
+
Interface
+ +
+

Service for fetching product and content recommendations from Raptor.

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

+ Methods +

+ +
+

+ publicgetContentBasedOnItemWeb() + +

+
+ RecommendationsServiceInterface.php + : + 60 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getContentBasedOnItemWeb(string $productId[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ContentRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $productId + + string + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ContentRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetContentBasedOnProductCategoryWeb() + +

+
+ RecommendationsServiceInterface.php + : + 71 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getContentBasedOnProductCategoryWeb(string $categoryId[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ContentRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $categoryId + + string + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ContentRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetContentCatalogueRank() + +

+
+ RecommendationsServiceInterface.php + : + 248 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getContentCatalogueRank([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ContentRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ContentRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetItemsBasedOnContentWeb() + +

+
+ RecommendationsServiceInterface.php + : + 93 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getItemsBasedOnContentWeb(string $contentId[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $contentId + + string + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetMerchandisingContentWeb() + +

+
+ RecommendationsServiceInterface.php + : + 216 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getMerchandisingContentWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ContentRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ContentRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetMerchandisingItemsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 206 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getMerchandisingItemsWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetNumOfUsersRightNowWeb() + +

+
+ RecommendationsServiceInterface.php + : + 196 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getNumOfUsersRightNowWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetPIMRelatedItemsForBasketWeb() + +

+
+ RecommendationsServiceInterface.php + : + 237 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getPIMRelatedItemsForBasketWeb(string $productIds[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $productIds + + string + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetPIMRelatedItemsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 226 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getPIMRelatedItemsWeb(string $productId[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $productId + + string + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetPopularBrandsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 166 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getPopularBrandsWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetPopularCategoriesWeb() + +

+
+ RecommendationsServiceInterface.php + : + 176 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getPopularCategoriesWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetPopularContentWeb() + +

+
+ RecommendationsServiceInterface.php + : + 186 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getPopularContentWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ContentRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ContentRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetPopularItemsInCategoryWeb() + +

+
+ RecommendationsServiceInterface.php + : + 37 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getPopularItemsInCategoryWeb(string $categoryId, bool $inStockOnly[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $categoryId + + string + + - + + - +
+ $inStockOnly + + bool + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetPopularItemsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 114 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getPopularItemsWeb(bool $inStockOnly[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $inStockOnly + + bool + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetProductCatalogueRank() + +

+
+ RecommendationsServiceInterface.php + : + 258 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getProductCatalogueRank([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetSimilarContentWeb() + +

+
+ RecommendationsServiceInterface.php + : + 82 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getSimilarContentWeb(string $contentId[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ContentRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $contentId + + string + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ContentRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetSimilarItemsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 25 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getSimilarItemsWeb(string $productId, bool $inStockOnly[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $productId + + string + + - + + - +
+ $inStockOnly + + bool + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetUserContentHistoryWeb() + +

+
+ RecommendationsServiceInterface.php + : + 156 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getUserContentHistoryWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ContentRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ContentRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetUserContentRecommendationsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 104 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getUserContentRecommendationsWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ContentRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ContentRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetUserCrossSellingItemsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 136 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getUserCrossSellingItemsWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetUserItemHistoryWeb() + +

+
+ RecommendationsServiceInterface.php + : + 49 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getUserItemHistoryWeb([bool $inStockOnly = false ][, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $inStockOnly + + bool + + false + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetUserItemRecommendationsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 125 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getUserItemRecommendationsWeb(bool $inStockOnly[, int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $inStockOnly + + bool + + - + + - +
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+

+ publicgetUserLookAlikeItemsWeb() + +

+
+ RecommendationsServiceInterface.php + : + 146 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public getUserLookAlikeItemsWeb([int $numOfItems = 10 ][, array<string, mixed> $options = [] ]) : ProductRecommendations
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $numOfItems + + int + + 10 + + - +
+ $options + + array<string, mixed> + + [] + + - +
+

Return values

+

ProductRecommendations

+ +
+ Tags + + +
+
+
+ Throws +
+
+ RaptorClientExceptionInterface + +
+
+ +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + diff --git a/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventMapperInterface.html b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventMapperInterface.html new file mode 100644 index 0000000000..9d7f16df04 --- /dev/null +++ b/docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Tracking-EventMapperInterface.html @@ -0,0 +1,420 @@ + + + + + EventMapperInterface | PHP API Reference (Ibexa Documentation) + + + + + + + + + + + + + + + + +
Copied!
+ + + +
+ +
+ +
+
+
+ + + + + + + + +
+
+
+ + + +
+
+ + +
+
+

+ EventMapperInterface

+ +
+ EventMapperInterface.php + : + 17 + +
+
Interface
+ +
+

Maps domain objects to tracking event data using registered strategies.

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

+ Methods +

+ +
+

+ publicmap() + +

+
+ EventMapperInterface.php + : + 24 + +
+
+ +
+ + + + + + + +
+
+
+
+ 		+
+ 
public map(EventType $eventType, mixed $data[, array<string, mixed> $context = [] ]) : EventDataInterface
+
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
+ $eventType + + EventType + + - + + - +
+ $data + + mixed + + - + + - +
+ $context + + array<string, mixed> + + [] + + - +
+

Return values

+

EventDataInterface

+ +
+ Tags + + +
+
+
+ Throws +
+
+ InvalidArgumentException + +
+
+ +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + diff --git a/docs/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html b/docs/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html new file mode 100644 index 0000000000..2fefef146f --- /dev/null +++ b/docs/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking-event.html @@ -0,0 +1,325 @@ + + + + + Event | PHP API Reference (Ibexa Documentation) + + + + + + + + + + + + + + +
Copied!
+ + + +
+ +
+ +
+
+
+ + + + + + + + +
+
+
+ + + +
+
+ + +
+
+

+ Event +

+ +
+ + + + +

+ Interfaces, classes, traits, and enums +

+ + +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + diff --git a/docs/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking.html b/docs/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking.html new file mode 100644 index 0000000000..7ff734605e --- /dev/null +++ b/docs/api/php_api/php_api_reference/namespaces/ibexa-contracts-connectorraptor-tracking.html @@ -0,0 +1,355 @@ + + + + + Tracking | PHP API Reference (Ibexa Documentation) + + + + + + + + + + + + + + +
Copied!
+ + + +
+ +
+ +
+
+
+ + + + + + + + +
+
+
+ + + +
+
+ + +
+
+

+ Tracking +

+ +
+ + +

+ Namespaces +

+ + + +

+ Interfaces, classes, traits, and enums +

+ + +
+
+
+ +
+
+
+ +
+
+
+
+
+
+ + + + + + + + + + + diff --git a/docs/api/rest_api/rest_api_authentication.md b/docs/api/rest_api/rest_api_authentication.md index 2a255e5004..37ef0c8c3a 100644 --- a/docs/api/rest_api/rest_api_authentication.md +++ b/docs/api/rest_api/rest_api_authentication.md @@ -276,39 +276,6 @@ See [JWT authentication](development_security.md#jwt-authentication) for configu After you configure JWT authentication for REST, you can get the JWT token through the following request: -=== "XML" - - ``` - POST /user/token/jwt HTTP/1.1 - Host: - Accept: application/vnd.ibexa.api.JWT+xml - Content-Type: application/vnd.ibexa.api.JWTInput+xml - ``` - - Provide the username and password in the request body: - - ```xml - - admin - publish - - ``` - - If credentials are valid, the server response contains a token: - - ```xml - - ``` - - You can then use this token in your request instead of username and password. - - ``` - GET /content/locations/1/5/children - Host: - Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…-QBE4-6eKNjg - Accept: application/vnd.ibexa.api.LocationList+xml - ``` - === "JSON" ``` diff --git a/docs/infrastructure_and_maintenance/security/development_security.md b/docs/infrastructure_and_maintenance/security/development_security.md index ecb2507e0a..cdc7196bcf 100644 --- a/docs/infrastructure_and_maintenance/security/development_security.md +++ b/docs/infrastructure_and_maintenance/security/development_security.md @@ -126,24 +126,29 @@ It's already provided in `config/packages/security.yaml`, you only need to uncom security: firewalls: ibexa_jwt_rest: - request_matcher: Ibexa\Contracts\Rest\Security\AuthorizationHeaderRESTRequestMatcher + request_matcher: Ibexa\Rest\Security\JWTTokenCreationRESTRequestMatcher user_checker: Ibexa\Core\MVC\Symfony\Security\UserChecker - anonymous: ~ - guard: - authenticators: - - lexik_jwt_authentication.jwt_token_authenticator - entry_point: lexik_jwt_authentication.jwt_token_authenticator stateless: true + provider: ibexa + json_login: + check_path: ibexa.rest.create_token + username_path: JWTInput.username + password_path: JWTInput.password + success_handler: lexik_jwt_authentication.handler.authentication_success + failure_handler: lexik_jwt_authentication.handler.authentication_failure + + ibexa_jwt_rest.api: + request_matcher: Ibexa\Rest\Security\AuthorizationHeaderRESTRequestMatcher + user_checker: Ibexa\Core\MVC\Symfony\Security\UserChecker + provider: ibexa + stateless: true + jwt: ~ ibexa_jwt_graphql: request_matcher: Ibexa\GraphQL\Security\NonAdminGraphQLRequestMatcher - user_checker: Ibexa\Core\MVC\Symfony\Security\UserChecker - anonymous: ~ - guard: - authenticators: - - lexik_jwt_authentication.jwt_token_authenticator - entry_point: lexik_jwt_authentication.jwt_token_authenticator + provider: ibexa stateless: true + jwt: ~ ``` Finish the setup by generating a [PEM encoded key pair](https://symfony.com/bundles/LexikJWTAuthenticationBundle/2.x/index.html#generate-the-ssl-keys) by using the command: diff --git a/docs/product_guides/product_guides.md b/docs/product_guides/product_guides.md index 1c2359f5b2..da9b7fcb1d 100644 --- a/docs/product_guides/product_guides.md +++ b/docs/product_guides/product_guides.md @@ -23,4 +23,5 @@ Discover the primary ones with the help of product guides. Condensed content all "commerce/shopping_list/shopping_list_guide", "ibexa_cloud/ibexa_cloud_guide", "cdp/cdp_guide", + "recommendations/raptor_integration/raptor_connector_guide", ], columns=4) =]] diff --git a/docs/recommendations/raptor_integration/connector_installation_configuration.md b/docs/recommendations/raptor_integration/connector_installation_configuration.md new file mode 100644 index 0000000000..c13d471c43 --- /dev/null +++ b/docs/recommendations/raptor_integration/connector_installation_configuration.md @@ -0,0 +1,78 @@ +--- +description: To configure the Raptor integration, follow the step-by-step procedure described below. +month_change: true +--- + +# Configuration procedure + +To configure the Raptor integration, follow a step-by-step procedure that allows you to activate the Raptor connector. + +## Install Raptor connector + +Before you can proceed to configuring the integration with Raptor, install the [Raptor](https://www.raptorservices.com/) connector. +To do it, run the following command: + +``` bash +composer require ibexa/connector-raptor +``` + +!!! note + + The [Ibexa Messenger](background_tasks.md) package is installed automatically as a dependency, but must be configured to enable server-side tracking. + See the Ibexa Messenger documentation for [configuration](background_tasks.md#configure-package) details. + +## SiteAccess-aware configuration + +To configure the Raptor connector, use the `ibexa.system..connector_raptor` configuration key in the `config/packages/ibexa_connector_raptor.yaml` file: + +``` yaml +[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml', 0, 13) =]] +``` + +- `enabled` - enables or disables the connector for a given scope, default value: `true`. If set to `false`, no tracking or recommendation requests are executed. +- `customer_id` - an identifier used to authenticate requests to the recommendation engine. You can find this value as ["Account number"](connector_installation_configuration.md#customer-id) in Raptor Control Panel. +- `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 [Twig functions](recommendations_twig_functions.md) and included in 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. +- `recommendations_api_key` - an API key used to authenticate requests to the Recommendations API. This key allows the connector to retrieve personalized recommendations from the recommendation engine. You can find this value as ["API key"](connector_installation_configuration.md#recommendations-api-key) in Raptor Control Panel. +- `recommendations_api_url` (optional) - overrides the default Raptor address, do not set unless a custom endpoint is required. + +By default, `tracking_type` is set to `client` as client-side tracking is the standard Raptor mode. +To understand the differences between client and server tracking types, including their advantages and disadvantages, refer to the [Raptor documentation](https://content.raptorservices.com/help-center/client-side-vs.-server-side-tracking). + +!!! note + + Only one tracking mode can be enabled at a time. + Client-side and server-side tracking cannot be used together. + +### Customer ID + +To find the value for the `customer_id` identifier, log in to Raptor Control Panel, and look for "Account number": + +A. In the top-left corner, above the account name, you can find the account number for the currently active account. +B. Click the arrow icon in the top-left corner to expand the window. There you can see a list of all your accounts, with their numbers shown in the “Account number” column on the right. This way, if you have multiple accounts, you can locate and copy the number of any of your accounts, not just the active one. + +![Account number](account_number.png) + +### Recommendations API key + +To find the value for the `recommendations_api_key`, log in to Raptor Control Panel, and look for "API key". +To do it, in the left panel, open the **Recommendations** section, and select **Website**. +Next, click on the Web module you’re interested in. +In the top-right corner, click the three-dot icon and select **API information**. +A new window appears, where you can find the "API key" value. +Click **Show API information** and copy the value. + +![API key](api_key.png) + +## Global configuration (non-SiteAccess-aware) + +The following settings are global and apply to the entire application (they are not scoped per SiteAccess): + +- `strict_exceptions` – when enabled, tracking exceptions are thrown instead of being silently handled. Default value: `%kernel.debug%`. + +This value can be overridden in `config/packages/ibexa_connector_raptor.yaml` file, for example: + +``` yaml hl_lines="14-17" +[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml') =]] +``` diff --git a/docs/recommendations/raptor_integration/custom_recommendation_rendering.md b/docs/recommendations/raptor_integration/custom_recommendation_rendering.md new file mode 100644 index 0000000000..532f3a7aac --- /dev/null +++ b/docs/recommendations/raptor_integration/custom_recommendation_rendering.md @@ -0,0 +1,78 @@ +--- +description: Use existing controllers to render recommendations outside the Page Builder. +month_change: true +--- + +# Custom recommendation rendering + +You can use existing controllers to render [recommendations](recommendation_blocks.md) outside the Page Builder. +The controllers responsible for rendering block recommendations on the front-end are independent and can be used to render recommendations for specific strategies. + +Each controller can be used to retrieve and display recommendations within a Twig template as follows: + +``` html+twig +{{ render(controller('', { + 'limit': limit, + 'template': '@ibexadesign/.html.twig', + '': parameter_value +})) }} +``` + +The controllers are placed in the `Ibexa\Bundle\ConnectorRaptor\Controller\Block` namespace. + +Each controller always requires these two parameters: + +- **limit** – the number of recommendations to render +- **template** – the path to the template + +Any other required parameters are specific to each controller and are detailed in the **Parameters** column of the table below: + +|Block name| Controller |Parameters|Recommendation item type| +|----------|---------------------------------------------------------------------------------------------|----------|------------------------| +|[Content that have been seen along with the item category]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#content-that-have-been-seen-along-with-the-item-category-block)| `ContentBasedOnProductCategoryBlockController`
`::showAction()` |`categoryId` (integer),
`limit` (integer),
`template` (string)|Content| +|[Most popular content]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-content-block)| `PopularContentBlockController`
`::showAction()` |`limit` (integer),
`template` (string)|Content| +|[Most popular products]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-products-block)| `PopularItemsBlockController`
`::showAction()` |`showInStock` (boolean),
`limit` (integer),
`template` (string)|Product| +|[Most popular products in category]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-products-in-category-block)| `PopularItemsInCategoryBlockController`
`::showAction()` |`categoryId` (integer),
`showInStock` (boolean),
`limit` (integer),
`template` (string)|Product| +|[Other customers have also seen]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-seen-block)| `SimilarItemsBlockController`
`::showAction()` |`productCode` (string),
`showInStock` (boolean),
`limit` (integer),
`template` (string)|Product| +|[Other customers have also seen this content]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-seen-this-content-block)| `SimilarContentBlockController`
`::showAction()` |`contentId` (integer),
`limit` (integer),
`template` (string)|Content| +|[Other Customers Have also Purchased block]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-purchased-block)| `OtherCustomersAlsoPurchasedBlockController`
`::showAction()` |`productCode` (string),
`limit` (integer),
`template` (string)|Product| +|[Personalized content recommendations]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#personalized-content-recommendations-block)| `UserContentRecommendationsBlockController`
`::showAction()` |`limit` (integer),
`template` (string)|Content| +|[The Personal Shopping Assistant]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#the-personal-shopping-assistant-block)| `UserItemRecommendationsBlockController`
`::showAction()` |`productCode` (string),
`showInStock` (boolean),
`limit` (integer),
`template` (string)|Product| +|[User's item history]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#users-item-history-block)| `UserItemHistoryBlockController`
`::showAction()` |`showInStock` (boolean),
`limit` (integer),
`template` (string)|Product| + +Each template receives a `recommendations` Twig variable, which is a list containing either [`Ibexa\Contracts\ProductCatalog\Values\ProductInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-ProductInterface.html) instances for product recommendations or [`Ibexa\Contracts\Core\Repository\Values\Content\Content`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-Content-Content.html) instances for content recommendations. + +Two generic templates are provided and can be used in `./templates/themes/` directory: + +- `@ibexadesign/ibexa/recommendations/_content_list.html.twig` for content items: + +``` html+twig +{% if recommendations is not empty %} + {% for content in recommendations %} + {% set location = content.contentInfo.mainLocation %} + {% if location %} +

{{ ibexa_content_name(content) }}

+ {% else %} +

{{ ibexa_content_name(content) }}

+ {% endif %} + {% endfor %} +{% endif %} +``` + +- `@ibexadesign/ibexa/recommendations/_product_list.html.twig` for products: + +``` html+twig +{% if recommendations is not empty %} + +{% endif %} +``` + +To fetch recommendations for the remaining modules, you need to [create a custom controller](controllers.md) and use a method from [`Ibexa\Contracts\ConnectorRaptor\Recommendations\RecommendationsServiceInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorRaptor-Recommendations-RecommendationsServiceInterface.html). + +Using this method, recommendations can be displayed on any page, for example on a specific product page, as shown below: + +![Custom rendering](custom_rendering.png) diff --git a/docs/recommendations/raptor_integration/img/account_number.png b/docs/recommendations/raptor_integration/img/account_number.png new file mode 100644 index 0000000000..b6d2cd5f86 Binary files /dev/null and b/docs/recommendations/raptor_integration/img/account_number.png differ diff --git a/docs/recommendations/raptor_integration/img/advanced_settings.png b/docs/recommendations/raptor_integration/img/advanced_settings.png new file mode 100644 index 0000000000..d63a18e4d1 Binary files /dev/null and b/docs/recommendations/raptor_integration/img/advanced_settings.png differ diff --git a/docs/recommendations/raptor_integration/img/api_key.png b/docs/recommendations/raptor_integration/img/api_key.png new file mode 100644 index 0000000000..a133d98265 Binary files /dev/null and b/docs/recommendations/raptor_integration/img/api_key.png differ diff --git a/docs/recommendations/raptor_integration/img/custom_rendering.png b/docs/recommendations/raptor_integration/img/custom_rendering.png new file mode 100644 index 0000000000..e7649cde21 Binary files /dev/null and b/docs/recommendations/raptor_integration/img/custom_rendering.png differ diff --git a/docs/recommendations/raptor_integration/img/raptor_module.png b/docs/recommendations/raptor_integration/img/raptor_module.png new file mode 100644 index 0000000000..0cddfb73d5 Binary files /dev/null and b/docs/recommendations/raptor_integration/img/raptor_module.png differ diff --git a/docs/recommendations/raptor_integration/img/recommendation_blocks.png b/docs/recommendations/raptor_integration/img/recommendation_blocks.png new file mode 100644 index 0000000000..db8ef552de Binary files /dev/null and b/docs/recommendations/raptor_integration/img/recommendation_blocks.png differ diff --git a/docs/recommendations/raptor_integration/raptor_connector.md b/docs/recommendations/raptor_integration/raptor_connector.md new file mode 100644 index 0000000000..3264624804 --- /dev/null +++ b/docs/recommendations/raptor_integration/raptor_connector.md @@ -0,0 +1,35 @@ +--- +description: Step-by-step activation procedure of setting up the Raptor connector. +page_type: landing_page +month_change: true +--- + +# Raptor connector + +The [Raptor](https://www.raptorservices.com/) connector is an add-on that provides a seamless integration between [[= product_name =]] and Raptor recommendation engine. + +Its primary goal is to enable editors and managers to deliver personalized experiences across digital channels, which helps increase conversion rates, drive sales, and improve user engagement. + +By combining content management capabilities with advanced recommendation features, the connector allows teams to build and manage personalized experiences across integrated tools. + +The connector ensures a smooth and unified integration layer, enabling: + +- event tracking through the tracking API +- personalized delivery of content and product recommendations through the Recommendations API +- flexible, SiteAccess-aware configuration + +This approach reduces integration complexity while providing a scalable foundation for personalization use cases across multiple sites and markets. + +To configure the integration with Raptor, follow a step-by-step procedure that allows you to activate the Raptor connector. +Activation includes [configuration](connector_installation_configuration.md), adding tracking scripts and events, and using [Page Builder](page_builder_guide.md) blocks. + +For more information on tracking, check the Raptor documentation: [Implementing tracking](https://content.raptorservices.com/help-center/data-management#implementing-tracking). + +[[= cards([ + "recommendations/raptor_integration/connector_installation_configuration", + "recommendations/raptor_integration/tracking_functions", + "recommendations/raptor_integration/tracking_php_api", + "recommendations/raptor_integration/recommendation_blocks", + "recommendations/raptor_integration/custom_recommendation_rendering", + "templating/twig_function_reference/recommendations_twig_functions", +], columns=3) =]] diff --git a/docs/recommendations/raptor_integration/raptor_connector_guide.md b/docs/recommendations/raptor_integration/raptor_connector_guide.md new file mode 100644 index 0000000000..3ac2b49ab2 --- /dev/null +++ b/docs/recommendations/raptor_integration/raptor_connector_guide.md @@ -0,0 +1,125 @@ +--- +description: Discover Raptor integration - an add-on focused on recommendations and tracking customer behaviors. +month_change: true +--- + +# Raptor integration guide + +Discover [Raptor](https://www.raptorservices.com/) integration - an add-on that is focused on recommendations and tracking customer behaviors. +It includes Raptor connector with tracking scripts and events, used to track and analyze customer behaviors, and a set of Recommendation blocks. + +## What is Raptor connector + +The [Raptor connector](raptor_connector.md) provides a seamless integration between [[= product_name =]] and Raptor recommendation engine. + +Its primary goal is to enable editors and managers to deliver personalized experiences across digital channels, which helps to increase conversion rates, drive sales, and improve user engagement. + +By bringing content and recommendations together, the connector makes it easy to build and manage personalized experiences. + +It provides a seamless integration layer that supports: + +- event tracking of user interactions through the Tracking API +- personalized delivery of content and product recommendations through the Recommendations API +- flexible SiteAccess-aware configuration adapted to different sites and contexts + +This approach simplifies integration while supporting personalization across different sites and markets. + +## Availability + +Raptor integration elements, such as tracking, Twig functions, and public API, are available in all supported [[= product_name =]] editions starting from v5.0.7 version. + +Recommendation blocks provided in Page Builder, are available in [[= product_name_exp =]] and [[= product_name_com =]] editions. + +## 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. +Tracking can be set up either on the client-side or server-side, depending on how you want to capture and process the events. + +The tracking works differently depending on the mode you choose. +In server-side mode, tracking happens on the server, handling all events without loading scripts in the browser. +In client-side mode, it inserts script tags so tracking runs directly in the browser. + +You can switch between server and client tracking at any time by changing the tracking type to fit your setup and needs. + +## Capabilities + +### Tracking + +Raptor [tracking functions](tracking_functions.md) allow you to collect data about how users interact with your products and content. + +You can track product visits to better understand what users are viewing. +Provided [Twig functions](../../templating/twig_function_reference/recommendations_twig_functions.md) simplify the implementation, allowing developers to quickly add tracking to templates without complex setup. + +This gives you the data you need to better understand user behavior, improve recommendations, and support personalization. + +### Recommendation blocks + +The Raptor Integration provides a set of ready-to-use recommendation blocks that can be added directly in the [Page Builder](page_builder_guide.md). + +These blocks can be configured to adjust how they work and what they display. +Content, Product, and Commerce recommendations can be placed on landing pages using these components. + +Editors can use these blocks to display tailored product recommendations, promote related content, and highlight items that are trending or recently viewed. + +Recommendation blocks are organized into dedicated categories, each grouping blocks based on the type of recommendation they provide: + +- **Recommendations: Content** - presents content recommendations: + - [Content that has been seen along with the item category]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#content-that-have-been-seen-along-with-the-item-category-block) + - [Most popular content]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-content-block) + - [Other customers have also seen this content]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-seen-this-content-block) + - [Personalized content recommendations]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#personalized-content-recommendations-block) +- **Recommendations: Product** - displays product suggestions based on visitors’ browsing history: + - [Most popular products]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-products-block) + - [Most popular products in category]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-products-in-category-block) + - [Other customers have also seen]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-seen-block) +- **Recommendations: Commerce** - shows recommendations based on visitors' purchase history (buy and basket events): + - [Other customers have also purchased block]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-purchased-block) + - [The Personal Shopping Assistant]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#the-personal-shopping-assistant-block) + - [User's item history]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#users-item-history-block) + +![Recommendation blocks](recommendation_blocks.png) + +For a complete description of Recommendation blocks see [Recommendation blocks in User Documentation]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/). + +### Advanced usage for complex tracking scenarios + +For more complex tracking requirements, [PHP API](tracking_php_api.md) provides direct access to the service. +It lets you track custom user actions, create more detailed tracking logic, and support scenarios not covered by the standard client- or server-side setups. + +## Benefits + +### Understand user behavior + +Thanks to tracking functions, you can capture how users interact with your products and content, giving you valuable insights into their behavior. +It helps you make data-driven decisions to improve engagement and personalize the user experience. + +### Highlight recommendations + +Use recommendation blocks on your websites to highlight content targeted at your customers. +Deliver relevant content and build trust in your brand. + +### Suggest content to boost retention + +Help users find content of their interest quicker. +Showing visitors content and products that match their interests helps keep them engaged and encourages them to come back. + +### Meet customer expectations and increase engagement + +Recommendation blocks highlight products that match customers' interests. +Tailored content boosts engagement by showing visitors information and products that align with their interests and fulfill their needs. +This strengthens the connection between your brand and your audience, encouraging them to spend more time on your site and return more often. + +### Increase average order value + +Use tracking for predictive analysis and find out what motivates users to put extra items into their carts. +Start building predictions of their behaviors and suggest products your visitors are willing to buy. + +### Track performance and increase conversions + +Use the Raptor service in your Commerce shop and see how recommendations drive sales. +Keep track of which recommendations are shown to visitors and measure conversion rates to evaluate their effectiveness against your goals. + +### Flexible tracking with PHP API + +Tracking using PHP API gives you full control over how events are recorded and processed. +You can use it for complex scenarios, so tracking can be adapted to your specific needs or business requirements. diff --git a/docs/recommendations/raptor_integration/recommendation_blocks.md b/docs/recommendations/raptor_integration/recommendation_blocks.md new file mode 100644 index 0000000000..76a13e2f8a --- /dev/null +++ b/docs/recommendations/raptor_integration/recommendation_blocks.md @@ -0,0 +1,43 @@ +--- +description: Recommendation blocks in Page Builder +edition: experience +month_change: true +--- + +# Recommendation blocks in Page Builder + +One of the Raptor Integration elements is the introduction of recommendation blocks available in the [Page Builder](page_builder_guide.md). + +Content, Product, and Commerce recommendations can be added to a landing page using the blocks. + +Editors can configure these blocks to display: + +- personalized product recommendations +- related articles or content +- recently viewed or popular items + +In the toolbar, corresponding categories for recommendation blocks are available, containing sets of blocks depending on the recommendation type: + +- **Recommendations: Content** - presents content recommendations: + - [Content that has been seen along with the item category]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#content-that-has-been-seen-along-with-the-item-category-block) + - [Most popular content]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-content-block) + - [Other customers have also seen this content]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-seen-this-content-block) + - [Personalized content recommendations]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#personalized-content-recommendations-block) +- **Recommendations: Product** - displays product suggestions based on visitors’ browsing history: + - [Most popular products]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-products-block) + - [Most popular products in category]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#most-popular-products-in-category-block) + - [Other customers have also seen]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-seen-block) +- **Recommendations: Commerce** - shows recommendations based on visitors' purchase history (buy and basket events): + - [Other customers have also purchased block]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#other-customers-have-also-purchased-block) + - [The Personal Shopping Assistant]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#the-personal-shopping-assistant-block) + - [User's item history]([[= user_doc =]]/personalization/raptor_integration/raptor_recommendation_blocks/#users-item-history-block) + +![Recommendation blocks](img/recommendation_blocks.png) + +After opening the settings of a recommendation block, a link is available at the bottom of the window. +It leads to the [Raptor Control Panel](https://controlpanel.raptorsmartadvisor.com/) (opens in a separate tab), where you can configure advanced settings and fine-tune the recommendation strategy. + +![Advanced settings](img/advanced_settings.png) + +For a complete description of Recommendation blocks see [Recommendation blocks]([[= user_doc =]]/recommendations/raptor_integration/raptor_recommendation_blocks/). +For the list of all page blocks that are available in Page Builder, see [Block reference page]([[= user_doc =]]/content_management/block_reference/). diff --git a/docs/recommendations/raptor_integration/tracking_functions.md b/docs/recommendations/raptor_integration/tracking_functions.md new file mode 100644 index 0000000000..8beac23b0f --- /dev/null +++ b/docs/recommendations/raptor_integration/tracking_functions.md @@ -0,0 +1,94 @@ +--- +description: Integrate the tracking script to collect user interactions. +month_change: true +--- + +# Raptor tracking functions + +[Raptor connector](raptor_connector.md) introduces [visit tracking functionality](https://content.raptorservices.com/help-center/introduction-to-tracking-documentation) for collecting user interactions with products and content. +The implementation includes product visit tracking with mapping to tracking parameters, and Twig functions for straightforward integration. + +Raptor integration introduces two Twig functions: + +- [`ibexa_tracking_script()`](../../templating/twig_function_reference/recommendations_twig_functions.md#ibexa_tracking_script-function) - allows you to embed main tracking script into the website. +- [`ibexa_tracking_track_event()`](../../templating/twig_function_reference/recommendations_twig_functions.md#ibexa_tracking_track_event-function) - is responsible for sending event data to the service, enabling tracking of user interactions and behaviors. + +## Embed tracking script + +To enable tracking, tracking script must be embedded into the website’s layout. +To embed tracking script, add the twig function `ibexa_tracking_script()` into the section of your base layout template, for example, `@ibexadesign/pagelayout.html.twig`: + +``` html+twig +[[= include_file('code_samples/recommendations/templates/themes/standard/pagelayout.html.twig') =]] +``` + +## Tracking modes + +Tracking user interactions can be implemented on the client-side or the server-side. +Each approach differs in where events are captured and how they are sent to the tracking backend. + +The [tracking Twig function](#embed-tracking-script) outputs different content depending on the mode: + +``` yaml +# Server-side tracking +connector_raptor: + tracking_type: 'server' # Returns HTML comments + +# Client-side tracking +connector_raptor: + tracking_type: 'client' # Returns