Implementation Steps

This article details the setup of Relewise by providing entities, setting up behavioral tracking, and implementing services. It is contingent on your having already set up your connection to Relewise via the API as per the Getting Started page. If you have yet to set yourself up with an authenticated API key, please follow the steps provided on the Getting Started page before you continue with this guide.

The scope of this article is to provide a down-to-Earth step by step of implementing Relewise on your site. For tips, good advice, and best practices, we refer to our Best Practices page instead. For concrete examples of code snippets to get you started, take a look at our Examples page. Taken together, these pages will provide you with a good starting setup that will allow you to further customize according to your needs.

Overview

There are three things that need to be done before you can leverage the benefits of Relewise on your site:

1. Provide Entities to Relewise that should be searched and recommended; these will typically be products/product groups and site content (pages, blogs, support pages, etc.)

2. Add Behavioral Tracking about how users interact with the entities on the site, so Relewise can rank search results better and generate recommendations.

3. Implement Services like pages for search, recommendations, and other services via the various API calls, to provide context. For example, you can provide the search term for a search and get the search results back, or provide a viewed product so Relewise can provide similar products.

1. Provide Entities

When integrating with Relewise, there are 2 different options available on how to get data into the Relewise API:

1. Push data to Relewise API - this is the recommended approach as you have the most control.
2. Pull data from a Feed via My Relewise. Relewise innately supports RSS 2.0/Google Shopping feeds, but can work with any kind of feed you have. Please note that integrating a custom feed in this way will require billed work on our part.

The API provides basic CRUD operations for Products, Product Categories, Content, Content Categories, Brand, Users, etc.

List of Entity-Actions

Below is a list of common Entity-Actions useful for setting up Relewise. For the full list, consult our API Reference.

Click to expand entity-actions table

Note: The various "Update" endpoints are used both to create entities as well as update them. In other words, if an entity does not exist already, the update endpoints will create them.

Entity-Action	Description
ProductQuery	The ProductQuery provides access to read information about products from Relewise
ContentQuery	The ContentQuery provides access to read information about content pages from Relewise.
UserQuery	The UserQuery provides access to read information about users in Relewise. Information can be queried by AuthenticatedID, TemporaryID, and E-mail. Furthermore, you can define one or more identifiers, that also can be used to query users. Users can be queried by a collection of identifiers and any user fulfilling any identifier is returned. Typical Use Case: When sending out newsletters with product recommendations you want to insert different types of recommendations depending on information known about the user. If it is a user known in Relewise you insert recommendations of type PersonalProductRecommendation and if it is a user not known to Relewise you insert PopularProducts
TrackProductUpdate	The TrackProductUpdate is used to add/update information about a product in Relewise.
TrackProductCategoryUpdate	The TrackProductCategoryUpdate is used to add/update information about a product category in Relewise.
TrackContentUpdate	The TrackContentUpdate is used to add/update information about a content element in Relewise.
TrackContentCategoryUpdate	The TrackContentCategoryUpdate is used to add/update information about a content category in Relewise.
TrackBrandUpdate	The TrackBrandUpdate is used to update information about a brand in Relewise.
TrackProductAdministrativeAction	The TrackProductAdministrativeAction provides functionality to delete, enable or disable one or more products in Relewise based on filtering.
TrackProductCategoryAdministrativeAction	The TrackProductCategoryAdministrativeAction provides functionality to delete, enable or disable one or more product category elements in Relewise based on filtering.
TrackContentAdministrativeAction	The TrackContentAdministrativeAction provides functionality to delete, enable or disable one or more content elements in Relewise based on filtering.
TrackContentCategoryAdministrativeAction	The TrackContentCategoryAdministrativeAction provides functionality to delete, enable or disable one or more content category elements in Relewise based on filtering.
TrackBrandAdministrativeAction	The TrackBrandAdministrativeAction provides functionality to delete, enable or disable one or more brands in Relewise based on filtering.
TrackUserUpdate	The TrackUserUpdate provides functionality to update information about a user in Relewise. Typical use case: You want to update information about a user's e-mail address or segmentation.

Data Types

When importing entities into the API, ensure that your data is of the correct type for optimal performance. Relewise supports a number of different data value types, including String, StringList, Double, DoubleList, Boolean, BooleanList, Multilingual, MultilingualCollection, Multicurrency, Object, and ObjectList. These are outlined below with examples of use case and code snippet.

Click to expand data types

String Data

Use string data for any texts that are not language-specific, and which do not require natural language processing in the interaction with the search. For language-specific texts that you want your users to search for, use Multilingual data or MultilingualCollection data instead.

Use Case Example

You want to attach a Product URL to the Relewise data, so you can retrieve it at a later time during or after the search.

Example of String Data

product.Data["ProductUrl"] = "https://example.com/shop/product/19782-this-is-a-product.html";

 

StringList Data

Use StringList for any field where you require a list of strings that are not language-specific. If the strings are language-specific, and/or you expect to employ natural language processing in the search for these strings, use MultilingualCollection instead.

Use Case Examples

You want to append a list of product IDs that are compatible with the product being shown, so you can retrieve it at a later time.

Example of StringList Data

product.Data["CompatibleWithProducts"] = new string[]{"p1", "p2", "p3"};

 

Double Data

Use Double data values to store numbers or values, particularly those used to faceting or for use in mathematical operations.

Use Case Examples

You want to emphasize products with a certain in-stock threshold, so you add StockCountto the product in order to set up a merchandising rule on the basis of stock count.

Example of Double Data

product.Data["StockCount"] = 19;

 

DoubleList Data

Use DoubleList data when you have multiple numeric data points for a given entity.

Use Case Examples

You retail containers for liquid, and want to detail the different sizes that a product comes in.

Example of DoubleList Data

product.Data["CompatibleVolumesInLiters"] = new double[] { 1, 2, 4, 5, 10 };

 

Boolean Data

Boolean data is mainly for fields used in merchandising or faceting.

Use Case Examples

You want to hide or bury products that are out of stock, so you add InStock as a Boolean field in order to set up a merchandising rule.

Example of Boolean Data

product.Data["InStock"] = True;

 

BooleanList Data

Use BooleanList data for when your products have a number of true/false conditions. It is primarily a tool for merchandising or faceting.

Example of BooleanList Data

product.Data["BooleanListProperty"] = new bool[] { true, false, false, true, true };

 

Multilingual Data

Multilingual data is used to contain language-specific strings that you want to be directly searchable by your users, such as Product Title, Description etc.

Use of Multilingual data ensures that Relewise performs natural language processing such as stemming and decompounding to the search, ensuring better results. Even for sites with a single language, the use of Multilingual Variables is encouraged.

Use Case Examples

You want your users to be able to search for the description of a product, so you set up Description as a Multilingual field.

Example of Multilingual Data

product.Data["Description"] = new Multilingual(
    new Multilingual.Value(english, "The short english description")
    );

 

MultilingualCollection Data

Use MultilingualCollection data when you have a field that contains a series of language-specific strings that you want to be directly searchable by your users.

Use of Multilingual data ensures that Relewise performs natural language processing such as stemming and decompounding to the search, ensuring better results. Even for sites with a single language, the use of Multilingual Variables is encouraged.

Use Case Examples

You have a site in English and in German, and you want to present your users with localized search and recommendation results.

Example of MultilingualCollection Data

product.Data["ShortDescription"] = new Multilingual(
    new Multilingual.Value(new Language("en"),
        "The short english description")
    new Multilingual.Value(new Language("ge"),
        "Die kurze deutsche Beschreibung")
    );

 

Multicurrency Data

Price data is stored as MultiCurrency data, which contains a string describing the name of the currency, and a double type data containing the price itself. Even when your site only uses a single currency, you should strive to employ MultiCurrency data.

Use Case Example

You have multiple currencies on your site, and want to display the correct currency according to your users' preference.

Example of Multicurrency Data

product.Data["InstallationPrice"] = new MultiCurrency(
    new Money(new Currency("DKK"), 300),
    new Money(new Currency("EUR"), 40)
);

 

Object and ObjectList

Use Objects to store different types of data that you want returned together in a request. An ObjectList can be useful for storing lists of data that you want to present together, and is commonly used for faceting.

Use Case Examples

You have a list of physical stores, and want to allow your users to sort a product by the amount in stock in a certain store. So you make an ObjectList with storeId and stockAmount in each object.

Example of an ObjectList

product.Data["Stores"] = new DataObject[] {
     new DataObject(new Dictionary<string, DataValue?>() {
        ["StoreId"] = "Store1",
        ["StockCount"] = 203,
        ["ConnectedWarehouses"] = new double[] { 1, 9, 22 } }),
     new DataObject(new Dictionary<string, DataValue?>() {
        ["StoreId"] = "Store2",
        ["StockCount"] = 53,
        ["ConnectedWarehouses"] = new double[] { 3, 2, 20 } }) 
    };

 

Ensuring that you use the correct data types can improve the performance and accuracy of your Relewise experience, and in turn provide a better experience for your users. We urge you to contact us if you are unsure about what data type to use.

Once your integration has been set up and run, you will be able to find the data by searching for it under the Entities section of my.relewise.com.

2. Add Behavioral Tracking

Behavioral tracking is the bread and butter of Relewise's personalization engine. Relewise does not charge anything for behavioral tracking, and we recommend that you set up tracking for all possible event types. This ensures a better personalized result.

Note that when tracking user behavior, it is important to provide the correct type of user identification. If the user has given consent to tracking, user information is tracked as well in the various types below. More information about the different user types can be found here.

Tracking Examples

To get started with Behavioral Tracking, you can refer to our Examples page, where you can find code snippets that can help you get underway quickly. Specifically, we offer examples for setting up tracking with:

• .NET
• Typescript/Javascript
• PHP
• Java

For further information, you should refer to the SDK of the language you are using.

The API furthermore provides endpoints for the various behavior tracking of users on the website; refer to the table below for an overview of the different types of tracking types.

Click to Expand Track-type Table

Track-Type	Description
TrackProductViewRequest	Tracks that a given product has been viewed by a user.
TrackProductCategoryViewRequest	Tracks that the product list of a given product category has been viewed by a user.
TrackContentViewRequest	Tracks that a given piece of content has been viewed by a user.
TrackContentCategoryViewRequest	Tracks that the content list of a given content category has been viewed by a user.
TrackBrandViewRequest	Tracks that a given brand has been viewed by a user.
TrackCartRequest	Tracks that a cart has been updated by a user.
TrackOrderRequest	Tracks that an order has been completed including which products it consisted of.
TrackSearchTermRequest	Tracks that a user has searched for a given search term.

 

3. Implement Services

With the above two implementation steps completed, Relewise now has enough data to do its real work: Adding personalization to Search and Recommendations. For practical examples of how to implement Search and Recommendation, refer to our examples page.

Search

Before you can begin performing search requests, you need to set up a search index. You can do so via the API. You can also contact us directly to have it set up. Without a Search Index, searches will return no results.

Relewise supports searching in products, product categories, content pages, and content categories. The search engine is personalized from user behavior data, which means that a user who is non-anonymous will receive search results based on their previous behavior.

Relewise is a fully-fledged search engine, which means that we support all the standard features of a search engine that can be expected today, such as facetting, filtering, sorting, pagination, and natural language processing.

For more information on our search engine, click here.

Search-Type	Description
ProductSearch	Product search is used to find products that match a given search term, or with a filter to show products on the basis of a category, a brand, or any other product property.
SearchTermPrediction	This is used with typeahead searches to inspire users on what could be relevant search terms related to the term they have already typed into the search field. This can help the user narrow down what they are looking for. For example when searching for towel, then relevant predictions could be beach towel, kitchen towel or yoga towel.
ProductCategorySearch	Product category search helps users find product categories that match a given search term.
ContentSearch	Content searches find content elements that match a given search term.

Recommendations

Recommendations are a great tool for showcasing relevant products to your users and keep them inspired. The Relewise recommendations are personalized from user behavior data, which means that a user who is non-anonymous will receive recommendations based on their previous behavior.

Recommendations may be placed on practically any page you desire, although we recommend you stick primarily to the Product Details page, front page, cart, and Power Step. For more information on recomendations, click here.

For a guide to best practices regarding recommendation locations, consult our Best Practices page.

Click to expand Standard Recommendations table

Recommendation-Type	Description
PurchasedWithProduct	This type of recommendation returns products typically purchased with a given product.
PurchasedWithMultipleProducts	This type of recommendation returns products typically purchased with one or more given products.
PurchasedWithCurrentCart	This type of recommendation returns products typically purchased with the content of a specific basket. It uses PurchasedWithMultipleProducts as the foundation and applies further personalization based on the user to the result.
ProductsViewedAfterViewingProduct	This type of recommendation returns products typically viewed after viewing a given product.
PopularProducts	This type of recommendation returns the most popular products. It can be either the most viewed or the most purchased within a given period.
SortProducts	This type of recommendation sorts a list of products ensuring the most relevant products come first.
SortVariants	This type of recommendation sorts a list of variants for a given product ensuring the most relevant variants comes first.
PersonalProduct	This type of recommendation returns a list of personalized product recommendations to a given user.
RecentlyViewedProducts	This type of recommendation returns a list of the products that the user most recently has viewed.
ProductsViewedAfterViewingContent	This type of recommendation returns relevant product based on a given content page.
ContentsViewedAfterViewingContent	This type of recommendation returns relevant content page based on a given content page.
ContentsViewedAfterViewingProduct	This type of recommendation returns relevant content pages based on a given product.
ContentsViewedAfterViewingMultipleProducts	This type of recommendation returns relevant content pages based on multiple products.
ContentsViewedAfterViewingMultipleContents	This type of recommendation returns relevant content pages based on multiple other content pages.
PopularContents	This type of recommendation returns the most popular content pages, and can be returned for a given period.
PersonalContent	This type of recommendation returns a list of personalized content recommendations to a given user.
PopularContentCategories	This type of recommendation returns the most popular content categories. These are the most viewed within a given period.
PersonalContentCategory	This type of recommendation returns a list of personalized content categories recommendations to a given user.
PopularSearchTerms	This type of recommendation returns a list of popular search terms for a given period. It can either be generally popular or it can be based on a given search term.
SearchTermBasedProduct	This type of recommendation returns a list of products that other users, who have previously searched for a given search term, have found relevant afterward.
PopularBrands	This type of recommendation returns the most popular brands. These are the most viewed within a given period.
PopularProductCategories	This type of recommendation returns the most popular product categories. These are the most viewed within a given period.
PersonalProductCategory	This type of recommendation returns a list of personalized product category recommendations to a given user.

Advanced Recommendations

These types of recommendations use more resources than our standard recommendations and are therefore priced differently.

Recommendation-Type	Description
SimilarProducts	This type of recommendation returns products similar to a given product. It is not based on an analysis of behavioral data, but rather on an analysis of similarities in product information data.
CustomProductsRecommendations	This type of recommendation makes it possible to have customer-specific recommendations developed. When the recommendation has been developed it is accessible for the customer using the existing Relewise API.

4. Updating Entities

At this point, if you have followed the outlines provided by this article, you should have a functioning Relewise integration running on your site. The only thing remaining is to prepare for future updates to the entities provided to Relewise. There are a few ways of doing this, as described below.

Pull Data: Updating the Feed

If you are importing data via a Feed, you may occasionally need to update it to reflect changes to what you require Relewise to work with. Since the feed is updated a number of times per day, dynamic changes to the feed (such as change in stock value, InStock parameters, etc.) are automatically communicated to the Relewise API.

As such, changes to the feed only need to occur if you have new fields that you need to add to the Relewise API, such as if you are expanding your possible search criteria. For feeds that do not conform for the RSS 2.0/Google Shopping standards, this change requires you to send it to Relewise directly so it can be mapped to the Relewise API correctly. Please note that updating a custom feed in this way will require billed work on our part.

Push Data: Full Update

An API push allows greater control over the entities being updated. As described in-depth in our best practices documentation, the best way to perform a full entity update is to mark all entities in the latest update with a timestamp that is identical across the entities being updated. In the same request, send a parameter that disables all entities without the latest timestamp, and another parameter that enables all products with the latest timestamp.

var nonUpdatedProductsFilter = new FilterCollection(
	new ProductDataFilter("ImportedAt", new EqualsCondition(
		importTimestamp, negated: true)
		)
	);
productUpdates.Add(
	new ProductAdministrativeAction(
		Language.Undefined, Currency.Undefined, nonUpdatedProductsFilter, 
		Relewise.Client.DataTypes.ProductAdministrativeAction.UpdateKind.Disable)
		);

Disabling products with anything but the latest timestamp

var updatedProductsFilter = new FilterCollection(
	new ProductDataFilter("ImportedAt", new EqualsCondition(
		importTimestamp, negated: false)
		)
	);
productUpdates.Add(
	new ProductAdministrativeAction(
		Language.Undefined, Currency.Undefined, updatedProductsFilter,
		Relewise.Client.DataTypes.ProductAdministrativeAction.UpdateKind.Enable)
		);

Enabling (and re-enabling) all products with the latest timestamp

This ensures that entities that are deactivated on your site are likewise deactivated in Relewise, and that entities that were previously deactivated but were just updated are re-enabled. Please note that updating product data of a disabled product will not automatically re-enable the product; you must perform the second step described above to re-enable previously disabled products.

Deactivating products rather than deleting them allows them to be re-enabled with a simple command, and so does not run the risk of losing data that might otherwise come with outright deletion of an entity.

Push Data: Delta Update

A Delta Update is particularly useful for sites with a lot of entities, where a full daily update may be prohibitively time-consuming. By setting up a way of tracking what entities have been affected since the last update, you may perform an update on those products alone, thus foregoing the timestamp method mentioned above.

The Delta Update is a powerful tool for ensuring that you can run as many updates in a day as you need. It does, however, require you to set up a system for capturing the delta changes that need to be communicated to Relewise.

UpdateKind

A ProductUpdateRequest requires an UpdateKind, of which there are several different types. These are:

• None: This prevents any changes from happening on the product. Useful for when you want to update the variants of a product, but not the product itself, and vice versa.
• UpdateAndAppend: Updates existing properties, and adds new properties to the product if they did not exist already. For instance, if you have a product with a data field called Key1, and you send a data collection with only Key2, the update will append Key2 but not make any changes to Key1.
• ReplaceProvidedProperties: Replaces the content of data fields, or removes it if the data is null.
• ClearAndReplace: Effectively removes all data from the product, and then appends the data from the request. This is effectively equivalent to creating a new product, except you retain the product ID and thus the tracking data attached to the product.

Be aware when using ClearAndReplace that it has the ability to change a product's status from disabled to enabled. Since this UpdateKind effectively resets the product with all new data, this also includes the status of the product.