You can show a set of recommendations to the customer. They are calculated by the AI engine. The profile context is retrieved automatically from the data of the profile who requested the resource that included the insert.
If you use Visual Studio Code as your editor, you can use code snippets to speed up working with inserts.
You can find the snippets in our Github repository: [https://github.com/Synerise/jinja-code-snippet](https://github.com/Synerise/jinja-code-snippet)
## Recommendations as Jinjava variable
This insert can't be used in Screen Views and Documents.
The `recommendation3` insert stores the result in a Jinjava variable and can be used in communications such as [dynamic content](/docs/campaign/dynamiccontent) or [emails](/docs/campaign/e-mail).
### Syntax
{% recommendations3 campaignId=campaign-hash %} {# replace campaign-hash with the campaign ID #}
{# logic of processing the result #}
{# the result is stored in a 'recommended_products3' variable #}
{% endrecommendations3 %}
- The items are stored as objects in the `recommended_products3` list.
You can use this list in all types of recommendations. For example, in [section recommendations](#section-recommendations) or [recommendations with slots](#recommendation-slots), `recommended_products3` lists the items without any information about slots or rows.
- The available item attributes depend on the item feed.
### Example
The following code is an example of showing recommendations on a website. The insert loops through recommendations generated for a campaign (the number of recommendations depends on the settings) and produces an HTML list of recommended items.
#### Input
where:
- line 5 opens the insert
- line 6 begins a loop that iterates over the results of the recommendation and generates HTML code to display them
- lines 7, 8, 9 ,11, 13, and 15 insert attributes of the current iterable into the generated HTML
- line 18 closes the loop
- line 19 closes the insert
#### Output
## Recommendations as JSON
This insert can be used to add recommendations only in Screen Views and Documents.
This method doesn't allow using most of the advanced options described further in this article, such as manipulating context, filters, or inserting meta tags.
This inserts a recommendation result as a JSON object:
If your campaign type is [External](/docs/ai-hub/recommendations-v2/abx-test-with-external-model), you need to provide the IDs of the items from the external model.
- The IDs must be an array of strings.
- They must be declared with `{% set %}` and used as a variable.
Example:
The recommendation type of the requested campaign is "Top items". It's configured to return one item in a slot.
The output of the generated document is the following:
## Recommendations with an item context
Some types of recommendations require an item context. If the metadata (OG tags) of the website where the recommendation is displayed include the `product:retailer_part_no` parameter, that context is read automatically.
In other situations you need to specify the context.
This can be done in two ways:
- [By using an aggregate](#ai-cart-recommendations)
- [By declaring the item IDs as a variable](#declaring-a-specific-item-context)
### Item context from an aggregate (example: cart recommendation) {#ai-cart-recommendations}
You can use an aggregate to provide the item context. The example below shows how to do it when displaying a cart recommendation. The cart page doesn't contain the item identifiers in the metadata, so an aggregate must be used to retrieve the items currently in the cart, based on `cart.status` events.
- Read about [tracking cart status](/developers/web/cart).
- The aggregate you need looks like this:
Cart status aggregate
#### Syntax
{% set itemContext = [] %}
{% aggregate aggregate-hash %}
{%- for r in aggregate_result|reverse -%}
{% set _noop = itemContext.append(r.sku) %}
{%- endfor -%}
{% endaggregate %}
{% recommendations3 campaignId=campaign-hash itemsIds=itemContext %}
{# logic of processing the result #}
{# the result is stored in a 'recommended_products3' variable #}
{% endrecommendations3 %}
where:
- line 1 creates an `itemContext` variable (array) for storing the context items.
- line 2 opens the aggregate insert.
- lines 3-5 are a loop that iterates over the results of the aggregate and add their `sku`s to `itemContext`
Cart recommendations are the only recommendation type that allows multiple items in the context. In other recommendations, only line 4 should be used (adding one item without a loop), unless the aggregate is configured to return a single value.
- line 6 closes the aggregate insert.
- line 8 opens the recommendations3 insert with the context added to the `itemsIds` parameter of the insert (this parameter must be named `itemsIds`).
You can now iterate through the results of the recommendation, as shown in the [first example in this article](#example) or below.
#### Example
The following code is an example of adding complementary item recommendations to a cart page.
**Input:**
### Declaring a specific item context
Instead of using an aggregate, you can insert the item IDs directly into a variable.
{% set itemContext = [] %}
{% set _noop = itemContext.append(item-id) %} {# replace item-id with the value you need #}
{% recommendations3 campaignId=campaign-hash itemsIds=itemContext %}
{# logic of processing the result #}
{# the result is stored in a 'recommended_products3' variable #}
{% endrecommendations3 %}
where:
- line 1 creates an `itemContext` variable (array) for storing the context items.
- line 2 adds an item ID to `itemContext`.
In cart recommendations, you can repeat this line to add more items.
- line 3 opens the recommendations3 insert with the context added to the `itemsIds` parameter of the insert (this parameter must be named `itemsIds`).
You can now iterate through the results of the recommendation, as shown in the [first example in this article](#example).
## Recommendation slots
When you use slots in recommendations, they are returned in a `slots_products3` list.
You can iterate over the items in the slot.
**Example:**
{% recommendations3 campaignId=DkhvrZoTKthD %}
{%- for slot in slots_products3 -%}
{{ slot.name }}
{%- for item in slot.items -%}
{{ item.title }}
{{ item.price.value }}
{% endfor %}
{% endfor %}
{% endrecommendations3 %}
### Selecting a particular slot
If you want to process data from a selection of slots instead of all slots in the response, you can use an IF statement and select a slot or slots by name.
In the following example, only the `foo` and `bar` slots will be displayed (if such slots exist):
{% recommendations3 campaignId=DkhvrZoTKthD %}
{%- for slot in slots_products3 -%}
{%- if (slot.name == "foo") or (slot.name == "bar") -%} {# choose slots by name #}
{# rest of the logic for displaying items from a slot #}
{%- endif -%}
{%- endfor -%}
{% endrecommendations3 %}
## Section recommendations
[Section recommendations](/docs/ai-hub/recommendations-v2/creating-section-recommendations) allow displaying personalized items on the website by displaying any number of sections.
In a section recommendation:
- A `slots_products3` list of slots is returned.
- Each slot has a `rows` list, which contains rows. Each row contains items with a certain attribute value, as defined in the recommendation settings.
- Each row has a:
- `metadata` object with information about the row (only available when a metadata catalog is added in the recommendation settings).
- `attributeValue` attribute, which lets you see the value of the item attribute used to build the section recommendation.
- `items` array with the recommended items (objects) in the row.
To obtain the data for display, you need to iterate over the slots and rows.
**Example:**
{% recommendations3 campaignId=1k2AxH0s00E9 %}
{# iterate over slots: #}
{%- for slot in slots_products3 -%}
{# iterate over rows in the slots: #}
{%- for row in slot.rows -%}
{# access row attributes and metadata: #}
{{ row.attributeValue }}
{{ row.metadata.imageLink }}
{# iterate over items in the row: #}
{%- for item in row.items -%}
{# access item attributes: #}
{{ item.itemId }}
{{ item.title }}
{% endfor %}
{% endfor %}
{% endfor %}
{% endrecommendations3 %}
## External recommendations
[External recommendations](/docs/ai-hub/recommendations-v2/abx-test-with-external-model) let you add a third-party recommendation result into A/B/X tests.
In this type of campaign, you need to provide the IDs of items selected by an external model.
- The IDs must be an array of strings.
- They must be declared with `{% set %}` and used as a variable.
Example:
{% set externalItems = ['sku1','sku2'] %}
{% recommendations3 campaignId=COhsCCOdu8Cg externalItemsIds=externalItems %}
{# logic of processing the result #}
{# the result is stored in a 'recommended_products3' variable #}
{% endrecommendations3 %}
## Filters
You can combine filters and elastic filters from the campaign with your own, or replace the campaign's filters completely.
First, define the filters to apply by using the following syntax:
{% set filters = 'param1=="value"ANDparam2!="value2"' %}
where:
- `param1=="value"` is a filter that includes (`==`) the `value` of `param1`
- `param2!="value2"` is a filter that excludes (`!=`) the `value2` of `param2`
- AND combines the two filters
- `set filters` saves the entire definition to the `filter` variable.
Now, `filters` can be added to the campaign's filters or elastic filters by using the following attributes of the recommendation insert:
- `additionalFilters`/`additionalElasticFilters` store your filters.
- `filtersJoiner`/`elasticFiltersJoiner` set the logic:
- `REPLACE` replaces the campaign's filters with your filters.
- `AND` matches if both your filters and the campaign filters are met.
- `OR` matches if at least one of the filters is met.
### Example: add to filters
This example adds the filters defined by `set filters` to the campaign's filters:
### Example: replace filter
This example generates recommendations limited to items from the `Women>Dresses` category. The original campaign's filter is replaced.
#### Input
## Open Graph meta tags in filters
You can insert the value of an OG tag into your filters.
### Syntax
{% set additionalParam = metric_additional_params["property_name"] %} {# stores value of OG tag #}
{% set filters = 'param=="' + additionalParam +'"' %} {# adds value of OG tag to your filter #}
### Example
The following example of a recommendation on a category page [replaces the campaign's filter](#filters) with a filter based on OG tags.
#### Input
{% set season = metric_additional_params["product:season"] %}
{% set filters = 'attributes.season=="' + season +'"' %}
{% recommendations3 campaignId=T5gNrNlMFC57 additionalFilters=filters filtersJoiner=REPLACE %}
{%- for p in recommended_products3 -%}
<li data-snr-ai-product-id="{{p.itemId}}">
<a class="snrs-AI--item-link" href="{{p.link}}" title="{{p.title}}">
<img src="{{ p.imageLink }}" class="products-slider__item-image snrAI-product-image snrAI-product-image-{{p.itemId}}" width="90" alt="{{p.title}}" id="snrAI-image-{{p.itemId}}">
<h3 class="snrs-AI-product--product-name">
<span class="snrs-AI-product--name-first">{{p.title}}</span>
</h3>
<span class="snrs-AI-product--season">{{p.attributes.season}}</span>
</a>
</li>
{%- endfor -%}
{% endrecommendations3 %}
