Aller au contenu
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Accorder et utiliser les avantages

Attribuez des avantages aux cartes Wallet depuis la console, les automatisations, les cartes à tampons ou l’API, utilisez-les avec Scanner de Carte et suivez-les dans les analyses.

A modèle d'avantage ne devient utile que lorsqu'il est attribué à des Cartes. Cette page couvre toutes les façons dont un avantage atteint une Carte, comment le personnel et la console d'administration l'utilisent, et comment suivre ses performances.

Façons d'attribuer un avantage

Canal
Idéal pour
Où le configurer

Console

Une Carte à la fois : tests, gestes de service client.

Page de la Carte → Avantages → Attribuer un avantage.

Automatisation

Campagnes et règles appliquées à de nombreuses Cartes : cadeaux de bienvenue, anniversaires, montées de niveau, audiences à maintenir engagées.

Automatisation avec l' Attribuer un avantage action.

Carte à tampons

Récompenses obtenues en collectant des tampons.

modèle d'avantage de récompense sur une modèle de carte à tampons.

API

Attributions pilotées par un CRM, un moteur de fidélité, un POS ou une plateforme e-commerce.

Fichier groupé

Grosses attributions ponctuelles à partir d'un fichier.

colonne Modèle d'avantage du mise à jour de Carte par fichier plat.

Connecteurs

Avantages qui existent déjà dans un système partenaire, comme des coupons d'une plateforme de fidélité, ou un script de fournisseur d'avantages.

Paramètres du connecteur, par exemple Comarch ou le script du fournisseur d'avantages.

Les avantages envoyés par une intégration sans modèle derrière eux sont affichés comme Externe dans la console d'administration.

Attribuer un avantage depuis la console

L'attribution depuis la page de la Carte est le moyen le plus rapide de tester un modèle ou de faire un geste ponctuel.

1

Ouvrez la Carte

Ouvrir Wallet → Cartes, trouvez la Carte, puis ouvrez son Avantages onglet.

2

Choisissez le modèle d'avantage

Cliquez sur Attribuer un avantage, recherchez le modèle par son nom et sélectionnez-le. Le nom interne s'affiche en gris sous le titre. Les modèles déjà sur la Carte, ou pas encore utilisables, peuvent quand même être attribués et sont seulement signalés ; les modèles expirés sont affichés grisés car le titulaire recevrait un avantage expiré. Lorsque le modèle sélectionné est déjà sur la Carte, le bouton affiche Actualiser l'avantage: l'attribuer à nouveau met à jour l'avantage existant issu du modèle au lieu d'en ajouter un second.

3

Confirmez

Cliquez sur Attribuer un avantage. La Carte est mise à jour immédiatement dans le Wallet du titulaire.

The Grant a benefit dialog shows each template's behavior and validity, marks those already on the pass, and offers Refresh benefit for one the pass already holds.
La boîte de dialogue Attribuer un avantage affiche le comportement et la validité de chaque modèle, marque ceux déjà sur la Carte et propose Actualiser l'avantage pour celui que la Carte contient déjà.

Quand aucun modèle n'est proposé, créez-en un d'abord ou remettez-en un existant sur Actif. Lorsque la Carte comporte déjà 20 avantages actifs, supprimez un avantage expiré avant d'en attribuer un nouveau. Voir Limites.

Attribuer un avantage avec une automatisation

L' Attribuer un avantage action attribue un modèle à chaque Carte ciblée par l'automatisation, dans la même mise à jour que les autres actions de l'automatisation (changement de données, thème, modèle de Carte), suivie de la notification lorsqu'il y en a une. Un modèle désactivé ou supprimé au moment où l'automatisation s'exécute est ignoré.

Les automatisations peuvent aussi réagir aux événements liés aux avantages (Un avantage est utilisé, Un avantage est crédité, Le solde d'un avantage évolue dans un sens ou dans l'autre). Voir Automatisation la référence complète.

Attribuer un avantage via l'API

Les intégrations attribuent un modèle à une Carte, ou créent un avantage autonome, avec l'API des avantages. L'attribution d'un modèle est idempotente : attribuer à nouveau le même modèle à la même Carte met à jour l'avantage qu'il a déjà créé.

Opération
Point de terminaison

Attribuer un modèle d'avantage à une Carte

POST /api/{tenantId}/passes/{passId}/benefitTemplates/{benefitTemplateId}

Lister les avantages d'une Carte

GET /api/{tenantId}/passes/{passId}/benefits

Créer un avantage sur une Carte

POST /api/{tenantId}/passes/{passId}/benefits

Lire, remplacer ou supprimer un avantage

GET, PUT, DELETE /api/{tenantId}/passes/{passId}/benefits/{benefitId}

Enregistrer une utilisation ou un crédit

POST /api/{tenantId}/passes/benefits/{benefitId}/movements

Lister les avantages sur toutes les Cartes

GET /api/{tenantId}/benefits

Une mutation contient une valeur signée valeur (négative pour utiliser, positive pour créditer, jamais zéro, nombres entiers uniquement) et l' ancienneValeur que l'appelant a lue en dernier. Si le solde a changé entre-temps, la requête est refusée avec un conflit et rien n'est appliqué, donc une requête réessayée ne peut jamais utiliser un avantage deux fois. La référence complète, y compris les autorisations et les erreurs, se trouve dans la référence de l'API.

Gérer un avantage sur une Carte

L' Avantages onglet d'une Carte répertorie tous les avantages qu'elle contient, avec leur statut, comportement, utilisations restantes, validité et origine, par exemple Console. Chaque ligne comporte un bouton Utiliser et un menu pour ouvrir l'avantage.

The Benefits tab of a pass shows each benefit's status, behavior, uses left and validity.
L'onglet Avantages d'une Carte affiche le statut, le comportement, les utilisations restantes et la validité de chaque avantage.

Ouvrir un avantage montre d'où il vient, son historique d'utilisation et les actions disponibles.

Action
Effet

Compter 1 utilisation / bouton Utiliser

Enregistre une utilisation, par exemple lorsque l'avantage a été utilisé à une caisse sans Carte Scanner.

Rendre 1 utilisation

Crédite une utilisation après une erreur. Un avantage à usage unique ou à usages multiples ne peut jamais dépasser son nombre initial d'utilisations.

Ajuster le solde

Enregistre une entrée signée, positive pour créditer et négative pour déduire, avec un motif. Elle ne peut pas faire passer l'avantage sous zéro et ne peut pas être annulée.

Modifier le code

Remplace uniquement le code de cet avantage.

Prolonger

Modifie la validité pour ce titulaire uniquement, sans modifier le modèle.

Retirer de la Carte

Supprime l'avantage de la Carte et libère son emplacement.

Le titre, la description, le visuel et les liens d'un avantage unique sont copiés depuis le modèle lorsqu'il est attribué. Ils ne peuvent pas être modifiés sur une Carte : attribuer à nouveau le modèle les actualise.

A benefit's page shows its origin, its usage history and the actions to give back, adjust, change the code or extend it.
La page d'un avantage affiche son origine, son historique d'utilisation et les actions pour le rendre, l'ajuster, modifier le code ou le prolonger.

Utiliser un avantage au comptoir

Carte Scanner répertorie les avantages d'une Carte scannée qui ont Afficher dans Carte Scanner activé, et le personnel en touche un pour l'utiliser. Un profil Carte Scanner peut restreindre la liste à certains tags ou modèles, par exemple uniquement les avantages du bar sur le téléphone du bar. Avec Utiliser automatiquement à la lecture, chaque scan utilise l'avantage immédiatement, sans toucher, ce qui accélère les files d'attente dans un bar ou un vestiaire.

Chaque utilisation est enregistrée avec sa source (console, Carte Scanner, API), l'opérateur ou la clé API et l'appareil, et apparaît dans l'historique d'utilisation de l'avantage.

Suivre les avantages

Analytique → Avantages indique les performances des avantages sur une période choisie : consultez Tableaux de bord d'analytique.

Le taux d'utilisation divise les utilisations par les avantages attribués. Un modèle à usages multiples ou illimités peut donc dépasser 100 % : un pack « 5 ateliers barista » utilisé trois fois affiche 300 %.

Benefit analytics shows uses, engaged passes and new benefits, with the top benefit templates of the period.
L'analytique des avantages montre les utilisations, les Cartes engagées et les nouveaux avantages, avec les principaux modèles d'avantages de la période.

Chaque modification est aussi un événement qui peut être interrogé avec l' API Insights ou envoyé à d'autres outils avec des webhooks. Les événements d'un avantage sur une Carte sont listés dans la référence des événements. Les événements de modèle sont :

Événement
Quand

BenefitTemplate:Created, BenefitTemplate:Updated, BenefitTemplate:Deleted

Un modèle est créé, modifié ou supprimé dans la console d'administration.

Afficher les avantages dans les champs de la Carte

Les modèles de Carte peuvent afficher les données d'avantages dans leurs champs avec Liquid. Chaque avantage est disponible sous benefits.<template key>, où la clé est l'identifiant du modèle d'avantage avec chaque caractère autre qu'une lettre, un chiffre ou un tiret bas remplacé par _benefitStats Variable.

Valeur
{{ benefits.free_drink_reward.data.value }}

{{ benefits.free_drink_reward.data.value }}

Le solde de l'avantage attribué depuis le modèle free-drink-reward.

{{ benefitStats.total }}

Avantages sur la Carte, hors avantages supprimés.

{{ benefitStats.active }}

Avantages utilisables maintenant.

{{ benefitStats.scheduled }}, {{ benefitStats.used }}, {{ benefitStats.expired }}

Avantages pas encore actifs, utilisés ou expirés.

Voir templating Liquid pour la syntaxe.

Migrer depuis l'API des privilèges

Les anciens points de terminaison de privilèges sont obsolètes et redirigent vers les avantages. Le mappage complet des anciens noms et des noms actuels se trouve dans Migrer depuis l'API des privilèges dans les guides des développeurs.

FAQ

Pourquoi l'avantage n'a-t-il pas été attribué par l'automatisation ?

Vérifiez d'abord l'historique d'exécution de l'automatisation. Un modèle inactif ou supprimé au moment où l'automatisation s'exécute est ignoré, et une Carte à la limite de 20 avantages ne peut pas recevoir un nouvel avantage. Vérifiez aussi que la Carte correspondait bien à l'audience de l'automatisation à ce moment-là.

Attribuer deux fois le même modèle crée-t-il deux avantages ?

Non. Attribuer un modèle à une Carte qui possède déjà un avantage issu de ce modèle met à jour cet avantage et actualise son titre, sa description, son visuel et ses liens.

Mis à jour