Usare l'etichetta in temi personalizzati e storefront headless

Il blocco app copre la maggior parte dei temi. Se il tuo tema non supporta i blocchi app, o stai creando uno storefront headless, puoi leggere tu stesso l’etichetta già pronta. OmniBuzz la scrive in un metacampo della variante. Sia il tema Liquid sia la Storefront API possono leggerlo.

Dove si trovano i dati

Proprietà	Valore
Namespace	omnibuzz
Chiave	label
Tipo	json
Proprietario	Variante del prodotto
Accesso Storefront	Lettura pubblica
Nome della definizione	OmniBuzz label

OmniBuzz crea la definizione per te. Il valore esiste ogni volta che la variante ha dati OmniBuzz. m può essere vuoto ({}): in quel caso non mostrare nulla.

Il formato del valore

{
  "v": 1,
  "u": "2026-11-05T02:10:00Z",
  "w": 30,
  "m": {
    "123456789": {
      "c": "EUR",
      "p": 10000,
      "r": 12000,
      "pct": 16,
      "t": {
        "en": "Lowest price in the last 30 days: €120.00",
        "de": "Niedrigster Preis der letzten 30 Tage: 120,00 €",
        "fr": "Prix le plus bas des 30 derniers jours : 120,00 €"
      },
      "b": {
        "en": "-16%",
        "de": "-16 %",
        "fr": "-16 %"
      }
    },
    "987654321": {
      "c": "SEK",
      "p": 114500,
      "r": 136000,
      "pct": 15,
      "fx": 200,
      "t": {
        "en": "Lowest price in the last 30 days: SEK 1,360.00",
        "de": "Niedrigster Preis der letzten 30 Tage: 1.360,00 SEK",
        "fr": "Prix le plus bas des 30 derniers jours : 1 360,00 SEK"
      },
      "b": {
        "en": "-15%",
        "de": "-15 %",
        "fr": "-15 %"
      }
    }
  }
}

L’esempio mostra tre lingue per restare breve. Il valore reale ha tutte e dieci in t e in b. La valuta del negozio nell’esempio è EUR, quindi il secondo mercato è convertito e ha fx.

Campo	Significato
v	Versione del formato. Per ora 1.
u	Quando il valore è stato scritto (ora ISO).
w	Lunghezza della finestra in giorni.
m	Risultati per mercato. La chiave è l’ID numerico del mercato. Ci sono solo i mercati con un’etichetta da mostrare. Può essere vuoto.
c	Valuta della voce.
p	Prezzo al momento del controllo, in centesimi (la stessa unità dei prezzi Liquid, anche per le valute senza decimali).
r	Il prezzo precedente, in centesimi.
pct	Riduzione rispetto al prezzo precedente, in percentuale, arrotondata per difetto.
fx	Tolleranza sul cambio in punti base (200 = 2%). Presente solo quando c non è la valuta del negozio.
t	Testo dell’etichetta per lingua. Tutte e dieci le lingue.
b	Testo del badge per lingua. Presente solo quando pct è maggiore di 0.

La regola di visualizzazione

Controlla sempre la voce salvata rispetto alla pagina attuale. Mostra l’etichetta solo se tutte queste condizioni sono vere:

1. m ha una voce per l’ID del mercato dell’acquirente.
2. c è uguale alla valuta dell’acquirente.
3. Il prezzo di confronto della variante è maggiore del suo prezzo.
4. r è maggiore di 0.
5. Il prezzo attuale in centesimi è uguale a p. Per una voce con fx va bene anche abs(price - p) * 10000 <= p * fx.

Scegli il testo in quest’ordine: la lingua dell’acquirente (per esempio de), poi la lingua di base (pt e pt-BR usano pt-PT), poi en. Mostra il badge solo quando il prezzo attuale è esattamente p. Tratta tutti i testi come testo semplice: in Liquid usa | escape, in JavaScript usa textContent, mai innerHTML.

Se un controllo fallisce, non mostrare nulla. Non mostrare una vecchia etichetta accanto a un prezzo cambiato.

Esempio Liquid

Salva questo come snippets/omnibuzz-label.liquid e richiamalo nella pagina prodotto:

{% doc %}
  @param {variant} variant - The selected variant
  @example
  {% render 'omnibuzz-label', variant: product.selected_or_first_available_variant %}
{% enddoc %}
{%- liquid
  assign label = variant.metafields.omnibuzz.label.value
  assign market_id = localization.market.id | append: ''
  assign entry = label.m[market_id]
  assign price = variant.price
  assign show = false
  assign exact = false

  if entry and entry.c == cart.currency.iso_code and variant.compare_at_price > price and entry.r > 0
    if price == entry.p
      assign show = true
      assign exact = true
    elsif entry.fx != blank
      assign drift = price | minus: entry.p | abs | times: 10000
      assign allowed = entry.p | times: entry.fx
      if drift <= allowed
        assign show = true
      endif
    endif
  endif

  if show
    assign lang = request.locale.iso_code
    assign base = lang | split: '-' | first
    if base == 'pt'
      assign base = 'pt-PT'
    endif
    assign text = entry.t[lang] | default: entry.t[base] | default: entry.t.en
    assign badge = entry.b[lang] | default: entry.b[base] | default: entry.b.en
  endif
-%}
{%- if show and text != blank -%}
  <p class="omnibuzz-label">{{ text | escape }}</p>
  {%- if exact and badge != blank -%}
    <span class="omnibuzz-badge">{{ badge | escape }}</span>
  {%- endif -%}
{%- endif -%}

Lo snippet legge il prezzo attuale dalla variante. Quando l’acquirente sceglie un’altra variante, il tuo tema deve renderizzare di nuovo lo snippet o eseguire gli stessi controlli in uno script.

Esempio con la Storefront API

Senza @inContext, l’API restituisce i prezzi del mercato principale. Passa sempre il paese e la lingua dell’acquirente:

query OmniBuzzLabel($handle: String!, $country: CountryCode!, $language: LanguageCode!)
@inContext(country: $country, language: $language) {
  localization {
    market {
      id
    }
  }
  product(handle: $handle) {
    variants(first: 50) {
      nodes {
        id
        price {
          amount
          currencyCode
        }
        compareAtPrice {
          amount
          currencyCode
        }
        metafield(namespace: "omnibuzz", key: "label") {
          value
        }
      }
    }
  }
}

value è una stringa JSON. Analizzala, poi applica la regola di visualizzazione:

• Converti amount in centesimi: Math.round(Number(amount) * 100). Fallo per ogni valuta.
• L’ID del mercato è un ID globale come gid://shopify/Market/123456789. Usa il numero finale come chiave in m.
• localization.market è deprecato dalla Storefront API 2026-10, ma funziona ancora. Senza un ID mercato, non mostrare nulla.

Da sapere

• I valori vengono aggiornati ogni notte, e di nuovo quando cambi i testi delle etichette o la tolleranza sul cambio nella pagina Etichette.
• L’app formatta da sola gli importi nel testo. Il formato può differire leggermente da quello del tuo negozio.
• Un mercato con le etichette disattivate, o una variante senza risultato, non ha una voce. In quel caso non mostrare nulla.

Quando disinstalli l’app

Shopify rimuove solo i dati che appartengono all’app stessa. La definizione omnibuzz e i suoi valori restano nel tuo negozio dopo la disinstallazione. L’app non può più ripulirli. Per rimuoverli, apri Impostazioni > Dati personalizzati > Varianti di prodotto nel tuo admin Shopify ed elimina la definizione OmniBuzz label. Eliminandola si eliminano anche i suoi valori.