Tracking with our PHP client

The examples below are using our PHP SDK, which is available via Packagist.

Start by making a Tracker-instance.

use Relewise\Tracker;
// You have to `use` the above to create a Tracker.

$tracker = new Tracker(
  "00000000-0000-0000-0000-000000000001", 
  "your api key");
$tracker->serverUrl = "the server URL for the dataset";

To make requests with the SDK you need to use the types from our PHP SDK. The types are located in the namespace Relewise\Models and an example of using a concrete type could be the following:

use Relewise\Models\TrackProductViewRequest;

Also remember to specify your Server URL in your request.

Read more about how to authenticate against our API here.

UserFactory

In order to provide the best user experience with personalization, it is important that users who give permission to be tracked (marketing cookies) are tracked with a unique ID. This unique ID can be advantageously accessed through your cookie consent supplier.

Using UserFactory

To use our UserFactory you have to add the following use.

use Relewise\Factory\UserFactory;

If the user has declined cookies, use the following factory method:

UserFactory::anonymous()

If the user has accepted cookies:

UserFactory::byTemporaryId("unique ID")

Best practices with TemporaryId:

• Use an ID that is "long-living" and classified as 1st party, e.g. cookie or localStorage.
• Use same ID as the shop uses to recognize the user.
• Make sure the ID does not change, when the user completes an order.

If the user has logged in:

UserFactory::byAuthenticatedId("PermanentId", "unique ID")

Best practices with AuthenticatedId:

• If possible, use an ID that is semantic and constant.
• For a user journey that "starts" as a Temporary User, make sure to map the Temporary ID on the first request to Relewise. – this can also be done through a UserUpdate-request.

Example implementation for getting a User-instance:

private function getUser() : User
{
  //"true" for demo-purposes, this should reflect the users cookie-consent choice.
  $userHasAcceptedCookies = true;
  $userIsLoggedIn = true;
      
  $user = Null;
      
  if ($userHasAcceptedCookies)
  {
    if ($userIsLoggedIn) 
    {
      $user = UserFactory::byAuthenticatedId("PermanentId", "unique ID");
    }
    else 
    {
      $user = UserFactory::byTemporaryId("unique ID");
    }	
  }
  else
  {
    $user = UserFactory::anonymous();
  }

  return $user;
}

If there is a logical segmentation of users, e.g. country, provide this segmentation via a custom key/value pair:

$user->addToClassifications("Country", "DK");

It is recommended to seek advice from Relewise before introducing segmentation by Classifications. Incorrect/excessive usage will potentially yield worse recommendations and search results.

Product Details Page (PDP)

On the Product Details Page (PDP), the following code must be called to track a product view:

$request = TrackProductViewRequest::create(
  ProductView::create(
    $this->getUser(),
    Product::create("product id"),
    ProductVariant::create("The variant id if any, otherwise don't parse ProductVariant to constructor")
  )
);

$response = $tracker->trackProductView($request);

Product Listing Page / Collection Pages (PLP)

On the Product Listing Page (PLP), the following code is called to track a category page view:

$request = TrackProductCategoryViewRequest::create(
  ProductCategoryView::create(
    $this->getUser(),
    "category id",
    "sub-category id if any"
  )
);

$response = $tracker->trackProductCategoryView($request);

Content Page

On the Content page, the following code is called to track a content page view:

$request = TrackContentViewRequest::create(
  ContentView::create(
    $this->getUser(),
    Content::create("content id")
  )
);

$response = $tracker->trackContentView($request);

For more advanced usages, you can provide data about the content:

// Optional: Provide additional information on the content.
// This can be used later during recommendations, 
// if there is a need to e.g. filter and/or boost/bury content recommendation
$content = Content::create("content id")
  ->addToData("Type", DataValueFactory::string("<page-type>"));

$request = TrackContentViewRequest::create(
  ContentView::create(
    $this->getUser(),
    $content
  )
);

$response = $tracker->trackContentView($request);

Cart / Basket updates

In case of any change to the user's basket, the following is called with the full contents of the basket:

$cart = Cart::create(
  $this->getUser(),
  subtotal: Money::create(Currency::create("DKK"), 150.45),
  lineItems: array(
    LineItem::create(
      Product::create("product id 1"),
      ProductVariant::create("variant id if any, otherwise null instead of ProductVariant"),
      quantity: 1,
      lineTotal: 24.95
    ),
    LineItem::create(
      Product::create("product id 2"),
      ProductVariant::create("variant id if any, otherwise null instead of ProductVariant"),
      quantity: 2,
      lineTotal: 125.50
    )
  )
);

$request = TrackCartRequest::create($cart);

$response = $tracker->trackCart($request);

Orders

When user places an order, the following is called with the full contents of the order:

$order = Order::create(
  $this->getUser(),
  subtotal: Money::create(Currency::create("DKK"), 150.45),
  orderNumber: "the order number",
  lineItems: array(
    LineItem::create(
      Product::create("product id 1"),
      ProductVariant::create("variant id if any, otherwise null instead of ProductVariant"),
      quantity: 1,
      lineTotal: 24.95
    ),
    LineItem::create(
      Product::create("product id 2"),
      ProductVariant::create("variant id if any, otherwise null instead of ProductVariant"),
      quantity: 2,
      lineTotal: 125.50
    )
  )
);

$request = TrackOrderRequest::create($order);

$response = $tracker->trackOrder($request);