Basic Product Detail Page Integration

The product detail page of a retail website is where your products shine: customers discover all features of your products and decide, based on the available information, if they want to buy the product, continue their search, or simply abandon the session. The Froomle Personalization platform can help your products shine even brighter with minimal required effort, as described in this basic example.

In this example we cover a Froomle integration that will recommend your users products that are viewed by other users who also viewed this product. This will direct users to good candidates for products that do satisfy their needs if the current product failed.

To set up the basic Froomle integration on a product detail page, there are two major steps:

Requesting recommendations

Recommendations are requested from Froomle using the Recommendations API. This Recommendations API lives at https://customer_token.froomle.com/api/environment/recommendations/requests. The Froomle support team will be in touch concerning your customer_token and environment.

Froomle can identify your users by either device_id or user_id. A device_id is anything that is tied to a specific device or browser, such as a cookie. A user_id is expected to be long-lived and used across devices, e.g. a login ID.

For the basic product detail page use case we would have to create the following recommendation request:

We will create a request that fetches 4 recommendations similar to the product shown on the product detail page.

{
    "page_type": "product_detail",
    "device_id": "BD3qoN3ko7URdparQX2vDT4",
    "user_id": "7081599607",
    "context_item": "917096",
    "lists": [
        {
            "list_name": "Similar products",
            "configuration_id": "default",
            "list_size": 4
        }
    ]
}

One very important detail about this request is the context_item key. This represents the unique identifier of the product displayed on the product detail page and is used as context for generating the list of similar products.

Below is an example response:

{
    "user_group": "froomle",
    "version": "Froomle_1",
    "device_id": "BD3qoN3ko7URdparQX2vDT4",
    "user_id": "7081599607",
    "request_id": 1285050,
    "lists": [
        {
            "list_name": "Similar products",
            "configuration_id": "default",
            "list_size": 4,
            "limit": 4,
            "list_key": "biufwgbvilwabi274rbd",
            "items": [
                {
                    "item_id": "item_1",
                    "rank": 1
                },
                                {
                    "item_id": "item_2",
                    "rank": 2
                },
                                {
                    "item_id": "item_3",
                    "rank": 3
                },
                                {
                    "item_id": "item_4",
                    "rank": 4
                }
            ]
        }
    ]
}

Integration events

Recommendations also introduce a set of extra integration events that you will have to communicate to Froomle. To link the original set of recommendations that is displayed with their events sent upon interaction, the recommendations API communicates a unique request_id in its response. You will see this is listed as a mandatory parameter for all the recommendation events.

Impression

Every time you display a box of recommendations it is important for us to know when each of the recommended items displayed in the box was visible to the user. Recommendations are often displayed "below the fold" meaning users have to scroll down on the product detail page before they can actually see them. A second example is a carousel that holds the recommendations, only a subset of the recommendations will be visible initially, when users "scroll" through the carousel other recommendations will be visible too. An impression event is used for each recommendation to communicate this information to Froomle.

Click on recommendation

Once a user interacts with a recommendation by clicking on a recommended item, you will have to communicate this interaction to Froomle by means of a click_on_recommendation event.