diff --git a/docs/snap-docs.json b/docs/snap-docs.json index d2711deca..95b927bca 100644 --- a/docs/snap-docs.json +++ b/docs/snap-docs.json @@ -18,7 +18,7 @@ {"name":"Context Variables","route":"/integration-context","price":0,"description":"## Context Variables\n\nContext variables are conditionally rendered within the `bundle.js` script's innerHTML via server side code or template logic. They provide various context variables that can be utilized by the Snap integration. Typically these variables are used to specify category page details (for [background filtering](https://github.com/searchspring/snap/blob/main/docs/INTEGRATION_BACKGROUND_FILTERS.md)), shopper details (for personalization), merchandising segmentation, or any other custom variables needed for the integration.\n\nThe innerHTML of the script MUST only contain variable assignments without `var`, `let`, or `const`. Each declaration should end with a semi-colon to ensure minification does not impact the functions ability to parse the innerHTML. These variables are retrieved using the [getContext](https://github.com/searchspring/snap/tree/main/packages/snap-toolbox/src/getContext) function at run time.\n\nThere are a few core context variables utilized by Snap, `shopper`, `merchandising` and `config` - these are reserved context variable names and should not be utilized for custom context functionality.\n\n| Option | Value | Page | Description |\n|---|---|:---:|---|\n| shopper.id | logged in user unique identifier | all | required for personalization functionallity |\n| shopper.cart | array of cart objects, each object in the array can contain `sku` and/or `childSku` | all | current cart contents, required if checkout process does not contain a dedicated cart page (ie. slideout cart) |\n| currency.code | currency code string, ie. 'EUR' (ISO 4217) | all | currency code of the shopper's cart contents or order confirmation. Used for beacon events containing pricing data |\n| merchandising.segments | array of strings used for merchandising | any | segmented merchandising allows for custom control over products returned on search requests and must also be setup within the Searchspring Management Console (SMC) |\n| config | object containing Snap configurations | any | advanced usage of Snap (not recommended for standard integrations) |\n\n## Examples\n\nThe custom variable example below shows a custom context being added for 'page'. The value would typically be assigned server side using template logic. This would be used to possibly toggle the siteId utilized by the client (to fetch different catalog data) or to modify text or currency displays.\n\n```html\n\n```\n\nWhen used, shopper context should always include at least an `id`; the `cart` contents can optionally be provided to ensure personalization is applied on every page. Standard Snap integrations will automatically take this context data and apply it for personalization.\n\n```html\n\n```\n\nMerchandising segmentation will automatically be applied if passed in via a script context variable. Standard Snap integrations will automatically take this context data and apply it for merchandising.\n\n```html\n\n```\n\nExample using multiple context variables together.\n\n```html\n\n```","image":"","sku":"sku/integration-context","id":"/integration-context","categoryHierarchy":"Getting Started > Integration > Context Variables"} {"name":"Background Filters","route":"/integration-backgroundFilters","price":0,"description":"## Background Filters\nBackground filters allow a page to be refined without displaying the active filter to the end-user. This is primarily used for category pages, although can also be used for custom functionality such as restricting visibility of products to user groups. The filter value is commonly retrieved from a context variable and applied as a background filter within the Snap config object.\n\nIn this example, we'll retrieve the `collection` object from the context and apply it as a category background filter for our search controller.\n\n\n```html\n\n```\n\n```typescript\nimport { getContext } from '@searchspring/snap-toolbox';\n\nconst context = getContext(['collection']);\nconst backgroundFilters = [];\n\nif (context.collection?.handle) {\n\t// set background filter\n\tif (context.collection.handle != 'all') {\n\t\tbackgroundFilters.push({\n\t\t\tfield: 'collection_handle',\n\t\t\tvalue: context.collection.handle,\n\t\t\ttype: 'value',\n\t\t\tbackground: true,\n\t\t});\n\t}\n}\n\nconst config = {\n\tclient: {\n\t\tglobals: {\n\t\t\tsiteId: 'abc123',\n\t\t},\n\t},\n\tcontrollers: {\n\t\tsearch: [\n\t\t\t{\n\t\t\t\tconfig: {\n\t\t\t\t\tid: 'search',\n\t\t\t\t\tglobals: {\n\t\t\t\t\t\tfilters: backgroundFilters,\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t],\n\t},\n};\n\nconst snap = new Snap(config);\n```\n\nBackground filters could also be applied to all services by setting `client.globals.filters` in the Snap config instead of on a per-controller basis.","image":"","sku":"sku/integration-backgroundFilters","id":"/integration-backgroundFilters","categoryHierarchy":"Getting Started > Integration > Background Filters"} {"name":"Foreground Filters","route":"/integration-foregroundFilters","price":0,"description":"## Foreground Filters\n***Note:*** **Foreground filters are only usable with a SearchController.**\n\nForeground filters provide a way for pre-applying a filter on page load. The applied filter will be applied to the URL and can be removed as any other applied filter would. Foreground filtering is accomplished by setting the inital UrlManager state; this can be used for setting various states, but only filtering will be covered in this document.\n\nIn the simplified example below, a foreground filter is used to pre-apply a filter for the `on_sale` field. \n\n```typescript\nconst config = {\n\tclient: {\n\t\tglobals: {\n\t\t\tsiteId: 'abc123',\n\t\t},\n\t},\n\tcontrollers: {\n\t\tsearch: [\n\t\t\t{\n\t\t\t\turl: {\n\t\t\t\t\tinitial: {\n\t\t\t\t\t\tparameters: {\n\t\t\t\t\t\t\tfilter: {\n\t\t\t\t\t\t\t\tstate: {\n\t\t\t\t\t\t\t\t\ton_sale: ['yes'],\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\tconfig: {\n\t\t\t\t\tid: 'search',\n\t\t\t\t},\n\t\t\t},\n\t\t],\n\t},\n};\n\nconst snap = new Snap(config);\n```\n\n\nThe `initial.parameters` object is keyed by `UrlManager` state parameters - such as filter, sort, page, and pageSize. Any valid `UrlManager` state parameters are available for usage here, even custom parameters; however, filter is the most likely to be used here.\n\nThere is also an optional `ignoreParameter` param you can set on the `initial.settings` object, this allows for specifying additional UrlManager state parameters to be added to the ignore list. See example where the `initial.state` filter `on_sale:yes` will be set even if there are other `filter` params present in the UrlManager state. The default values in the `ignoreParameter` are `query`, `tag`, `oq` and `fallbackQuery`. This list is used to determine wether or not to apply the initial state provided - if the UrlManager state contains any states that are not being ignored, the initial state will not be applied.\n\n```typescript\nconst config = {\n\tclient: {\n\t\tglobals: {\n\t\t\tsiteId: 'abc123',\n\t\t},\n\t},\n\tcontrollers: {\n\t\tsearch: [\n\t\t\t{\n\t\t\t\turl: {\n\t\t\t\t\tinitial: {\n\t\t\t\t\t\tsettings: {\n\t\t\t\t\t\t\tignoreParameters: ['filter'],\n\t\t\t\t\t\t},\n\t\t\t\t\t\tparameters: {\n\t\t\t\t\t\t\tfilter: {\n\t\t\t\t\t\t\t\tstate: {\n\t\t\t\t\t\t\t\t\ton_sale: ['yes'],\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\tconfig: {\n\t\t\t\t\tid: 'search',\n\t\t\t\t},\n\t\t\t},\n\t\t],\n\t},\n};\n\nconst snap = new Snap(config);\n```\n\n## Advanced Configuration\nAdditional advanced configuration is available for special use cases. If you do not wish to use the default `ignoreParameters` you can specify as much using `initial.settings.useDefaultIgnoreParameters`, and setting it to `false`.\n\nMore configuration can be made within each `initial.parameter` object. It is possible to specify individual `ignoreParameters` here, which allows for more control for when to apply each individual initial state. Within the parameter configuration it is also possible to opt out of the 'global' `ignoreParameter` settings specified in `initial.settings` by using the `useGlobalIgnoreParameters` configuration. Lastly, there may be cases where it is necessary to replace existing state values instead of merging them (the default action). This is specified in each individual parameter configuration via the `action` configuration; this supports a `merge` or `set` value.\n\nExample using advanced configurations shown below:\n\n```typescript\nconst config = {\n\tclient: {\n\t\tglobals: {\n\t\t\tsiteId: 'abc123',\n\t\t},\n\t},\n\tcontrollers: {\n\t\tsearch: [\n\t\t\t{\n\t\t\t\turl: {\n\t\t\t\t\tinitial: {\n\t\t\t\t\t\tsettings: {\n\t\t\t\t\t\t\tignoreParameters: ['query', 'tag', 'filter'],\n\t\t\t\t\t\t\tuseDefaultIgnoreParameters: false,\n\t\t\t\t\t\t},\n\t\t\t\t\t\tparameters: {\n\t\t\t\t\t\t\tfilter: {\n\t\t\t\t\t\t\t\tuseGlobalIgnoreParameters: true,\n\t\t\t\t\t\t\t\taction: 'set',\n\t\t\t\t\t\t\t\tstate: {\n\t\t\t\t\t\t\t\t\ton_sale: ['yes'],\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\tconfig: {\n\t\t\t\t\tid: 'search',\n\t\t\t\t},\n\t\t\t},\n\t\t],\n\t},\n};\n\nconst snap = new Snap(config);\n```","image":"","sku":"sku/integration-foregroundFilters","id":"/integration-foregroundFilters","categoryHierarchy":"Getting Started > Integration > Foreground Filters"} -{"name":"Recommendations","route":"/integration-recommendations","price":0,"description":"## Recommendations Integration\nIt 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 (standard when using Snap object).\n\nChanges to the recommendation integration scripts were made in Snap `v0.60.0`. Legacy Recommmendation Integrations docs can still be found [`here`](https://github.com/searchspring/snap/blob/main/docs/INTEGRATION_LEGACY_RECOMMENDATIONS.md)\n\nRecommendations script blocks can be placed anywhere on the page and will automatically target and batch requests for all profiles specified in the block (requires the `bundle.js` script also). Batching profiles is important for deduplication of recommended products (see more below).\n\nThe block below uses the `recently-viewed` profile which would typically be setup to display the last products viewed by the shopper. Profiles must be setup in the Searchspring Management Console (SMC) and have associated Snap templates selected.\n\n```html\n\n\n
\n```\n\nThe `RecommendationInstantiator` will look for these script blocks on the page and attempt to inject components based on the `selector` specified in each profile. In the example above, the profile specified is the `recently-viewed` profile, and is set to render inside the `.ss__recs__recently-viewed` element just below the script block. The targeted element could exist anywhere on the page - but it is recommended to group elements with script blocks whenever possible (for easy integration identification). The component to render into the targeted `selector` is setup within the `RecommendationInstantiator` configuration.\n\n\n## Recommendation Context Variables\nContext variables are set within the script blocks and can be used to set either global or per profile (profile specific) functionality. Variables are used to alter the results displayed by our recommendations and may be required depending on the profile placements in use.\n\n### Globals Variables\n| Option | Value | Placement | Description | Required\n|---|---|:---:|---|:---:|\n| products | array of SKU strings | product detail page | SKU value(s) to identify the current product(s) being viewed | ✔️ |\n| blockedItems | array of strings | all | SKU values to identify which products to exclude from the response | |\n| filters | array of filters | all | optional recommendation filters to apply to ALL profiles in the batch | |\n| cart | array (or function that returns an array) of current cart skus | all | optional method of setting cart contents | |\n| shopper.id | logged in user unique identifier | all | required for personalization functionallity if not provided to the bundle (global) context | |\n\n\n### Profile Specific Variables\n| Option | Value | Placement | Description | Required\n|---|---|:---:|---|:---:|\n| profile | string | all | profile name to use | ✔️ |\n| selector | string | all | CSS selector to render component inside | ✔️ |\n| options.siteId | global siteId overwrite | all | optional global siteId overwrite | |\n| options.categories | array of category path strings | all | optional category identifiers used in category trending recommendation profiles | |\n| options.brands | array of brand strings | all | optional brand identifiers used in brand trending recommendation profiles | |\n| options.blockedItems | array of strings | all | SKU values to identify which products to exclude from the profile response | |\n| options.branch | template branch overwrite | all | optional branch overwrite for recommendations template (advanced usage) | |\n| options.dedupe | boolean (default: `true`) | all | dedupe products across all profiles in the batch | |\n| options.query | string | dynamic custom | query to search | |\n| options.filters | array of filters | all | optional recommendation filters | |\n| 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)) | |\n| 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) | |\n\n\n## Batching and Ordering\nEach \"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.\n\nWhile 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.\n\n## Deduping\n\nDeduping is a process that prevents the same product from appearing in multiple recommendation profiles within a single batch. This is particularly useful when you have several recommendation profiles on a page and want to ensure a diverse range of products is shown to the user.\n\nHere's how deduping works:\n\n1. By default, deduping is enabled for all profiles in a batch (`options.dedupe: true`).\n2. The order of profiles in the array determines their priority for deduping.\n3. When a product is returned for a higher-priority profile, it becomes unavailable for lower-priority profiles in the same batch.\n\nFor example, if you have three profiles in this order: \"Customers Also Bought\", \"Similar Products\", and \"You May Also Like\", and a product is returned for \"Customers Also Bought\", it won't appear in \"Similar Products\" or \"You May Also Like\".\n\nYou can disable deduping for specific profiles by setting `options.dedupe: false`. This is useful for profiles where you want to ensure certain products always appear, regardless of their presence in other recommendations.\n\nHere's an example that demonstrates deduping:\n\n```html\n\n```\n\n## Additional Examples\n\nThe 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`.\n\nA typical \"similar\" profile that would display products similar to the product passed in via the `products` global context variable.\n\n```html\n\n```\n\nIf tracking scripts are not in place, \"crosssell\" profiles may require the cart contents to be provided.\n\n```html\n\n```\n\nIf the shopper identifier is not beeing captured by the `bundle.js` context, it must be provided for proper personalization.\n\n```html\n\n```\n\n### Filters\nThe 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`.\n\n```html\n\n```","image":"","sku":"sku/integration-recommendations","id":"/integration-recommendations","categoryHierarchy":"Getting Started > Integration > Recommendations"} +{"name":"Recommendations","route":"/integration-recommendations","price":0,"description":"## Recommendations Integration\nIt 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 (standard when using Snap object).\n\nChanges to the recommendation integration scripts were made in Snap `v0.60.0`. Legacy Recommmendation Integrations docs can still be found [`here`](https://github.com/searchspring/snap/blob/main/docs/INTEGRATION_LEGACY_RECOMMENDATIONS.md)\n\nRecommendations script blocks can be placed anywhere on the page and will automatically target and batch requests for all profiles specified in the block (requires the `bundle.js` script also). Batching profiles is important for deduplication of recommended products (see more below).\n\nThe block below uses the `recently-viewed` profile which would typically be setup to display the last products viewed by the shopper. Profiles must be setup in the Searchspring Management Console (SMC) and have associated Snap templates selected.\n\n```html\n\n\n\n```\n\nThe `RecommendationInstantiator` will look for these script blocks on the page and attempt to inject components based on the `selector` specified in each profile. In the example above, the profile specified is the `recently-viewed` profile, and is set to render inside the `.ss__recs__recently-viewed` element just below the script block. The targeted element could exist anywhere on the page - but it is recommended to group elements with script blocks whenever possible (for easy integration identification). The component to render into the targeted `selector` is setup within the `RecommendationInstantiator` configuration. The targeted element should be given a `min-height` inline style to prevent cumulative layout shift.\n\n\n## Recommendation Context Variables\nContext variables are set within the script blocks and can be used to set either global or per profile (profile specific) functionality. Variables are used to alter the results displayed by our recommendations and may be required depending on the profile placements in use.\n\n### Globals Variables\n| Option | Value | Placement | Description | Required\n|---|---|:---:|---|:---:|\n| products | array of SKU strings | product detail page | SKU value(s) to identify the current product(s) being viewed | ✔️ |\n| blockedItems | array of strings | all | SKU values to identify which products to exclude from the response | |\n| filters | array of filters | all | optional recommendation filters to apply to ALL profiles in the batch | |\n| cart | array (or function that returns an array) of current cart skus | all | optional method of setting cart contents | |\n| shopper.id | logged in user unique identifier | all | required for personalization functionallity if not provided to the bundle (global) context | |\n\n\n### Profile Specific Variables\n| Option | Value | Placement | Description | Required\n|---|---|:---:|---|:---:|\n| profile | string | all | profile name to use | ✔️ |\n| selector | string | all | CSS selector to render component inside | ✔️ |\n| options.siteId | global siteId overwrite | all | optional global siteId overwrite | |\n| options.categories | array of category path strings | all | optional category identifiers used in category trending recommendation profiles | |\n| options.brands | array of brand strings | all | optional brand identifiers used in brand trending recommendation profiles | |\n| options.blockedItems | array of strings | all | SKU values to identify which products to exclude from the profile response | |\n| options.branch | template branch overwrite | all | optional branch overwrite for recommendations template (advanced usage) | |\n| options.dedupe | boolean (default: `true`) | all | dedupe products across all profiles in the batch | |\n| options.query | string | dynamic custom | query to search | |\n| options.filters | array of filters | all | optional recommendation filters | |\n| 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)) | |\n| 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) | |\n\n\n## Batching and Ordering\nEach \"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.\n\nWhile 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.\n\n## Deduping\n\nDeduping is a process that prevents the same product from appearing in multiple recommendation profiles within a single batch. This is particularly useful when you have several recommendation profiles on a page and want to ensure a diverse range of products is shown to the user.\n\nHere's how deduping works:\n\n1. By default, deduping is enabled for all profiles in a batch (`options.dedupe: true`).\n2. The order of profiles in the array determines their priority for deduping.\n3. When a product is returned for a higher-priority profile, it becomes unavailable for lower-priority profiles in the same batch.\n\nFor example, if you have three profiles in this order: \"Customers Also Bought\", \"Similar Products\", and \"You May Also Like\", and a product is returned for \"Customers Also Bought\", it won't appear in \"Similar Products\" or \"You May Also Like\".\n\nYou can disable deduping for specific profiles by setting `options.dedupe: false`. This is useful for profiles where you want to ensure certain products always appear, regardless of their presence in other recommendations.\n\nHere's an example that demonstrates deduping:\n\n```html\n\n```\n\n## Additional Examples\n\nThe 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`.\n\nA typical \"similar\" profile that would display products similar to the product passed in via the `products` global context variable.\n\n```html\n\n```\n\nIf tracking scripts are not in place, \"crosssell\" profiles may require the cart contents to be provided.\n\n```html\n\n```\n\nIf the shopper identifier is not beeing captured by the `bundle.js` context, it must be provided for proper personalization.\n\n```html\n\n```\n\n### Filters\nThe 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`.\n\n```html\n\n```","image":"","sku":"sku/integration-recommendations","id":"/integration-recommendations","categoryHierarchy":"Getting Started > Integration > Recommendations"} {"name":"Recommendations (legacy)","route":"/integration-legacy-recommendations","price":0,"description":"## Recommendations Integration (Legacy)\n\nFor integrations using Snap `v0.60.0` and newer, please reference the updated [`integration docs`](https://github.com/searchspring/snap/blob/main/docs/INTEGRATION_RECOMMENDATIONS.md).\n\n\nIt 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).\n\n```html\n\n```\n\nThe `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).\n\n\n## Recommendation Context Variables\nProfile 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.\n\n| Option | Value | Page | Description |\n|---|---|:---:|---|\n| products | array of SKU strings | product detail page | SKU value(s) to identify the current product(s) being viewed (global) |\n| cart | array (or function that returns an array) of current cart skus | all | optional method of setting cart contents (global) |\n| blockedItems | array of strings | all | SKU values to identify which products to exclude from the response (global) |\n| filters | array of filters | all | optional recommendation filters (global) |\n| shopper.id | logged in user unique identifier | all | required for personalization functionallity if not provided to the bundle context (global) |\n| options.siteId | siteId overwrite | all | optional siteId overwrite (will force a new batch) |\n| options.categories | array of category path strings | all | optional category identifiers used in category trending recommendation profiles |\n| options.brands | array of brand strings | all | optional brand identifiers used in brand trending recommendation profiles |\n| options.branch | template branch overwrite | all | optional branch overwrite for recommendations template (advanced usage) |\n| options.filters | array of filters | all | optional recommendation filters |\n| options.query | string | all | query to search |\n| 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)) |\n| options.blockedItems | array of strings | all | SKU values to identify which products to exclude from the response |\n| 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) | \n| options.dedupe | boolean (default: `true`) | all | specify wether or not the profile should deduplicate products when in a batch |\n| 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.\n| 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) |\n\n## Batching and Ordering\nBy 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.\n\nIn 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. \n\nThe 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.\n\n```html\n\n\n\n\n\n\n\n```\n\nAlternatively, 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.\n\n```html\n\n\n\n```\n\n## Additional Examples\n\nThe 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`.\n\nA typical \"similar\" profile that would display products similar to the product passed in via the `product` context variable.\n\n```html\n\n```\n\nIf tracking scripts are not in place, \"also bought\" profiles may require the cart contents to be provided.\n\n```html\n\n```\n\nIf the shopper identifier is not beeing captured by the `bundle.js` context, it must be provided for proper personalization.\n\n```html\n\n```\n\nHaving multiple scripts batched using the order context variable\n\n```html\n\n\n\n```\n\n### Filters\nThe 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`.\n\n```html\n\n```\n\nThe 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`.\n\n```html\n\n\n\n```","image":"","sku":"sku/integration-legacy-recommendations","id":"/integration-legacy-recommendations","categoryHierarchy":"Getting Started > Integration > Recommendations (legacy)"} {"name":"Tracking","route":"/integration-tracking","price":0,"description":"## Tracking\nCertain reports depend on beacon data being tracked. These are events tracked outside of the integration code and should be added to various pages. These tracking methods require that our `bundle.js` script exist on the pages where utilized.\n\n### Shopper Login\nIdentifies the logged-in user. Should be invoked if a user is logged into their account. The value should contain any unique identifier (ie. user ID, email, hash)\n\n```html\n\n```\n\nAlternatively, this can also be integrated using the global `searchspring.tracker.track.shopper.login` methods.\n\n```typescript\nsearchspring.tracker.track.shopper.login({\n\tid: 'snapdev'\n});\n```\n\n### Product View\nTracks product page views. Should only be installed on product detail pages. A `uid` and/or `sku` and/or `childSku` and/or `childUid` are required (provide as many of these product identifiers that are available).\n\n```html\n\n```\n\nAlternatively, this can also be integrated using the `searchspring.tracker.track.product.view` method\n\n```typescript\nsearchspring.tracker.track.product.view({\n\tuid: '123',\n\tsku: 'product123',\n\tchildUid: '123_a',\n\tchildSku: 'product123_a'\n});\n```\n\n\n### Cart View \nTracks cart contents. Should only be installed on a cart page. If the checkout process does not contain a dedicated cart page (ie. slideout cart) then this method should be invoked when the cart comes into view. \n\nEach item object must contain a `qty`, `price`, (`uid` and/or `sku` and/or `childSku` and/or `childUid` - provide as many of these product identifiers that are available).\n\n```html\n\n```\n\nAlternatively, this can also be integrated using the `searchspring.tracker.track.cart.view` method.\n\n```typescript\nsearchspring.tracker.track.cart.view({\n\titems: [\n\t\t{\n\t\t\tuid: '123',\n\t\t\tsku: 'product123',\n\t\t\tchildUid: '123_a',\n\t\t\tchildSku: 'product123_a',\n\t\t\tqty: '1',\n\t\t\tprice: '9.99',\n\t\t},\n\t\t{\n\t\t\tuid: '456',\n\t\t\tsku: 'product456',\n\t\t\tchildUid: '456_a',\n\t\t\tchildSku: 'product456_a',\n\t\t\tqty: '2',\n\t\t\tprice: '10.99',\n\t\t},\n\t]\n});\n```\n\n\n### Order Transaction\nTracks order transaction. Should be invoked from an order confirmation page. Expects an object with the following:\n\n`order` - (optional) object containing the following\n\n`order.id` - (optional) order id\n\n`order.total` - (optional) transaction total of all items after tax and shipping\n\n`order.transactionTotal` - (optional) transaction total of all items before tax and shipping\n\n`order.city` - (optional) city name\n\n`order.state` - (optional) 2 digit state abbreviation (US only)\n\n`order.country` - (optional) 2 digit country abbreviation\t(ie. 'US', 'CA', 'MX', 'PL', 'JP')\n\n`order.items` - required array of items - same object provided to `track.cart.view` event\n\n```html\n\n```\n\nAlternatively, this can also be integrated using the `searchspring.tracker.track.order.transaction` method\n\n```typescript\nsearchspring.tracker.track.order.transaction({\n\torder: {\n\t\tid: '123456',\n\t\ttotal: '34.29',\n\t\ttransactionTotal: '31.97',\n\t\tcity: 'Los Angeles',\n\t\tstate: 'CA',\n\t\tcountry: 'US',\n\t},\n\titems: [\n\t\t{\n\t\t\tuid: '123',\n\t\t\tsku: 'product123',\n\t\t\tchildUid: '123_a',\n\t\t\tchildSku: 'product123_a',\n\t\t\tqty: '1',\n\t\t\tprice: '9.99'\n\t\t},\n\t\t{\n\t\t\tuid: '456',\n\t\t\tsku: 'product456',\n\t\t\tchildUid: '456_a',\n\t\t\tchildSku: 'product456_a',\n\t\t\tqty: '2',\n\t\t\tprice: '10.99'\n\t\t},\n\t]\n});\n```\n\n\n### Product Click\nTracks product click events. This event can be included within the Snap integration. It is reccomended to invoke on each product `onmousedown` event via the `result.track.click()` method. \n\n```jsx\nsearchController.store.results.map(result)=>{(\n\t{searchController.track.product.click(e, result)}}>\n)}\n```\n\nAlternatively, this can also be integrated using the `ss-track-intellisuggest` and `ss-track-intellisuggest-signature` attributes.\n\n```jsx\nsearchController.store.results.map(result)=>{(\n\t\n)}\n```\n\n\nAlternatively, this can also be integrated using the `searchspring.tracker.track.product.click` method. \n\nThe `intellisuggestData` and `intellisuggestSignature` values are returned from SearchSpring's Search API on each `result.attributes` object. An optional `href` value can also be provided. \n\n```typescript\nsearchspring.tracker.track.product.click({\n\tintellisuggestData: '37d5578e1d1646ac97701a063ba84777',\n\tintellisuggestSignature: '5739a2596d3b4161b041ce1764ffa04d',\n\thref: '/product123',\n});\n```\n\n\n## Cart Attribute Tracking\n\nThis is not required if the above `Cart View` and `Order Transaction` tracking has not been implemented OR you are not using the `realtime` recommendations configuration. \n\nAdding the following attributes to clickable cart elements allows for real-time updates to any recommendations (disabled by default) when the cart changes. If the click event occurs on a nested element, the attribute data will attempt to be retrieved from up to 3 parent nodes.\n\nIf you are using multiple custom Tracker instances with a different tracker `config.id`, attributes are namespaced by the trackers `id` (Default: `'track'`, Example: `ss-track-cart-add`)\n\n### Add to cart\nAdds product `uid` or `sku` (or `childSku`/`childUid`) to `ssCartProducts` cookie. It is preferable to use the more specific variant `childSku` or `childUid` if available. Supports multiple products using a comma delimiter.\n\n```html\n\n```\n\nAlternatively, this can also be integrated using the `searchspring.tracker.cookies.cart.add` method\n\n```typescript\nsearchspring.tracker.cookies.cart.add(['product123'])\n```\n\n\n### Remove from cart\nRemoves product `uid` or `sku` (or `childSku`/`childUid`) to `ssCartProducts` cookie. It is preferable to use the more specific variant `childSku` or `childUid` if available. Supports multiple products using a comma delimiter.\n\n```html\n\n```\n\nAlternatively, this can also be integrated using the `searchspring.tracker.cookies.cart.remove` method\n\n```typescript\nsearchspring.tracker.cookies.cart.remove(['product123'])\n```\n\n\n### Clear cart\nClears all products currently stored in the `ssCartProducts` cookie.\n\n```html\n\n```\n\nAlternatively, this can also be integrated using the `searchspring.tracker.cookies.cart.remove` method\n\n```typescript\nsearchspring.tracker.cookies.cart.clear()\n```\n\n### View cart\nAllows for real-time updates to any recommendations when an element with this attribute is clicked.\n\n```html\n\n```\n","image":"","sku":"sku/integration-tracking","id":"/integration-tracking","categoryHierarchy":"Getting Started > Integration > Tracking"} {"name":"Debugging","route":"/integration-debugging","price":0,"description":"## Debugging\n\n## Branch Overrides \n\nThis functionality is only currently possible with Searchspring managed Snap repositories (https://github.com/searchspring-implementations).\n\nWhile browsing a page that contains a Snap integration, appending the `?branch=[branchname]` query parameter to the URL will stop the execution of the existing script, and load the build from the `[branchname]` branch `https://snapui.searchspring.io/[siteid]/[branchname]/bundle.js`\n\nYou will see an interface overlay on the bottom right of the viewport indicating if successful and details of the build.\n\n\n\nThis will also be persisted across page navigation. To stop previewing a branch build, you must click the `Stop Preview` button in the interface or clear the `ssBranch` cookie. The interface can also be minimized. \n\n\n## Development Mode\n\nWhile browsing a page that contains a Snap integration, appending the `?dev` query parameter to the URL will set the controller's `environment` property to `development`. \n\nThis is commonly used to enable visibility of development logs in the console. \n\nSee [AbstractController](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Abstract) and [@searchspring/snap-logger](https://github.com/searchspring/snap/tree/main/packages/snap-logger)\n\n","image":"","sku":"sku/integration-debugging","id":"/integration-debugging","categoryHierarchy":"Getting Started > Integration > Debugging"} diff --git a/packages/snap-client/docs/classes/Client.html b/packages/snap-client/docs/classes/Client.html index 40ab5f3ce..9c1f6ae6d 100644 --- a/packages/snap-client/docs/classes/Client.html +++ b/packages/snap-client/docs/classes/Client.html @@ -1,4 +1,4 @@ -Private
configPrivate
globalsPrivate
modePrivate
requestersGenerated using TypeDoc
Private
configPrivate
globalsPrivate
modePrivate
requestersGenerated using TypeDoc
Optional
autocomplete?: RequesterConfig<AutocompleteRequestModel> & { Optional
fetchOptional
finder?: RequesterConfig<SearchRequestModel>Optional
meta?: RequesterConfig<MetaRequestModel>Optional
mode?: keyof typeof AppMode | AppModeOptional
recommend?: RequesterConfig<RecommendRequestModel>Optional
search?: RequesterConfig<SearchRequestModel>Optional
suggest?: RequesterConfig<SuggestRequestModel>Generated using TypeDoc
Optional
autocomplete?: RequesterConfig<AutocompleteRequestModel> & { Optional
fetchOptional
finder?: RequesterConfig<SearchRequestModel>Optional
meta?: RequesterConfig<MetaRequestModel>Optional
mode?: keyof typeof AppMode | AppModeOptional
recommend?: RequesterConfig<RecommendRequestModel>Optional
search?: RequesterConfig<SearchRequestModel>Optional
suggest?: RequesterConfig<SuggestRequestModel>Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Optional
profile?: RecommendRequestOptionsModelGenerated using TypeDoc
Optional
profile?: RecommendRequestOptionsModelGenerated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Abstract
Abstract
Protected
_initializedRest
...args: unknown[]Abstract
searchGenerated using TypeDoc
Protected
_initializedRest
...args: unknown[]Abstract
searchGenerated using TypeDoc
Optional
context: ContextVariablesProtected
_initializedRest
...args: unknown[]Generated using TypeDoc
Optional
context: ContextVariablesProtected
_initializedRest
...args: unknown[]Generated using TypeDoc
Optional
context: ContextVariablesProtected
_initializedRest
...args: unknown[]Generated using TypeDoc
Optional
context: ContextVariablesProtected
_initializedRest
...args: unknown[]Generated using TypeDoc
Optional
context: ContextVariablesProtected
_initializedOptional
click?: BeaconEventOptional
impression?: BeaconEventOptional
product?: Record<string, { Optional
render?: BeaconEventRest
...args: unknown[]Generated using TypeDoc
Optional
context: ContextVariablesProtected
_initializedOptional
click?: BeaconEventOptional
impression?: BeaconEventOptional
product?: Record<string, { Optional
render?: BeaconEventRest
...args: unknown[]Generated using TypeDoc
Optional
context: ContextVariablesProtected
_initializedPrivate
previousRest
...args: unknown[]Generated using TypeDoc
Optional
context: ContextVariablesProtected
_initializedPrivate
previousRest
...args: unknown[]Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Optional
middleware?: { Optional
plugins?: PluginGrouping[]Generated using TypeDoc
Optional
middleware?: { Optional
plugins?: PluginGrouping[]Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Optional
shopper?: { Optional
cart?: ProductViewEvent[]Generated using TypeDoc
Optional
shopper?: { Optional
cart?: ProductViewEvent[]Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Optional
domOptional
href?: stringOptional
selector?: stringGenerated using TypeDoc
Optional
domOptional
href?: stringOptional
selector?: stringGenerated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Rest
...args: anyGenerated using TypeDoc
Rest
...args: anyGenerated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Optional
element?: ElementPositionObjGenerated using TypeDoc
Optional
element?: ElementPositionObjGenerated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Const
Generated using TypeDoc
Const
Generated using TypeDoc
Rest
...func: Middleware<T>[]Generated using TypeDoc
Rest
...func: Middleware<T>[]Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Optional
config: LoggerConfigPrivate
modePrivate
prefixGenerated using TypeDoc
Optional
config: LoggerConfigPrivate
modePrivate
prefixGenerated using TypeDoc
Optional
mode?: keyof typeof AppMode | AppModeOptional
prefix?: stringGenerated using TypeDoc
Optional
mode?: keyof typeof AppMode | AppModeOptional
prefix?: stringGenerated using TypeDoc
Const
Generated using TypeDoc
Const
Generated using TypeDoc
Const
Generated using TypeDoc
Const
Generated using TypeDoc