IBX-11237: websiteId section added

[julitafalcondusza]

Question	Answer
JIRA Ticket	(https://github.com/ibexa/connector-raptor/pull/13)
Versions	4.6

Checklist

• Text renders correctly
• Text has been checked with vale
• Description metadata is up to date
• Redirects cover removed/moved pages
• Code samples are working
• PHP code samples have been fixed with PHP CS fixer
• Added link to this PR in relevant JIRA ticket or code PR

[github-actions]

Preview of modified files

Preview of modified Markdown:

• docs/templating/twig_function_reference/recommendations_twig_functions.md

[github-actions]

Summary

Status	Count
🔍 Total	758319
🔗 Unique	15005
✅ Successful	7264
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	751055
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	0

Full Github Actions output

[mnocon]

This is a confusing concept, and to make it clearer we need to provide better description of the use cases where the custom id should be provided.

The example with websiteId: 'ibexa_user_get_current().login' is not enough for two reasons:

• it does not handle the anonymous user, for which the website id should not be set (at least that's how I understand this)
• it's not clear whether it's recommended and better than the default behaviour - because by default, user id is sent as website id:

https://github.com/ibexa/connector-raptor/blob/1b622a028435145e513dc14b6cee8dd14bd076a4/src/lib/Tracking/ContextProvider/LoggedInUserWebsiteIdContextProvider.php#L20-L25 , based on user remote identifier:

https://github.com/ibexa/connector-raptor/blob/1b622a028435145e513dc14b6cee8dd14bd076a4/src/lib/Tracking/TrackingIdentifierProvider.php#L146-L159

The use cases I'm thinking of where providing a custom website id might be needed:

• custom CRM scenario - if you store information about your customers in an external CRM system, you might use one of the identifiers stored there and send that instead of the default value
• B2B scenario - send company identifier (the company the user belongs to) instead of an ID of a single user to track actions of the whole company, not a single user

[mnocon]

Suggested change

	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.

Let's introduce this alternative name in the introduction of this parameter.

BTW, Raptor doc calls it "User ID"? https://content.raptorservices.com/help-center/user-tracking-understanding-soft-ids-hard-ids-raptor-identity-matching#:~:text=IDs%3A-,UserId%20%28Website%20ID

The explanation from the Raptor doc:internal site ID for logged‑in users sounds useful

[mnocon]

"is available" is confusing here, makes it sounds as if it's calculated for users when they log in.

Maybe:

Suggested change

	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.

[mnocon]

I don't think it's recommended to to this, as it's not better from the default implementation.

We need to describe a business cases here, for example (sentences are a draft):

Suggested change

	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)
	}) }}

This one doesn't handle the anonymous user, which I guess would be a bug - so we need to verify this if this should be expanded even further

[mnocon]

Example showing how you could set the website ID by integrating it with a custom CRM if you use one. This one shows also how to handle the anonymous user.

Suggested change

	<?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;
	}
	}

If we go with this one, the sentences below are out of date.