From f5f8084c35fb9b02a3ca2e566ccc26e705bac6d4 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 4 Sep 2024 13:50:58 -0700 Subject: [PATCH] docs(docs/integration_recommendations): updating recommendation integration docs --- docs/INTEGRATION_RECOMMENDATIONS.md | 206 +++++++++++++-------- docs/LEGACY_INTEGRATION_RECOMMENDATIONS.md | 148 +++++++++++++++ 2 files changed, 275 insertions(+), 79 deletions(-) create mode 100644 docs/LEGACY_INTEGRATION_RECOMMENDATIONS.md diff --git a/docs/INTEGRATION_RECOMMENDATIONS.md b/docs/INTEGRATION_RECOMMENDATIONS.md index 7745ff7bc..8b4447d6e 100644 --- a/docs/INTEGRATION_RECOMMENDATIONS.md +++ b/docs/INTEGRATION_RECOMMENDATIONS.md @@ -1,68 +1,106 @@ ## Recommendations Integration + +Changes to the recommendation integration scripts were made in Snap `v.0.60.0`. Legacy Recommmendation Integrations docs can still be found [`here`](https://github.com/searchspring/snap/blob/main/packages/snap-preact/src/Instantiators/README.md) + It is recommended to utilize the [`RecommendationInstantiator`](https://github.com/searchspring/snap/blob/main/packages/snap-preact/src/Instantiators/README.md) for integration of product recommendations. This method allows recommendations to be placed anywhere on the site with a single script block (requires the `bundle.js` script also). ```html - ``` -The `RecommendationInstantiator` will look for these elements on the page and attempt to inject components based on the `profile` specified. In the example above, the profile specified is the `recently-viewed` profile, and would typically be setup to display the last products viewed by the shopper. These profiles must be setup in the Searchspring Management Console (SMC) and have associated Snap templates selected. +The `RecommendationInstantiator` will look for these elements on the page and attempt to inject components based on the `profiles` specified. In the example above, the profile specified is the `recently-viewed` profile, and is set to render inside the target `.above-content`, this profile would typically be setup to display the last products viewed by the shopper. These profiles must be setup in the Searchspring Management Console (SMC) and have associated Snap templates selected. ## Recommendation Context Variables Context variables may be applied to individual recommendation profiles similar to how they are done on the integration script tag. Variables here may be required depending on the profile type utilized, and can be used to alter the results displayed by our recommendations. +### Globals Variables | Option | Value | Page | Description | |---|---|:---:|---| | products | array of SKU strings | product detail page | SKU value(s) to identify the current product(s) being viewed | | cart | array (or function that returns an array) of current cart skus | all | optional method of setting cart contents | +| shopper.id | logged in user unique identifier | all | required for personalization functionallity if not provided to the bundle (global) context | +| profiles | array of profile objects | all | required profile specific variables | + +### Profile Specific Variables +| Option | Value | Page | Description | +|---|---|:---:|---| +| profile | string | all | profile name to use | +| target | string | all | CSS selector to render component inside | | options.siteId | global siteId overwrite | all | optional global siteId overwrite | | options.categories | array of category path strings | all | optional category identifiers used in category trending recommendation profiles | | options.brands | array of brand strings | all | optional brand identifiers used in brand trending recommendation profiles | | options.branch | template branch overwrite | all | optional branch overwrite for recommendations template (advanced usage) | +| options.dedupe | boolean (default: `true`) | all | dedupe recs from other profiles in the batch | +| options.searchTerm | string | all | query to search | | options.filters | array of filters | all | optional recommendation filters | | options.realtime | boolean | all | optional update recommendations if cart contents change (requires [cart attribute tracking](https://github.com/searchspring/snap/blob/main/docs/INTEGRATION_TRACKING.md)) | | options.blockedItems | array of strings | all | SKU values to identify which products to exclude from the response | | options.batched | boolean (default: `true`)| all | only applies to recommendation context, optional disable profile from being batched in a single request, can also be set globally [via config](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Recommendation) | | options.order | number | all | optional order number for recommendation params to be added to the batched request. Profiles that do not specify an order will be placed at the end, in the occurrence they appear in the DOM. | options.limit | number (default: 20, max: 20) | all | optional maximum number of results to display, can also be set globally [via config globals](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Recommendation) | -| shopper.id | logged in user unique identifier | all | required for personalization functionallity if not provided to the bundle (global) context | -## Batching and Ordering -By default, recommendation profile results are fetched in the same API request (batch), this is done in an effort to prevent the display of duplicate products across multiple profiles. The order of the profiles in the DOM determines the priority of results for de-duplication (best recommendations). If you wish to change the order, an `order` value can be provided (lowest value has highest priority). For some profiles (like product bundles) it is important that they receive the best suggested products prior to de-duplication, for these, the `order` would be set manually so that de-duplication does not occur. -In most cases batching is the best practice, however for profiles like a mini cart (side cart) de-duplication may not be desired. Batching can be turned off per profile with a `batched: false` value. +## Batching and Ordering +By default, each script tag will fetch the recommendations for each profile it finds a target for in a single batched request. The priority order is based on the order listed in the profiles array. +In most cases batching everything is the best practice, however for profiles like a mini cart (side cart) de-duplication may not be desired. De-duplication can be turned off per profile with a `dedupe: false` value, or you can add an additional script to fetch the recommendations in a seperate batch. The example below shows how to manually specify the order and batching of specific profiles. ```html - - - - - - ``` @@ -73,46 +111,50 @@ The examples below assume that the `similar` profile has been setup in the Searc A typical "similar" profile that would display products similar to the product passed in via the `product` context variable. ```html - ``` -If tracking scripts are not in place, "also bought" profiles may require the cart contents to be provided. +If tracking scripts are not in place, "crosssell" profiles may require the cart contents to be provided. ```html - ``` If the shopper identifier is not beeing captured by the `bundle.js` context, it must be provided for proper personalization. ```html - -``` - -Having multiple scripts batched using the order context variable - -```html - - - ``` @@ -120,25 +162,31 @@ Having multiple scripts batched using the order context variable The example shown below will filter the recommendations for products matching color: blue, & red, and price range 0 - 20. ```html - ``` \ No newline at end of file diff --git a/docs/LEGACY_INTEGRATION_RECOMMENDATIONS.md b/docs/LEGACY_INTEGRATION_RECOMMENDATIONS.md new file mode 100644 index 000000000..cdcbb93ed --- /dev/null +++ b/docs/LEGACY_INTEGRATION_RECOMMENDATIONS.md @@ -0,0 +1,148 @@ +## Recommendations Integration (Legacy) + +For integrations using Snap `v0.60.0` and newer, please reference the updated [`integration docs`](https://searchspring.github.io/snap/#/integration-recommendations). + + +It is recommended to utilize the [`RecommendationInstantiator`](https://github.com/searchspring/snap/blob/main/packages/snap-preact/src/Instantiators/README.md) for integration of product recommendations. This method allows recommendations to be placed anywhere on the site with a single script block (requires the `bundle.js` script also). + +```html + +``` + +The `RecommendationInstantiator` will look for these elements on the page and attempt to inject components based on the `profile` specified. In the example above, the profile specified is the `recently-viewed` profile, and would typically be setup to display the last products viewed by the shopper. These profiles must be setup in the Searchspring Management Console (SMC) and have associated Snap templates selected. + + +## Recommendation Context Variables +Context variables may be applied to individual recommendation profiles similar to how they are done on the integration script tag. Variables here may be required depending on the profile type utilized, and can be used to alter the results displayed by our recommendations. + +| Option | Value | Page | Description | +|---|---|:---:|---| +| products | array of SKU strings | product detail page | SKU value(s) to identify the current product(s) being viewed | +| cart | array (or function that returns an array) of current cart skus | all | optional method of setting cart contents | +| options.siteId | global siteId overwrite | all | optional global siteId overwrite | +| options.categories | array of category path strings | all | optional category identifiers used in category trending recommendation profiles | +| options.brands | array of brand strings | all | optional brand identifiers used in brand trending recommendation profiles | +| options.branch | template branch overwrite | all | optional branch overwrite for recommendations template (advanced usage) | +| options.filters | array of filters | all | optional recommendation filters | +| options.realtime | boolean | all | optional update recommendations if cart contents change (requires [cart attribute tracking](https://github.com/searchspring/snap/blob/main/docs/INTEGRATION_TRACKING.md)) | +| options.blockedItems | array of strings | all | SKU values to identify which products to exclude from the response | +| options.batched | boolean (default: `true`)| all | only applies to recommendation context, optional disable profile from being batched in a single request, can also be set globally [via config](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Recommendation) | +| options.order | number | all | optional order number for recommendation params to be added to the batched request. Profiles that do not specify an order will be placed at the end, in the occurrence they appear in the DOM. +| options.limit | number (default: 20, max: 20) | all | optional maximum number of results to display, can also be set globally [via config globals](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Recommendation) | +| shopper.id | logged in user unique identifier | all | required for personalization functionallity if not provided to the bundle (global) context | + +## Batching and Ordering +By default, recommendation profile results are fetched in the same API request (batch), this is done in an effort to prevent the display of duplicate products across multiple profiles. The order of the profiles in the DOM determines the priority of results for de-duplication (best recommendations). If you wish to change the order, an `order` value can be provided (lowest value has highest priority). For some profiles (like product bundles) it is important that they receive the best suggested products prior to de-duplication, for these, the `order` would be set manually so that de-duplication does not occur. + +In most cases batching is the best practice, however for profiles like a mini cart (side cart) de-duplication may not be desired. Batching can be turned off per profile with a `batched: false` value. + +The example below shows how to manually specify the order and batching of specific profiles. + +```html + + + + + + + +``` + +## Additional Examples + +The examples below assume that the `similar` profile has been setup in the Searchspring Management Console (SMC), and that a Snap `bundle.js` script exists on the page and has been configured with a `RecommendationInstantiator`. + +A typical "similar" profile that would display products similar to the product passed in via the `product` context variable. + +```html + +``` + +If tracking scripts are not in place, "also bought" profiles may require the cart contents to be provided. + +```html + +``` + +If the shopper identifier is not beeing captured by the `bundle.js` context, it must be provided for proper personalization. + +```html + +``` + +Having multiple scripts batched using the order context variable + +```html + + + +``` + +### Filters +The example shown below will filter the recommendations for products matching color: blue, & red, and price range 0 - 20. + +```html + +``` \ No newline at end of file