Website product recommendations - developer setup

This article explains how to set up Ometria's product recommendation engines on your site using the product recommendations API which the JavaScript tracker offers as a plugin.

Before you begin

Your marketing team should have sent you a product recommendation ID from Ometria, this is required by the exposed getProductRecommendations method this plugin offers.

See: Website product recommendations - marketing setup

Initialise the ometria object

You must initialise the ometria object in order to use  the getProductRecommendations()method.

This method performs a GET request to the recommendations endpoint retrieving product recommendations based on the parameters passed.

See our JavaScript tracker documentation for guidance.

Signature

type Params = {
    prodRecInstance: string;
    account: string;
    limit: number;
    theirProductIds?: number[];
    customerId?: string;
    email?: string;
    excludeProducts?: number[];
};

type SuccessCallback = {
    (response: any): void;
};

type ErrorCallback = {
    (error: any): void;
};

function ometria.getProductRecommendations(params: Params, successCallback: SuccessCallback, errorCallback: ErrorCallback): void

Parameters

* - Required

Return value

This method does not return a value.

Examples

These examples show what happens when using the API with the different product recommendation engines.

Top products

With a prodRecInstance ID from the Top products engine, use the following method:

const params = {
   prodRecInstance: "01e36080a22f88b3d269c267bfca45fe", 
   account: "[your account hash]";
   limit: 20,
   excludedProducts: [1, 2, 3],
};

function successCallback(response) {
    // Do something with response...
}

function errorCallback(error) {
    // Do something with error
}

ometria.getProductRecommendations(params, successCallback, errorCallback);

Product based recommendations

With a prodRecInstance ID from the Similar products engine, you must provide the theirProductIds array within the params object, then use the following method:

const params = {
   prodRecInstance: "01e36080a22f88b3d269c267bfca45fe", 
   account: "[your account hash]";
   theirProductIds: [1, 2, 3, 4],
   email: ‘example@example.com’,
   limit: 20,
   excludedProducts: [1, 2, 3],
};

function successCallback(response) {
    // Do something with response...
}

function errorCallback(error) {
    // Do something with error
}

ometria.getProductRecommendations(params, successCallback, errorCallback);

Profile based recommendations

With a prodRecInstance ID from the Recently viewed engine, you must provide either the customer_idor theemail properties within the params object.

If both of these properties are defined customer_id will take precedence. 

Use the following method:

const params = {
   prodRecInstance: "01e36080a22f88b3d269c267bfca45fe", 
   account: "[your account hash]";
   email: ‘example@example.com’,
   limit: 20,
   excludedProducts: [1, 2, 3],
};

function successCallback(response) {
    // Do something with response...
}

function errorCallback(error) {
    // Do something with error
}

ometria.getProductRecommendations(params, successCallback, errorCallback);

Testing with an HTTP client

During development, it could be beneficial for you to test the endpoint using an HTTP client to learn and preview the data returned.

You can use any HTTP client, however the two examples below demonstrate usage with cURL and Postman.

The base URL for the recommendations endpoint is: https://recommendations.ometria.com

A basic request requires both account and prodRecInstance query parameters.

You can get the account number from your marketing team who have access to Ometria - it's displayed in the URL:

The prodRecInstance should be sent to you also by the marketing team, they can find it on the Product recommendations screen.

cURL

curl --location --request GET 'https://recommendations.ometria.com?account=ACCOUNT_HERE&prodRecInstance=PROD_REC_INSTANCE_HERE'

Postman

Render retrieved products on-site - example

Depending on the tech stack used on your site, best practices for content rendering may differ.

This guide explains how to get recommended product data retrieved and rendered using pure JavaScript and simple DOM manipulation.

<head>
<script>// handle success callback where products will be rendered into the DOM 
const successCallback = (response) => {
    // grab element from DOM
    const productsListNode = document.getElementById('recommendedProductsList');    // construct html list with products
    let listHTML = '';    response.products.forEach(product => {
        const productHTML = `
            <li>
                <img src="${product.image_url}" alt="${product.title}">
                <span>${product.price}</span>
                <a href="${product.url}">
                    <img src="${product.image_url}" alt="${product.title}">
                </a>
            </li>
        `;        listHTML += productHTML;
    });    // apply list html to DOM element
    productsListNode.innerHTML = listHTML;
};// handle error response
const errorCallback = (error) => {
    console.error(error);
};// make call to get the products data
ometria.getProductRecommendations(
    {
        prodRecInstance: 'MY_INSTANCE'
    }, 
    successCallback,
    errorCallback
);</script>
</head>
<body>
    <!-- Recommended products list wrapper -->
    <ul id="recommendedProductsList"></ul>
</body>

Track interactions

Track impression of recommended products list:

ometria.trackRecommendedProductsImpression(prodRecInstance); 

We strongly recommend interpreting 'impression' as "recommended products were rendered and visible in the user's viewport".

This means that you should trigger the above method to track the impression when recommended products are rendered and visible to the user.

You can use various plugins or methods to check whether an element is visible to the user (in the viewport).

Here are two recommended ways of detecting visible element on the page:

• Scroll listener and getBoundingClientRect() - check example 
• Intersection Observer (modern browsers solution) - check examples 

See also: Checking your website recommendations setup

Implementing an A/B test with multiple recommendation engines

You can perform an A/B test with multiple recommendation engines by invoking the getProductRecommendations() based on some conditional logic.

The example below is hypothetical, when implementing your own A/B test you should tailor the conditional logic to your own needs:

const groupAParams {
    prodRecInstance: "Ole36080a22f88b3d269c267bfca45fe",
    account: "[your account hash]"
    email: 'example@example.com',
    limit: 20,
    excludedProducts: [1, 2, 3],
};

const groupBParams {
    prodRecInstance: "Ole26462a56c77c5d513d455cefg72ej",
    email: 'example@example.com',
    limit: 20,
    excludedProducts: [4, 5, 6],
};

if (userFallsIntoGroupA(userId)) {
    ometria.getProductRecommendations (groupAparams, successACallback, errorACallback);
} else {
    ometria.getProductRecommendations (groupBParams, successBCallback, errorBCallback);
}

function successACallback(response) {
    // Do something with response...
}

function successBCallback(response) {
    // Do something with response...
}

function errorACallback(response) {
    // Do something with error...
}

function errorBCallback(response) {
    // Do something with error...
}

Using Google Analytics to track performance

For monitoring your conversion and attribution you'll need to use Google Analytics and set up event tracking.