> For the complete documentation index, see [llms.txt](https://docs.samita.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.samita.io/reference/how-it-works.md).

# How it works

A simple overview of how Sami Product Labels works behind the scenes to display badges on your storefront.

This page explains how **Sami Product Labels** delivers badges, labels, trust badges, highlights, and banners to your storefront — no coding knowledge required.

## App Embed block

When you install the app, it adds an **App Embed block** to your Shopify theme -- a standard Shopify mechanism for running app functionality on your storefront.

Toggle the App Embed on or off anytime from your Shopify theme editor under **App embeds**. Off means no badges show; on means the app handles everything automatically.

{% hint style="info" %}
The app does **not** edit, overwrite, or inject code into your theme files. Everything runs through the App Embed block, which Shopify manages separately from your theme.
{% endhint %}

## How configurations are delivered

Every badge, label, trust badge, highlight, and banner you create is saved as a **Shopify metafield** attached to your store -- Shopify's built-in system for storing custom data.

This means:

* **No external API calls at page load** — configurations are already stored in Shopify, so there's no third-party server to wait on.
* **Fast performance** — badges load as fast as any other part of your theme.
* **Reliability** — badges stay available as long as your store is online, with no external server to go down.

## How badges appear on your storefront

When a customer visits your store:

1. The App Embed script loads as part of your theme.
2. The script reads your badge configurations from the stored metafields.
3. It evaluates your **targeting rules** — which products, collections, pages, or customer segments should see each badge.
4. The matching badges are rendered on the page in the positions you configured.

This entire process happens in the customer's browser and takes only milliseconds.

## Analytics tracking

**Sami Product Labels** tracks two key events to measure badge performance:

* **Add to cart** — records which badge was displayed when a customer adds a badged product to their cart.
* **Order placed** — records the conversion when a customer completes a purchase with a badged product.

These events power your **Analytics dashboard**, showing which badges drive engagement and sales.

{% hint style="info" %}
Analytics tracking is available on the DIAMOND plan. The app only tracks aggregate events — it does not store personal customer information.
{% endhint %}

## Country detection

The app detects the visitor's country, powering **country-based targeting** so you can show different badges by region.

For example, you could display a "Free Shipping" badge only to customers in the United States, or show a "Local Pickup Available" badge to customers in your home country.

## What the app does NOT do

* **Does not modify your theme files** — no Liquid code is injected.
* **Does not slow down your store** — data is stored in Shopify metafields, not fetched from external servers.
* **Does not collect personal customer data** — it uses customer tags and order counts for targeting only, never names, emails, or payment info.

***

## Next steps

* [Permissions and data access](/reference/permissions-and-data.md) — learn what data the app accesses and how it is handled.
* [Enable the app in your theme](/getting-started/enable-app-in-theme.md) — get started by turning on the App Embed block.


---

# 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.samita.io/reference/how-it-works.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.