Best Practices for Product Integration

If your site requires search and recommendation of products, you will need to set up proper handling of product data to Relewise.

First, decide if you want to push or pull data between your store and the Relewise API. You can read more about the difference in pushing and pulling data here.

Relewise recommends pushing product data to the API. Pushing data is faster and potentially cheaper in licensing cost, and grants a higher level of control over when entities are pushed and how they are structured.

A note on Product and Variant IDs

If your site is operating with products that have variants, it is useful to know that while ProductID must be unique across the site, VariantID only needs to be unique to the product under which the variant is stored.

For concrete examples of integrating and updating products, refer to our Examples section:

• Integrating Products with .NET
• Integrating Products with TS/JS
• Integrating Products with PHP

Importing Product Entities via API

Your import of products should include every product that is to be made available via recommendation and/or search results from Relewise.

Best practice for loading products into Relewise is to include as few product and variant fields as possible. To determine which fields to include, please refer to this checklist:

• Should the field be text searchable?
• Should results be able to be filtered on the basis of this field?
• Should results be able to be sorted on the basis of this field?
• Do you need this field returned to you in results from Relewise? This might be for instance a product image URL, which enables you to render the product image in your result UI, without needing to look up that image url in your own datastore after getting the result back from Relewise.

If you can answer yes to at least one of these, the field should be included. Otherwise, leave it out.

Each field you want to be text-searchable will be configured in the Search Index later on.

If you have multiple languages on your site, you should make sure to include data for each language in the relevant fields. For instance, if your site has an English and a German language component, you should include information for fields such as DisplayName in both English and German, using a Multilingual property.

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.

Multilingual Properties

Even if your site only has a single language, we still urge you to use Multilingual properties for those of your fields that contain language specific text. Language invariant data such as an image path does usually not need to be multilingual, except if your site uses different images for different languages.

Using multilingual datatypes ensures that these fields are properly formatted and processed by the natural language processing built into Relewise. Whenever you receive results back from Relewise in later search and recommendation responses, we will ensure correct mapping of the language specific value for the selected fields, based on the language passed to us as part of the request.

product.data["ShortDescription"] = new Multilingual(
	new Multilingual.Value(en, "An English short description")
	)

Product Updates

When running a full product update via ProductUpdate, we suggest that you include a timestamp field or similar identifier for when you perform the update.

product.Data["ImportedAt"] = importTimestamp;

This allows you to disable all products that were not included in the latest update, on the assumption that they have been removed from your site, and so should be removed from Relewise as well. By using this method, you can disable products that are out of stock, discontinued, etc, but still be able to reactivate them later as needed.

It is important to set this timestamp to the exact same value for all products being updated, such as by storing the timestamp in a variable before starting the integration. This ensures there are no changes to the timestamp while the integration is still running.

After performing the update, any product not affected by the update will have an old, unchanged timestamp from the last time it was updated.

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

With the obsolete products disabled, you should also make sure to enable any products that may have been disabled in a previous update, but which are no longer meant to be disabled. Updating product data of a disabled product will not automatically re-enable the product.

To enable all imported product, similarly to the above, use the following, where we have set "negated" to false and change the update kind to "Enable":

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

Keep in mind that this method does not apply to Delta updates, which in its nature only updates selected products.

Note that you use ProductAdministrativeAction to disable products, and ProductUpdate to create and update/enable them. Similarly, use ProductCategoryAdministrativeAction to disable product categories, and ProductCategoryUpdate to enable or update them.