Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release v0.60.1 #1164

Merged
merged 7 commits into from
Sep 12, 2024
Merged

Release v0.60.1 #1164

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0201f9d
fix(preact/instantiator/recommendation): adding fallback selector to …
korgon Sep 11, 2024
bb0212a
fix(preact-components/recommendation): adjusting logic to prevent ren…
korgon Sep 11, 2024
5b2e460
fix(client/recommend): adjusting request batching to ensure undefined…
korgon Sep 11, 2024
66a65fb
refactor(client/recommend): refactoring recommend request to better s…
korgon Sep 12, 2024
70e2ef4
refactor(preact/instantiator): updating instantiator with recommend c…
korgon Sep 12, 2024
df0dc32
docs(docs): updating documentation for recommendation integration cha…
korgon Sep 12, 2024
c25d8d0
Merge pull request #1162 from searchspring/recs-fixes
korgon Sep 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 59 additions & 15 deletions docs/INTEGRATION_LEGACY_RECOMMENDATIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,20 @@ It is recommended to utilize the [`RecommendationInstantiator`](https://github.c
</script>
```

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 `profile` specified in the script attribute. 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).


## 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.
Profile configurations are applied to recommendation via script context variables. The variables here may be required depending on the profile type utilized, and can be used to alter the results displayed by our recommendations. When multiple recommendation integration script blocks are found, a batch will be created by default, and any profile configurations NOT in the `options` variable are applied globally to all profiles.

| 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 |
| products | array of SKU strings | product detail page | SKU value(s) to identify the current product(s) being viewed (global) |
| cart | array (or function that returns an array) of current cart skus | all | optional method of setting cart contents (global) |
| blockedItems | array of strings | all | SKU values to identify which products to exclude from the response (global) |
| filters | array of filters | all | optional recommendation filters (global) |
| shopper.id | logged in user unique identifier | all | required for personalization functionallity if not provided to the bundle context (global) |
| options.siteId | siteId overwrite | all | optional siteId overwrite (will force a new batch) |
| 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) |
Expand All @@ -30,16 +33,16 @@ Context variables may be applied to individual recommendation profiles similar t
| 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.dedupe | boolean (default: `true`) | all | specify wether or not the profile should deduplicate products when in a batch |
| 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.
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` should 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.
In most cases batching is the best practice, however for profiles like a mini cart (side cart) de-duplication may not be desired. Using `dedupe` would allow for opting out of deduplication for that profile in the batch.

The example below shows how to manually specify the order and batching of specific profiles.
The example below shows how to manually specify the order of the profiles and how to dedupe them. In the example the 'bundle' profile in the batch receives the best suggestions because it has the lowest order, and the 'quick-cart' profile is not deduplicating products at all.

```html
<script type="searchspring/recommend" profile="customers-also-bought">
Expand All @@ -63,6 +66,21 @@ The example below shows how to manually specify the order and batching of specif
};
</script>

<script type="searchspring/recommend" profile="quick-cart">
products = ['product123'];
options = {
dedupe: false
};
</script>
```

Alternatively, a profile can be placed in it's own batch via the `batched: false` value. The example below shows how to place the 'quick-cart' profile into it's own batch.

```html
<script type="searchspring/recommend" profile="bundle">
products = ['product123'];
</script>

<script type="searchspring/recommend" profile="quick-cart">
products = ['product123'];
options = {
Expand All @@ -73,28 +91,28 @@ The example below shows how to manually specify the order and batching of specif

## 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`.
The examples below assume that profiles used have 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
<script type="searchspring/recommend" profile="customers-also-viewed">
products = ['product123'];
<script type="searchspring/recommend" profile="similar">
products = ['sku123'];
</script>
```

If tracking scripts are not in place, "also bought" profiles may require the cart contents to be provided.

```html
<script type="searchspring/recommend" profile="view-cart">
cart = ['product123'];
cart = ['sku456'];
</script>
```

If the shopper identifier is not beeing captured by the `bundle.js` context, it must be provided for proper personalization.

```html
<script type="searchspring/recommend" profile="view-cart">
<script type="searchspring/recommend" profile="similar">
shopper = {
id: '[email protected]'
};
Expand Down Expand Up @@ -122,7 +140,7 @@ Having multiple scripts batched using the order context variable
```

### Filters
The example shown below will filter the recommendations for products matching color: blue, & red, and price range 0 - 20.
The example shown below will filter the recommendations for products matching field `color` with a value `blue` and `red`, as well as a field `price` with a range from `0` to `20`.

```html
<script type="searchspring/recommend" profile="customers-also-bought">
Expand All @@ -146,4 +164,30 @@ The example shown below will filter the recommendations for products matching co
]
}
</script>
```

The next example shows a global filter being used, this will filter all of the profiles in the batch for products matching the field `onSale` with a value `true`; the 'similar' profile will additionally apply a filter using the field `price` with a range from `0` to `20`.

```html
<script type="searchspring/recommend" profile="customers-also-bought">
filters = [
{
type: 'value',
field: 'onSale',
value: 'true'
}
];
</script>

<script type="searchspring/recommend" profile="similar">
options = {
filters: [
{
type: 'range',
field: 'price',
value: { low: 0, high: 20 }
}
]
}
</script>
```
23 changes: 12 additions & 11 deletions docs/INTEGRATION_RECOMMENDATIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ It is recommended to utilize the [`RecommendationInstantiator`](https://github.c
profiles = [
{
profile: 'recently-viewed',
target: '.ss__recs__recently-viewed',
selector: '.ss__recs__recently-viewed',
options: {
limit: 5
}
Expand All @@ -23,7 +23,7 @@ It is recommended to utilize the [`RecommendationInstantiator`](https://github.c
</script>
```

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 `.ss__recs__recently-viewed`, 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.
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 selector `.ss__recs__recently-viewed`, 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
Expand All @@ -34,6 +34,7 @@ Context variables are applied to individual recommendation profiles similar to h
|---|---|:---:|---|:---:|
| products | array of SKU strings | product detail page | SKU value(s) to identify the current product(s) being viewed | ✔️ |
| blockedItems | array of strings | all | SKU values to identify which products to exclude from the response | |
| filters | array of filters | all | optional recommendation filters to apply to ALL profiles in the batch | |
| 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 | |

Expand All @@ -42,7 +43,7 @@ Context variables are applied to individual recommendation profiles similar to h
| Option | Value | Placement | Description | Required
|---|---|:---:|---|:---:|
| profile | string | all | profile name to use | ✔️ |
| target | string | all | CSS selector to render component inside | ✔️ |
| selector | 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 | |
Expand All @@ -55,7 +56,7 @@ Context variables are applied to individual recommendation profiles similar to h


## Batching and Ordering
Each "searchspring/recommendations" script block groups multiple recommendation profiles into a single API request, known as a batch. By default, the script tag fetches recommendations for all profiles with a matching target in one batched request. The order of profiles in the array determines their priority within the batch.
Each "searchspring/recommendations" script block groups multiple recommendation profiles into a single API request, known as a batch. By default, the script tag fetches recommendations for all profiles with a matching selector in one batched request. The order of profiles in the array determines their priority within the batch.

While batching all profiles together is generally the most efficient approach, there may be cases where separate batching is preferred. For instance, recommendations for a mini cart (side cart) might not require de-duplication with other recommendations. You can disable de-duplication for a specific profile by setting `dedupe: false` in its options, or create a separate batch by using an additional script tag.

Expand Down Expand Up @@ -83,19 +84,19 @@ Here's an example that demonstrates deduping:
profiles = [
{
profile: 'customers-also-bought',
target: '.ss__recs__crosssell',
selector: '.ss__recs__crosssell',
options: {
limit: 5
}
},
{
profile: 'customers-also-viewed',
target: '.ss__recs__similar'
selector: '.ss__recs__similar'
},
// same batch, but dedupe false
{
profile: 'customers-also-like',
target: '.ss__recs__alsoliked',
selector: '.ss__recs__alsoliked',
options: {
dedupe: false
}
Expand All @@ -118,7 +119,7 @@ A typical "similar" profile that would display products similar to the product p
profiles = [
{
profile: 'customers-also-viewed',
target: '.ss__recs__similar'
selector: '.ss__recs__similar'
}
];
</script>
Expand All @@ -134,7 +135,7 @@ If tracking scripts are not in place, "crosssell" profiles may require the cart
profiles = [
{
profile: 'customers-also-bought',
target: '.ss__recs__crosssell'
selector: '.ss__recs__crosssell'
}
];
</script>
Expand All @@ -152,7 +153,7 @@ If the shopper identifier is not beeing captured by the `bundle.js` context, it
profiles = [
{
profile: 'view-cart',
target: '.ss__recs__cart'
selector: '.ss__recs__cart'
}
];
</script>
Expand All @@ -166,7 +167,7 @@ The example shown below will filter the recommendations for products matching fi
profiles = [
{
profile: 'customers-also-bought',
target: '.ss__recs__crosssell',
selector: '.ss__recs__crosssell',
options: {
filters: [
{
Expand Down
6 changes: 2 additions & 4 deletions packages/snap-client/src/Client/Client.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,6 @@ describe('Snap Client', () => {
body: {
profiles: [
{
limit: 20,
tag: 'dress',
},
],
Expand All @@ -368,7 +367,7 @@ describe('Snap Client', () => {
},
};

const recommendCacheKey = '{"profiles":[{"tag":"dress","limit":20}],"siteId":"8uyt2m","test":true}';
const recommendCacheKey = '{"profiles":[{"tag":"dress"}],"siteId":"8uyt2m","test":true}';

expect(recommendRequesterSpy).toHaveBeenCalledTimes(2);
expect(recommendRequesterSpy.mock.calls).toEqual([
Expand Down Expand Up @@ -606,7 +605,6 @@ describe('Snap Client', () => {
body: {
profiles: [
{
limit: 20,
tag: 'dress',
},
],
Expand All @@ -615,7 +613,7 @@ describe('Snap Client', () => {
},
};

const recommendCacheKey = '{"profiles":[{"tag":"dress","limit":20}],"siteId":"8uyt2m","test":true}';
const recommendCacheKey = '{"profiles":[{"tag":"dress"}],"siteId":"8uyt2m","test":true}';

expect(recommendRequesterSpy).toHaveBeenCalledTimes(2);
expect(recommendRequesterSpy.mock.calls).toEqual([
Expand Down
Loading
Loading