By implementing the Recommendations Service Plugin (formerly SPI), you can integrate your service with Wix to provide advanced recommendation algorithms that allow Wix merchants to provide tailored product recommendations to their customers.
The integration process involves creating an app and configuring the Recommendations service plugin extension.
With this service plugin, you can design your app to deliver tailored recommendations across various content types, such as products, services, events, or any combination the above. For example, you can:
When your app implementing the Recommendations service plugin is installed on a Wix site, the recommendation algorithms it supports become accessible through the Recommendations API.
Learn more about service plugin extensions.
Algorithms select items to recommend from their supported catalogs. The apps providing these catalogs must be installed on the Wix site before you can start using the Recommendations service plugin on this site.
To enable Wix to communicate with your app:
Name | Type | Description |
---|---|---|
deploymentUri | string | Required. Base URI for your service's endpoints. Wix appends the endpoint path to the base URI. For example, to call the Get Recommendations endpoint at https://my-recommendation.com/v1/get-recommendations , the base URI you provide here is https://my-recommendation.com/ . |
catalogAppIds | Array | Required. App IDs of supported catalogs. The following are Wix apps that provide catalogs and their app IDs: Wix Stores: "215238eb-22a5-4c36-9e7b-e7c08025e04e" Wix Bookings: "13d21c63-b5ec-5912-8397-c3a5ddb27a97" Wix Restaurants: "9a5d83fd-8570-482e-81ab-cfa88942ee60" |
supportedAlgorithms | Array | Required. Recommendation algorithms implemented by the app. See the table below for details on the structure of the supportedAlgorithms object. |
componentName | string | Required. A unique name for this component. This is an internal name that will only appear in the app dashboard. |
supportedAlgorithms
propertiesProperty | Type | Description |
---|---|---|
reserved | int | Reserved field with a value of 1. |
name | string | Required. Algorithm name. This value is not translatable. |
description | string | Required. Algorithm description. This describes how the algorithm works and if it has any limitations regarding site content, number of items in the catalog, site traffic, and so on. This value is not translatable. |
additionalInfo | google.protobuf.StringValue | A supplemental description . It can be used to help break up and organize information. You can, for example, display this information as a tooltip or as an additional section that is collapsed by default. |
algorithmType | enum | Algorithms may have the following types: * RELATED_ITEMS - This type of algorithm provides recommendations based on 1 or more other provided items. For example, when an item is added to a cart, the algorithm can suggest other items frequently bought together with that item.* GLOBAL - This type of algorithm provides general recommendations based on site or project statistics. |
algorithmId | string | Required. Algorithm ID. This must be unique for a specific app but does not have to be unique across all apps on the site or in the project. |
The following is an example of a valid config file:
```json
{
"deploymentUri": "https://my-recommendation.com/",
"catalogAppIds": ["c567afb8-ac2c-4888-a90c-94933066ae6a"],
"supportedAlgorithms": [
{
"algorithmId": "945a457f-0a57-4cf4-95a1-95991b545119",
"name": "Frequently bought together",
"description": "Products frequently bought together with selected one",
"algorithmType": "RELATED_ITEMS"
},
{
"algorithmId": "97f48eb2-4d42-4296-b620-13862dd0353e",
"name": "Personalized recommendations",
"description": "Personalized recommendations based on user's behavior",
"additionalInfo": "Works best when user has a history of interactions with the site",
"algorithmType": "GLOBAL"
}
],
"componentName": "MyRecommendations"
}
```
This article presents a sample flow your app can support. You aren't limited to this exact flow, but it can be a helpful jumping off point as you plan your Recommendations integration.
In this flow, a site owner selects a recommendation algorithm provided by your app, and adds a "Related Products" widget to display the recommendations. Wix calls the Recommendations service plugin to get a list of items recommended by the algorithm, which are then sent to the widget.
Before implementing this flow, configure your app, so it can communicate with your Recommendations service plugin implementation.
Note: Currently, only the Online Stores app has a user interface (UI) that supports recommendations. To work with the Online Stores app, ensure that you include catalogAppIds: ["215238eb-22a5-4c36-9e7b-e7c08025e04e"]
when configuring your Ecom Recommendations Provider extension in the Wix Dev Center.
Alternatively, you can implement your own custom UI to display recommendations by leveraging one of Wix’s Development Frameworks and the Recommendations API.
algorithmType
of RELATED_ITEMS
are listed under the "Related Products" section.A site visitor navigates to a page with the Related Products widget.
Wix sends a Get Recommendations service plugin request to your app. The payload includes the algorithmId
of the selected algorithm. If the widget is installed on a products page, the items
field is populated with the product's ID as catalogItemId
and the Wix Stores app ID as appId
:
{
"algorithmId": "945a457f-0a57-4cf4-95a1-95991b545119",
"items": [
{
"catalogItemId": "ec7914e8-208b-0069-5850-1a965643508d",
"appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
}
]
}
On any other page, the items
field is empty.
Your app responds with a list of recommendations.
Example of a successful response from your app:
{
"recommendationPerAlgorithm": [
{
"algorithmId": "945a457f-0a57-4cf4-95a1-95991b545119",
"recommendedItems": [
{
"catalogItemId": "1ce6198f-5fad-5ac9-5b36-ecb2175929ef",
"appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
},
{
"catalogItemId": "58a7ab15-5c65-d836-7934-86f78b17996b",
"appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
}
]
}
]
}
The site displays the recommended products in the widget based on the IDs of the products returned in your response.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
This method retrieves an array containing the lists of recommended items returned by each algorithm. Items must be selected from catalogs in Wix apps installed on the site.
If a requested recommendation algorithm's type is RELATED_ITEMS
then the items
field is included in the request. The response should contain items related to those submitted.
How the related items are selected depends on the recommendation algorithms used. For example, items can be in the same category, or can be frequently bought or watched together.
The set of items used by algorithms with the RELATED_ITEMS
algorithmType
to determine related item recommendations.
List of algorithms used to find recommended items. Items will be returned in a separate object for each algorithm
Related items returned by each algorithm.
Each object in the array contains an algorithmId
and a list of the item recommendations provided by that algorithm.
curl POST 'www.wixapis.com/stores/recommendations/v1/get-recommendations' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--data-binary '{
"items": [
{
"catalogItemId": "ec7914e8-208b-0069-5850-1a965643508d",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
}
],
"algorithmIds": ["4197e48af4324989be1aa691fe37c53a", "09dc98e8-8696-49f7-833a-bab57f516f88"]
}'
{
"recommendationPerAlgorithm": [
{
"algorithmId": "4197e48af4324989be1aa691fe37c53a",
"recommendedItems": [
{
"catalogItemId": "1ce6198f-5fad-5ac9-5b36-ecb2175929ef",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "efd0b233-8f8e-b6b8-b5f3-66903caa8558",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "58a7ab15-5c65-d836-7934-86f78b17996b",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "040528a7-7256-7875-c8e4-8976d949f66b",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "11e2ffb7-2520-3c21-051e-1f05486b9061",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "e8f9c6d5-4ddd-36dd-f595-fe7bfd7891e2",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "16694dd9-ab43-7c5b-974e-e15a4297f235",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "593c5cd0-4996-2a8a-ad34-7669f266c42e",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "51c819a7-9380-1748-d761-b0bb25d175c2",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
}
]
},
{
"algorithmId": "09dc98e8-8696-49f7-833a-bab57f516f88",
"recommendedItems": [
{
"catalogItemId": "bbd4f614-5ca0-26bc-5546-a694a49476e7",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "75826f6b-d3b3-77dc-8aba-b2b42b4ced3a",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "813e1ea2-bf63-48f3-0554-4ae86acb21e5",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "e0071b73-eefc-7477-383e-11f1c94ad360",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "8f43bb22-3e48-dff3-06f4-69ef591a4ee3",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "8fd2d126-1286-84c3-19e9-2ea9bf8e4f3c",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
},
{
"catalogItemId": "5695280b-2c36-3f0c-7373-b802c594f364",
"appId": "f29c9b39-1090-4d9b-8e3a-a3a681a57970"
}
]
}
]
}