ibexa · julitafalcondusza · Jul 7, 2026 · Jul 8, 2026 · Jul 8, 2026 · Jul 8, 2026
diff --git a/docs/templating/twig_function_reference/recommendations_twig_functions.md b/docs/templating/twig_function_reference/recommendations_twig_functions.md
@@ -74,9 +74,71 @@
 
 - **eventType** - type: string, defines the type of tracking event to be sent, for example, `visit`, `contentvisit`, `buy`, `basket`, `itemclick`. For more information, see [Tracking events for recommendations](https://content.raptorservices.com/help-center/tracking-events-parameters-reference).
 - **data** (optional) - type: mixed, accepts the primary object associated with the event, such as a Product or Content, can be null if not required. For more information, see [tracking event examples](#tracking-events).
-- **context** (optional)- type: array, additional event data, such as quantity, basket details, or custom parameters. For more information, see [example usage](#context-parameter-example-usage).
+- **context** (optional)- type: array, additional event data, such as quantity, basket details, [website ID](#websiteid-parameter), or custom parameters. For more information, see [example usage](#context-parameter-example-usage).
 - **template** (optional) - type: string, path to a custom Twig template used to render the tracking event, allows overriding the default tracking output.
 
+### `websiteId` parameter
+
+The `websiteId` (`p7`) parameter for [Raptor tracking](https://content.raptorservices.com/help-center/introduction-to-tracking-documentation) can be optionally provided as a **context** to `ibexa_tracking_track_event()` function.
-The `websiteId` (`p7`) parameter for [Raptor tracking](https://content.raptorservices.com/help-center/introduction-to-tracking-documentation) can be optionally provided as a **context** to `ibexa_tracking_track_event()` function.
+The `websiteId`, also known as a **Login ID**, (`p7`) parameter for [Raptor tracking](https://content.raptorservices.com/help-center/introduction-to-tracking-documentation) can be optionally provided as a **context** to `ibexa_tracking_track_event()` function.
-The `websiteId` (`p7`) parameter for [Raptor tracking](https://content.raptorservices.com/help-center/introduction-to-tracking-documentation) can be optionally provided as a **context** to `ibexa_tracking_track_event()` function.
+The `websiteId`, also known as a **Login ID**, (`p7`) parameter for [Raptor tracking](https://content.raptorservices.com/help-center/introduction-to-tracking-documentation) can be optionally provided as a **context** to `ibexa_tracking_track_event()` function.
+
+Example:
+
+``` html+twig
+{{ ibexa_tracking_track_event('visit', product, {
+    websiteId: 'my-id'
+}) }}
+```
-Example:
-
-``` html+twig
-{{ ibexa_tracking_track_event('visit', product, {
-    websiteId: 'ibexa_user_get_current().login'
-}) }}
-```
+
+When storing customer data in an external Customer Relationship Management (CRM) system, set the `websiteId` to an identifier of the customer stored there.
+
+The following example shows how you pass that value, assuming a custom Twig function `get_custom_crm_identifier` integrating with that CRM exists:
+
+``` html+twig
+{{ ibexa_tracking_track_event('visit', product, {
+    websiteId: get_custom_crm_identifier(ibexa_user_get_current().login)
+}) }}
-Example:
-
-``` html+twig
-{{ ibexa_tracking_track_event('visit', product, {
-    websiteId: 'ibexa_user_get_current().login'
-}) }}
-```
+
+When storing customer data in an external Customer Relationship Management (CRM) system, set the `websiteId` to an identifier of the customer stored there.
+
+The following example shows how you pass that value, assuming a custom Twig function `get_custom_crm_identifier` integrating with that CRM exists:
+
+``` html+twig
+{{ ibexa_tracking_track_event('visit', product, {
+    websiteId: get_custom_crm_identifier(ibexa_user_get_current().login)
+}) }}
+
+The website ID, also known as a **Login ID**, is available for logged-in users.
+It serves as a persistent, cross-device identifier.
+Both the User ID and the Cookie ID can be used to personalize website modules.
-The website ID, also known as a **Login ID**, is available for logged-in users.
-It serves as a persistent, cross-device identifier.
-Both the User ID and the Cookie ID can be used to personalize website modules.
+Set the `websiteId` parameter for logged-id users, for which you have data uniquely identifying them. 
+The value of this parameter serves as a persistent, cross-device identifier of the user.
+Example values are User ID or the Cookie ID.
-The website ID, also known as a **Login ID**, is available for logged-in users.
-It serves as a persistent, cross-device identifier.
-Both the User ID and the Cookie ID can be used to personalize website modules.
+Set the `websiteId` parameter for logged-id users, for which you have data uniquely identifying them. 
+The value of this parameter serves as a persistent, cross-device identifier of the user.
+Example values are User ID or the Cookie ID.
+
+The value of `websiteId` parameter is resolved in the following order:
+
+1. Explicit `websiteId` passed in the `ibexa_tracking_track_event()` context.
+2. Custom `WebsiteIdContextProviderInterface` implementations (the first one returning a non-null value wins).
+3. The built-in provider, which uses the logged-in user's identifier (`ruid`).
+
+If no value is resolved, the event is sent without the `p7` parameter.
+
+To resolve `websiteId` on the project level, implement the interface as follows:
+
+``` php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tracking;
+
+use Ibexa\Contracts\ConnectorRaptor\Tracking\ContextProvider\WebsiteIdContextProviderInterface;
+
+final class MyWebsiteIdProvider implements WebsiteIdContextProviderInterface
+{
+    public function getWebsiteId(): ?string
+    {
+        // Return a non-empty string to use it as the websiteId (p7),
+        // or null to defer to the next provider in the chain.
+        return 'my-id';
+    }
+}
-<?php
-
-declare(strict_types=1);
-
-namespace App\Tracking;
-
-use Ibexa\Contracts\ConnectorRaptor\Tracking\ContextProvider\WebsiteIdContextProviderInterface;
-
-final class MyWebsiteIdProvider implements WebsiteIdContextProviderInterface
-{
-    private const string WEBSITE_ID = 'ibexa_user_get_current().login';
-
-    public function getWebsiteId(): string
-    {
-        return self::WEBSITE_ID;
-    }
-}
+namespace App\Tracking;
+
+use Ibexa\Contracts\Core\SiteAccess\ConfigResolverInterface;
+use Ibexa\Contracts\Core\Repository\PermissionResolver;
+use Ibexa\Contracts\ConnectorRaptor\Tracking\ContextProvider\WebsiteIdContextProviderInterface;
+
+final class MyCrmWebsiteUserIdProvider implements WebsiteIdContextProviderInterface
+{
+    public function __construct(
+        private ConfigResolverInterface $configResolver, 
+        private PermissionResolver $permissionResolver,
+    )
+    {
+
+    }
+
+    public function getWebsiteId(): ?string
+    {
+        $currentUserId = $this->permissionResolver->getCurrentUserReference()->getUserId();
+
+        // Don't resolve for anynomous user
+        if ($this->isAnonymousUser($currentUserId)) {
+            return null;
+        }
+
+        return $this->getWebsiteUserIdForCurrentUser($currentUserId);
+    }
+
+    /**
+     * @phpstan-return non-empty-string
+     */
+    private function getWebsiteUserIdForCurrentUser(int $userId): string
+    {
+        // Implement custom logic resolving user identifier from the CRM
+
+        return 'custom-identifier-for-the-user-retrieved from-the-CRM';
+    }
+
+    private function isAnonymousUser(int $userId): bool
+    {
+        return (int) $this->configResolver->getParameter('anonymous_user_id') === $userId;
+    }
+}
-<?php
-
-declare(strict_types=1);
-
-namespace App\Tracking;
-
-use Ibexa\Contracts\ConnectorRaptor\Tracking\ContextProvider\WebsiteIdContextProviderInterface;
-
-final class MyWebsiteIdProvider implements WebsiteIdContextProviderInterface
-{
-    private const string WEBSITE_ID = 'ibexa_user_get_current().login';
-
-    public function getWebsiteId(): string
-    {
-        return self::WEBSITE_ID;
-    }
-}
+namespace App\Tracking;
+
+use Ibexa\Contracts\Core\SiteAccess\ConfigResolverInterface;
+use Ibexa\Contracts\Core\Repository\PermissionResolver;
+use Ibexa\Contracts\ConnectorRaptor\Tracking\ContextProvider\WebsiteIdContextProviderInterface;
+
+final class MyCrmWebsiteUserIdProvider implements WebsiteIdContextProviderInterface
+{
+    public function __construct(
+        private ConfigResolverInterface $configResolver, 
+        private PermissionResolver $permissionResolver,
+    )
+    {
+
+    }
+
+    public function getWebsiteId(): ?string
+    {
+        $currentUserId = $this->permissionResolver->getCurrentUserReference()->getUserId();
+
+        // Don't resolve for anynomous user
+        if ($this->isAnonymousUser($currentUserId)) {
+            return null;
+        }
+
+        return $this->getWebsiteUserIdForCurrentUser($currentUserId);
+    }
+
+    /**
+     * @phpstan-return non-empty-string
+     */
+    private function getWebsiteUserIdForCurrentUser(int $userId): string
+    {
+        // Implement custom logic resolving user identifier from the CRM
+
+        return 'custom-identifier-for-the-user-retrieved from-the-CRM';
+    }
+
+    private function isAnonymousUser(int $userId): bool
+    {
+        return (int) $this->configResolver->getParameter('anonymous_user_id') === $userId;
+    }
+}
+```
+
+The provider is registered automatically.
+Implementing the interface is sufficient, no service configuration is required.
+
+!!! note
+
+    Custom provider takes precedence over the built-in one.
+    A provider must return either null or a non-empty string.
+
+If you register multiple providers, control their order by tagging the service with a priority (higher priority is checked first):
+
+``` php
+App\Tracking\MyWebsiteIdProvider:
+    tags:
+        - { name: ibexa.connector.raptor.tracking.website_id_context_provider, priority: 50 }
+```
+
 ### Tracking events
 
 The following events are supported and can be triggered from Twig templates: