Użycie etykiety w własnych motywach i sklepach headless

Blok aplikacji wystarcza w większości motywów. Jeśli Twój motyw nie obsługuje bloków aplikacji albo budujesz sklep headless, możesz sam odczytać gotową etykietę. OmniBuzz zapisuje ją w metapolu wariantu. Odczytają je zarówno motyw Liquid, jak i Storefront API.

Gdzie są dane

Właściwość	Wartość
Przestrzeń nazw	omnibuzz
Klucz	label
Typ	json
Właściciel	Wariant produktu
Dostęp w Storefront	Odczyt publiczny
Nazwa definicji	OmniBuzz label

OmniBuzz tworzy definicję za Ciebie. Wartość istnieje zawsze, gdy wariant ma dane OmniBuzz. m może być puste ({}); wtedy nie pokazuj niczego.

Format wartości

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

Przykład pokazuje trzy języki, żeby był krótki. Prawdziwa wartość ma wszystkie dziesięć w t i w b. Walutą sklepu w przykładzie jest EUR, więc drugi rynek jest przeliczany i ma fx.

Pole	Znaczenie
v	Wersja formatu. Obecnie 1.
u	Kiedy zapisano wartość (czas ISO).
w	Długość okna w dniach.
m	Wyniki według rynków. Kluczem jest numeryczny identyfikator rynku. Są tylko rynki z etykietą do pokazania. Obiekt może być pusty.
c	Waluta wpisu.
p	Cena w chwili sprawdzenia, w groszach (ta sama jednostka co ceny w Liquid, także dla walut bez miejsc po przecinku).
r	Poprzednia cena, w groszach.
pct	Obniżka względem poprzedniej ceny, w procentach, zaokrąglona w dół.
fx	Tolerancja kursu w punktach bazowych (200 = 2%). Występuje tylko wtedy, gdy c nie jest walutą sklepu.
t	Tekst etykiety według języka. Wszystkie dziesięć języków.
b	Tekst plakietki według języka. Występuje tylko wtedy, gdy pct jest większe od 0.

Reguła wyświetlania

Zawsze porównuj zapisany wpis z aktualną stroną. Pokaż etykietę tylko wtedy, gdy spełnione jest wszystko poniżej:

1. m ma wpis dla identyfikatora rynku kupującego.
2. c jest równe walucie kupującego.
3. Cena porównawcza wariantu jest wyższa niż jego cena.
4. r jest większe od 0.
5. Aktualna cena w groszach jest równa p. Dla wpisu z fx wystarczy też abs(price - p) * 10000 <= p * fx.

Wybierz tekst w tej kolejności: język kupującego (na przykład de), potem język bazowy (pt i pt-BR używają pt-PT), potem en. Pokaż plakietkę tylko wtedy, gdy aktualna cena jest dokładnie równa p. Traktuj wszystkie teksty jak zwykły tekst: w Liquid użyj | escape, w JavaScript textContent, nigdy innerHTML.

Jeśli jakiekolwiek sprawdzenie zawiedzie, nie pokazuj niczego. Nie pokazuj starej etykiety obok zmienionej ceny.

Przykład w Liquid

Zapisz to jako snippets/omnibuzz-label.liquid i wyrenderuj na stronie produktu:

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

Snippet odczytuje aktualną cenę z wariantu. Gdy kupujący wybierze inny wariant, motyw musi ponownie wyrenderować snippet albo wykonać te same sprawdzenia w skrypcie.

Przykład w Storefront API

Bez @inContext API zwraca ceny rynku głównego. Zawsze przekazuj kraj i język kupującego:

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 to ciąg JSON. Sparsuj go, a potem zastosuj regułę wyświetlania:

• Przelicz amount na grosze: Math.round(Number(amount) * 100). Zrób to dla każdej waluty.
• Identyfikator rynku to identyfikator globalny, na przykład gid://shopify/Market/123456789. Użyj liczby na końcu jako klucza w m.
• localization.market jest przestarzałe od Storefront API 2026-10, ale nadal działa. Bez identyfikatora rynku nie pokazuj niczego.

Warto wiedzieć

• Wartości są aktualizowane co noc oraz ponownie, gdy zmienisz teksty etykiet lub tolerancję kursu na stronie Etykiety.
• Aplikacja sama formatuje kwoty w tekście. Format może się nieco różnić od formatu waluty w Twoim sklepie.
• Rynek z wyłączonymi etykietami albo wariant bez wyniku nie ma wpisu. Wtedy nie pokazuj niczego.

Gdy odinstalujesz aplikację

Shopify usuwa tylko dane należące do samej aplikacji. Definicja omnibuzz i jej wartości zostają w Twoim sklepie po odinstalowaniu. Aplikacja nie może już ich wyczyścić. Aby je usunąć, otwórz w panelu Shopify Ustawienia > Dane niestandardowe > Warianty produktu i usuń definicję OmniBuzz label. Razem z nią znikną jej wartości.