> For the complete documentation index, see [llms.txt](https://docs.abtasty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abtasty.com/commerce/widget-implementation.md).

# Widget implementation

Once a strategy is built and deployed in Commerce, you still need to surface its results to your visitors. **Widget implementation** is about that last step: getting recommendation, merchandising, and search results onto your site or into your emails.

There are three web integration methods, ordered from least to most code: the **Custom Widget** (no-/low-code), the **tag plus custom JavaScript**, and the **headless API**. Email deployment and the Search widget are covered at the end.

{% hint style="warning" %}
At the time of writing, the in-app **Widget implementation** page (opened from the left navigation) returned "Page not found" in the demo environment. The deployment methods below are documented from the existing implementation guides and should be re-verified against the live page once it is available.
{% endhint %}

{% hint style="info" %}
**What you need before deploying:** the AB Tasty unified tag installed on your site, and the identifier of the strategy you want to display, a `RECO_ID` for a recommendation strategy or a `MERCH_ID` for a merchandising strategy. You can copy these from the strategy list in Creating strategies. Verify the tag is present by opening the browser console and typing `recos`, you should see a global context object.
{% endhint %}

### Method 1: Custom Widget (no-/low-code)

The fastest path. AB Tasty provides a pre-configured **Custom Widget** component that handles the API call and the HTML/CSS rendering for you. Marketing teams can manage the banner from the visual editor without writing code.

**Procedure:**

1. Open the **AB Tasty campaign editor**.
2. Add the provided **Custom Widget** to your campaign.
3. Link it to the corresponding `RECO_ID` to display the recommendation banner.

Your banner is now live, using the Custom Widget and the recommendation tag. The `RECO_ID` is the unique identifier found in the strategy list.

### Method 2: Tag plus custom JavaScript

For full control over markup while keeping AB Tasty's data layer and automatic tracking, use the unified tag together with custom JavaScript. The tag collects context variables; you retrieve the products and render your own HTML/CSS.

**Retrieve the products** by calling `recos.reco(RECO_ID)`, which returns a Promise resolving to the product list:

```js
recos.reco("5a936bc0-fbd1-4048-81a8-b94da73178e2").then(console.log);
// → JSON product list (id, name, price, img_link, link, …)
```

**Render your banner and enrich it with data attributes** so the AB Tasty tag can auto-detect impressions and clicks:

```html
<div data-reco-id="[RECO_ID]" data-reco-name="[RECO_NAME]">
  <a href="..."
     data-item-id="[ITEM_ID]"
     data-reco-click="go_to_page">
    <!-- product card markup -->
  </a>
</div>
```

| Attribute         | Purpose                                  | Required |
| ----------------- | ---------------------------------------- | -------- |
| `data-reco-id`    | Identifies the recommendation container. | Yes      |
| `data-item-id`    | Identifies a specific product.           | Yes      |
| `data-reco-click` | Tracks the click action (action id).     | Yes      |
| `data-reco-name`  | Names the recommendation.                | Optional |

When an element carrying `data-reco-id` appears, the tag emits a **show** event; when an element carrying `data-reco-click` is clicked, it emits the click. The tag enriches these with `reco_id`, `reco_name`, `item_id`, and `item_ids`, then pushes the custom event **`ab_recos`** to the `dataLayer`, from which your tag manager (e.g. GTM) forwards them to analytics.

The `ab_recos` event carries an `action_id` (values include `show`, `go_to_page`, `add_to_cart_item`, `add_to_cart_items`, `convert_XXX`, `close`, `set_experiment_audience`), `reco_id`, `item_id`, and `item_ids`.

{% hint style="warning" %}
For banners filled asynchronously, add `data-reco-id` only **after** the content has fully loaded, otherwise the **show** event can fire before the products exist. Note that each view and click generates a tracking event, which can increase analytics (and BigQuery export) costs at scale.
{% endhint %}

### Method 3: Headless API

For headless architectures, native apps, server-side rendering, and CRM environments, call the API directly and render the results yourself.

**Recommendations:**

```
GET https://uc-info.eu.abtasty.com/v1/reco/[SITE_ID]/recos/[RECO_ID]?variables=[VARIABLES]&fields=[FIELDS]
```

| Parameter   | Purpose                                                                             |
| ----------- | ----------------------------------------------------------------------------------- |
| `SITE_ID`   | Your site identifier (e.g. `952`).                                                  |
| `RECO_ID`   | The recommendation strategy id (UUID, e.g. `5a936bc0-fbd1-4048-81a8-b94da73178e2`). |
| `variables` | JSON-encoded dynamic variables (e.g. `viewing_item`, `viewed_items`).               |
| `fields`    | Optional JSON-encoded list of product fields to return; defaults to id only.        |

The response is a JSON list of products with fields such as `img_link`, `id`, `price`, `category`, `name`, and `revenues_last_30_days`. Cache responses where possible, pass contextual parameters, and combine with analytics tracking.

**Merchandising** uses the same base host, with a JWT in the `Authorization: Bearer <token>` header:

```
GET https://uc-info.eu.abtasty.com/v1/reco/[SITE_ID]/merch/category_id/{category_id}
GET https://uc-info.eu.abtasty.com/v1/reco/[SITE_ID]/merch/{merch_id}
```

Retrieve a strategy either by category id or by merchandising strategy UUID (`merch_id`). Common query parameters include `variables`, `fields`, `limit` (default 20), `offset` (zero-based, takes precedence over `page`), `page` (1-indexed), `facets` (true/false), `filters[field][]`, `sort[field]` (asc/desc), and `output_format` (json/csv). Filter and sort fields must be flagged `facetable` and `merch_sortable` respectively in the back office.

The merchandising response includes `name`, `items`, `total_items`, `total_pages`, `current_page`, `limit`, `has_next`, and `facets`. Status codes: `200` OK, `400` Bad Request (strategy not found / invalid filter), `403` Forbidden (auth), `422` Unprocessable Entity (invalid JSON/format), `503` Service Unavailable (10-second global timeout).

### Email deployment

Recommendation strategies can also be deployed into email campaigns. Navigation events must carry a `USER_ID`, and you configure deployment from **deployment settings** at the bottom of the strategy builder after saving. Three options exist:

* **JSON API**: the same recommendation endpoint as above:

  ```
  GET https://uc-info.eu.abtasty.com/v1/reco/[SITE_ID]/recos/[RECO_ID]?variables=[VARIABLES]&fields=[FIELDS]
  ```

  Code samples (cURL, JavaScript, Python) are available from the **Code** button on the deployment page.
* **Compatible email tools (feeds)**: currently implemented for **Brevo**, which consumes a dedicated feed.
* **HTML template**: create a template in your email tool and paste the code from the deployment page; currently implemented for **SFMC** (Salesforce Marketing Cloud).

### Search widget

The front-end search experience is deployed through the AB Tasty **Search widget** in Web Experimentation & Personalization, not through the methods above. See the Search section for the full launch procedure (Modal vs Free placement, Element Selector, desktop/mobile widgets, translation keys, styling, and the `abtasty_search` / `abtasty_search_result` events).

### Related

* Creating strategies: build the strategies you deploy here, and find their `RECO_ID` / `MERCH_ID`.
* Search: launching and configuring the Search widget.
* Monitoring Commerce deployment health: confirm deployments and synchronizations succeeded.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.abtasty.com/commerce/widget-implementation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.