Utiliser le label dans des thèmes personnalisés et des boutiques headless

Le bloc d’application couvre la plupart des thèmes. Si votre thème n’accepte pas les blocs d’application, ou si vous créez une boutique headless, vous pouvez lire vous-même le label terminé. OmniBuzz l’écrit dans un métachamp de variante. Le thème Liquid et la Storefront API peuvent tous deux le lire.

Où se trouvent les données

Propriété	Valeur
Espace de noms	omnibuzz
Clé	label
Type	json
Propriétaire	Variante de produit
Accès Storefront	Lecture publique
Nom de la définition	OmniBuzz label

OmniBuzz crée la définition pour vous. La valeur existe dès que la variante a des données OmniBuzz. m peut être vide ({}) ; dans ce cas, n’affichez rien.

Le format de la valeur

{
  "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’exemple montre trois langues pour rester court. La valeur réelle contient les dix dans t et dans b. La devise de la boutique est l’EUR dans l’exemple : le deuxième marché est donc un marché converti et porte fx.

Champ	Signification
v	Version du format. Actuellement 1.
u	Moment où la valeur a été écrite (heure ISO).
w	Durée de la fenêtre en jours.
m	Résultats par marché. La clé est l’ID numérique du marché. Seuls les marchés ayant un label à afficher sont présents. L’objet peut être vide.
c	Devise de l’entrée.
p	Prix au moment du contrôle, en centimes (même unité que les prix Liquid, y compris pour les devises sans décimales).
r	Le prix antérieur, en centimes.
pct	Réduction par rapport au prix antérieur, en pourcentage, arrondie à l’inférieur.
fx	Tolérance de taux de change en points de base (200 = 2 %). Présent uniquement quand c n’est pas la devise de la boutique.
t	Texte du label par langue. Les dix langues.
b	Texte du badge par langue. Présent uniquement quand pct est supérieur à 0.

La règle d’affichage

Vérifiez toujours l’entrée enregistrée par rapport à la page en cours. N’affichez le label que si tout ce qui suit est vrai :

1. m contient une entrée pour l’ID du marché de l’acheteur.
2. c est égal à la devise de l’acheteur.
3. Le prix barré (prix comparé) de la variante est supérieur à son prix.
4. r est supérieur à 0.
5. Le prix actuel en centimes est égal à p. Pour une entrée avec fx, la règle est aussi remplie quand abs(price - p) * 10000 <= p * fx.

Choisissez le texte dans cet ordre : la langue de l’acheteur (par exemple de), puis la langue de base (pt et pt-BR utilisent pt-PT), puis en. N’affichez le badge que si le prix actuel est exactement égal à p. Traitez tous les textes comme du texte brut : en Liquid, utilisez | escape ; en JavaScript, utilisez textContent, jamais innerHTML.

Si un contrôle échoue, n’affichez rien. N’affichez pas un ancien label à côté d’un prix modifié.

Exemple Liquid

Enregistrez ceci sous snippets/omnibuzz-label.liquid et appelez-le sur la page produit :

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

Le snippet lit le prix actuel sur la variante. Quand l’acheteur choisit une autre variante, votre thème doit afficher à nouveau le snippet ou exécuter les mêmes contrôles en script.

Exemple avec la Storefront API

Sans @inContext, l’API renvoie les prix du marché principal. Transmettez toujours le pays et la langue de l’acheteur :

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 est une chaîne JSON. Analysez-la, puis appliquez la règle d’affichage :

• Convertissez amount en centimes : Math.round(Number(amount) * 100). Faites-le pour toutes les devises.
• L’ID du marché est un ID global tel que gid://shopify/Market/123456789. Utilisez le nombre final comme clé dans m.
• localization.market est obsolète à partir de la Storefront API 2026-10, mais fonctionne encore. Sans ID de marché, n’affichez rien.

À savoir

• Les valeurs sont mises à jour chaque nuit, et à nouveau quand vous modifiez les textes des labels ou la tolérance de taux de change sur la page Labels.
• L’application formate elle-même les montants du texte. Le format peut différer légèrement de celui de votre boutique.
• Un marché dont les labels sont désactivés, ou une variante sans résultat, n’a pas d’entrée. N’affichez alors rien.

Quand vous désinstallez l’application

Shopify ne supprime que les données qui appartiennent à l’application elle-même. La définition omnibuzz et ses valeurs restent dans votre boutique après la désinstallation. L’application ne peut plus les nettoyer. Pour les supprimer, ouvrez Paramètres > Données personnalisées > Variantes de produit dans votre admin Shopify et supprimez la définition OmniBuzz label. Ses valeurs sont supprimées avec elle.