Usar a etiqueta em temas personalizados e lojas headless

O bloco de aplicação serve a maioria dos temas. Se o seu tema não suporta blocos de aplicação, ou se cria uma loja headless, pode ler a etiqueta já pronta. O OmniBuzz escreve-a num metacampo de variante. Tanto o tema Liquid como a Storefront API conseguem lê-lo.

Onde estão os dados

Propriedade	Valor
Espaço de nomes	omnibuzz
Chave	label
Tipo	json
Proprietário	Variante de produto
Acesso Storefront	Leitura pública
Nome da definição	OmniBuzz label

O OmniBuzz cria a definição por si. O valor existe sempre que a variante tem dados do OmniBuzz. m pode estar vazio ({}); nesse caso, não mostre nada.

O formato do valor

{
  "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 %"
      }
    }
  }
}

O exemplo mostra três idiomas para ficar curto. O valor real tem os dez em t e em b. A moeda da loja no exemplo é EUR, por isso o segundo mercado é convertido e tem fx.

Campo	Significado
v	Versão do formato. Atualmente 1.
u	Quando o valor foi escrito (hora ISO).
w	Duração da janela em dias.
m	Resultados por mercado. A chave é o ID numérico do mercado. Só aparecem os mercados com uma etiqueta para mostrar. Pode estar vazio.
c	Moeda da entrada.
p	Preço no momento da verificação, em cêntimos (a mesma unidade dos preços do Liquid, também nas moedas sem casas decimais).
r	O preço anterior, em cêntimos.
pct	Redução face ao preço anterior, em percentagem, arredondada por defeito.
fx	Tolerância cambial em pontos base (200 = 2%). Só aparece quando c não é a moeda da loja.
t	Texto da etiqueta por idioma. Os dez idiomas.
b	Texto da etiqueta de desconto por idioma. Só aparece quando pct é superior a 0.

A regra de apresentação

Verifique sempre a entrada guardada com a página atual. Mostre a etiqueta apenas se tudo o que se segue for verdade:

1. m tem uma entrada para o ID de mercado do comprador.
2. c é igual à moeda do comprador.
3. O preço de comparação da variante é superior ao seu preço.
4. r é superior a 0.
5. O preço atual em cêntimos é igual a p. Numa entrada com fx, também serve abs(price - p) * 10000 <= p * fx.

Escolha o texto por esta ordem: o idioma do comprador (por exemplo de), depois o idioma base (pt e pt-BR usam pt-PT), depois en. Mostre a etiqueta de desconto apenas quando o preço atual for exatamente p. Trate todos os textos como texto simples: em Liquid use | escape, em JavaScript use textContent, nunca innerHTML.

Se uma verificação falhar, não mostre nada. Não mostre uma etiqueta antiga ao lado de um preço alterado.

Exemplo em Liquid

Guarde isto como snippets/omnibuzz-label.liquid e renderize-o na página de produto:

{% 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 -%}

O snippet lê o preço atual da variante. Quando o comprador escolhe outra variante, o seu tema tem de renderizar o snippet de novo ou executar as mesmas verificações num script.

Exemplo com a Storefront API

Sem @inContext, a API devolve os preços do mercado principal. Passe sempre o país e o idioma do comprador:

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 é uma cadeia JSON. Analise-a e depois aplique a regra de apresentação:

• Converta amount para cêntimos: Math.round(Number(amount) * 100). Faça-o para todas as moedas.
• O ID de mercado é um ID global como gid://shopify/Market/123456789. Use o número final como chave em m.
• localization.market está obsoleto desde a Storefront API 2026-10, mas ainda funciona. Sem um ID de mercado, não mostre nada.

Bom saber

• Os valores são atualizados todas as noites, e outra vez quando altera os textos das etiquetas ou a tolerância cambial na página Etiquetas.
• A aplicação formata ela própria os montantes no texto. Pode diferir ligeiramente do formato monetário da sua loja.
• Um mercado com as etiquetas desativadas, ou uma variante sem resultado, não tem entrada. Nesse caso, não mostre nada.

Quando desinstala a aplicação

A Shopify só remove os dados que pertencem à própria aplicação. A definição omnibuzz e os seus valores ficam na sua loja depois de desinstalar. A aplicação já não os pode limpar. Para os remover, abra Definições > Dados personalizados > Variantes de produto no seu admin Shopify e elimine a definição OmniBuzz label. Ao eliminá-la, os seus valores também são eliminados.