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. Track Behavior that details 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.

You can read more about Pushing and Pulling data here.

For a full list of the data types supported by Relewise, and examples of their usecase, refer to our page on Product and Content Data.

Datakeys are Case Sensitive

Most datakeys in Relewise are case sensitive. Ensure that your data adheres to this case sensitivity to avoid unnecessary issues during implementation.

To learn more, click here.

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.

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.

Importing Historic Order Data

If you are using Relewise to search for or recommend products, you may benefit from importing historical order data from your ERP or similar. Historical order data provides a foundation of established tracking data that helps "kickstart" the behavioral tracking, thus giving our services something to base itself on in the early days of implementation.

We recommend importing historical order data around the time when you go live, but no later. Sending order data after your Relewise solution has begun tracking order data is going to mean double data tracking, which will skew the data and cause misleading service results.

Getting Started with Behavioral Tracking

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 a full list of behavioral tracking types and their function, refer to the behavioral tracking page.

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 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.
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.
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)
		);

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

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.