Introduction
The Recommendations API allows users to promote and recommend items to their customers. Items are selected from catalogs in installed Wix apps by algorithms also provided by installed Wix apps. Users can choose algorithms from among those available to get the types of recommendations they need. For example, an algorithm could provide a list of bestselling items, or items frequently bought together with some specified item/s.
With the Recommendations API, you can:
- Get a list of recommendation algorithms available for use on your Wix site or project.
- Get a list of recommended items given one or more algorithms
Before you begin
- You must have an app installed on your project that implements the Recommendations Provider SPI and provides algorithms. You must also have an app installed whose catalogs those algorithms can apply to. (Currently, in both cases, this is only Wix Stores.)
- Algorithms can only be applied to catalogs they support. To find out which catalogs an algorithm supports, call
List Available Algorithms
and check thecatalogAppIds
.
Terminology
- Algorithm: Code that is used to identify and return items from a catalog based on some defined criteria, such as which items have the highest number of sales. Algorithms may take a list of products as input and use them in their calculations.
- Catalog: A set of products or services defined in a Wix App. In this documentation, we refer to these products or services generally as “items”.
Setup
To use the Recommendations API, install the @wix/ecom
package using npm or Yarn:
1npm install @wix/ecom
or
1yarn add @wix/ecom
Then import { recommendations }
from @wix/ecom
:
1import { recommendations } from '@wix/ecom'
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Returns a recommendation object containing a list of items to recommend to the customer.
getRecommendation()
determines which items to recommend based on the given recommendation algorithms.
getRecommendation()
doesn’t run the algorithms. It calls the installed apps that provide them.
Apps may provide algorithms for use with their own catalogs, or for use with catalogs from other apps.
For example, Wix Stores provides algorithms that can only be used on its own catalogs.
To run an algorithm, the app providing it must be installed, and an app providing a supported catalog must be installed.
For more information and to see which algorithms are available on your site or project, call listAvailableAlgorithms()
.
getRecommendation()
operates as follows:
getRecommendation()
receives as input a list of algorithms as an array. These algorithms can be provided by different apps and can apply to different catalogs.getRecommendation()
calls the app that corresponds to theappId
of the first algorithm in the list of algorithms. It passes that algorithm’s ID and the IDs of any subsequent algorithms in the array for the same app.- The app runs the algorithms.
getRecommendation()
returns items recommendations from the first algorithm (according to its position in thealgorithms
array) that meets the minimum number of recommendations. At that pointgetRecommendation()
stops calling other apps.- If none of the algorithms run by the first app meet the minimum recommended items,
getRecommendation()
finds the next algorithm in the array with a newappId
(an ID of an app that has not yet been called), and repeats the process. - If no algorithms in the
algorithms
array recommend at least the minimum recommended items,getRecommendation()
returns an empty array.
Permission Scopes
For app development, you must have one of the following permission scopes:function getRecommendation(algorithms: Array<Algorithm>, options: GetRecommendationOptions): Promise<GetRecommendationResponse>
A list of algorithms checked in a specific order determined by their appID and their position in the algorithms array. See the method description for more information.
If no algorithm is able to return at least minimumRecommendedItems items, an empty array is returned.
Get recommendation options.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Returns a list of recommendation algorithms that can be used on your Wix site or project. These algorithms can be used with getRecommendation()
to provide item recommendations to the customer.
Algorithms are run by the apps that provide them, and can only be used on catalogs they support. Apps may provide algorithms for use with their own catalogs and/or catalogs from other apps.
The app which provides an algorithm is referenced by that algorithm’s appId
. The apps whose catalogs are supported by an algorithm are referenced by the IDs in that algorithm’s catalogAppIds
array.
For an algorithm to be considered “Available” and returned in this method’s response, the algorithm must meet the following conditions:
- The algorithm’s
appId
must match the ID of an installed Wix app. - At least 1 of the IDs in
catalogAppIds
must match the ID of an installed Wix app.
Wix app IDs are listed here.
Permission Scopes
For app development, you must have one of the following permission scopes:function listAvailableAlgorithms(): Promise<ListAvailableAlgorithmsResponse>