Données de la carte et synchronisation

Comprenez ce qu’une carte stocke, quand les données des connecteurs sont récupérées et comment fonctionnent les déclencheurs de rendu.

Données de Carte et synchronisation

Une carte dans The Wallet Crew est un enregistrement léger. Elle stocke des identifiants et une petite quantité de données de remplacement spécifiques à la carte. Elle ne conserve pas les données client provenant des systèmes sources. Lorsqu'une carte est rendue pendant l'installation, une mise à jour push ou un aperçu, les connecteurs interrogent les systèmes externes en direct pour récupérer les données nécessaires à la génération de la carte.

Comprendre ce modèle d'extraction est essentiel avant de travailler avec l'API ou de configurer un modèle. Il explique pourquoi les identifiants externes sont le champ le plus critique d'une carte, pourquoi les mises à jour qui ne déclenchent pas un appel de connecteur ne modifient jamais ce qu'un client voit, et pourquoi la disponibilité du connecteur affecte directement la livraison de la carte.

Exemples concrets

• Une carte de fidélité stocke un ID CRM et récupère le dernier solde uniquement lorsque la carte est rendue.
• Une carte d'événement stocke un ID de billet et récupère les dernières données de siège ou de porte d'embarquement lorsqu'une mise à jour est déclenchée.
• Une carte d'adhésion stocke un remplacement local dans des données supplémentaires lorsqu'aucun système connecté n'expose cette valeur.

Ce qu'une carte stocke

Un enregistrement de carte ne contient que les données nécessaires pour identifier la carte, récupérer les données externes et conserver de petites valeurs spécifiques à la carte.

Type de champ	Description	Persisté ?	Utilisé pour
ID de Carte	Identifiant interne de la plateforme. Opaque. Attribué à la création.	Oui	Références internes, certains points de terminaison de l'API
Identifiants externes	Paires clé-valeur reliant la carte aux systèmes sources	Oui	Recherches de connecteurs au moment du rendu
Données supplémentaires	Paires clé-valeur stockées directement sur la carte	Oui	Enrichissement de la carte lorsque les données du connecteur ne sont pas disponibles
Métadonnées	Paires clé-valeur calculées automatiquement si nécessaire	Recalculées, non définies manuellement	Segmentation et reporting uniquement

The Wallet Crew ne stocke pas de données personnelles par défaut. Les noms, soldes, points de fidélité et autres données client restent dans les systèmes sources et sont récupérés au moment du rendu.

Identifiants externes

Les identifiants externes sont le pont entre une carte et les données sources. Ils indiquent à chaque connecteur quel enregistrement récupérer lorsque la carte est générée.

Utilisation Structure pour la vue back-office de l'emplacement de ces identifiants sur une carte.

Une carte peut comporter plusieurs identifiants externes, souvent un par système connecté. Une carte de fidélité peut utiliser un ID client CRM, un ID client Shopify et un numéro de programme de fidélité comme identifiants distincts. Chaque clé est une chaîne. Chaque valeur est l'identifiant utilisé par ce système source.

Les identifiants externes ne sont pas affichés sur la carte. Leur seul but est de permettre aux connecteurs de récupérer le bon enregistrement.

Si une carte n'a aucun identifiant externe pour un connecteur utilisé par le modèle, ce connecteur n'a rien à interroger. Ses champs ne sont pas disponibles au moment du rendu.

Les identifiants externes sont également utilisés pour localiser une carte dans l'API. La plupart des points de terminaison d'écriture acceptent id.{key}={value} des paramètres de requête pour cibler une carte sans connaître son ID interne, par exemple id.shopify.customerId=12345. Plusieurs id.* paramètres sont combinés avec des conditions ET Utilisez la référence de l'API pour connaître toutes les règles de recherche.

Pour utiliser les identifiants externes dans une URL de livraison de carte, voir URL de livraison de carte.

Un identifiant externe manquant ou incorrect empêche silencieusement un connecteur de récupérer des données. Si une carte s'affiche avec des champs vides, vérifiez que les identifiants externes corrects sont définis sur la carte.

Comment une carte est créée

Les cartes sont créées via des flux d'inscription, et non via une étape ultérieure d'importation de données.

Les principaux chemins de création sont :

• Cinto SDK — un développeur appelle le SDK pendant un flux d'inscription et fournit les identifiants externes au moment de la création. Utilisez la documentation Cinto SDK.
• Connecteur — certains connecteurs peuvent créer des cartes automatiquement lorsqu'un événement pertinent se produit dans le système source. Le connecteur définit les identifiants externes dans le cadre de la création de la carte. Utilisez la création de carte déclenchée par un connecteur.
• Formulaire d'inscription — la plateforme inclut un formulaire d'inscription intégré avec une étape de carte. Utilisez les flux d'inscription.

Dans tous les cas, les identifiants externes sont définis à la création. Il n'existe pas d'étape distincte de chargement des données qui les rattache plus tard.

Comment les connecteurs utilisent les identifiants externes

Les connecteurs récupèrent des données à partir des systèmes sources. Ils sont configurés et activés par locataire dans le cadre de la configuration de l'intégration.

Lorsqu'une carte est rendue, chaque connecteur configuré reçoit l'identifiant externe pertinent et appelle le système source. La réponse devient disponible dans le contexte de rendu sous forme de champs nommés tels que firstName, loyaltyBalance, ou offerTitle. Les noms exacts des champs dépendent du connecteur et sont documentés dans la référence de ce connecteur.

L'appel du connecteur se produit au moment du rendu, et non à la création de la carte. Il n'existe aucun traitement en arrière-plan qui pousse les données client dans The Wallet Crew. La carte reflète ce que les connecteurs ont renvoyé lors du dernier rendu réussi.

Les noms des champs du connecteur varient selon l'intégration. Utilisez la référence du connecteur pour les champs exposés par chaque connecteur.

Données supplémentaires

Les données supplémentaires sont la solution de repli pour les valeurs qui ne proviennent pas d'un connecteur.

Il s'agit d'un magasin clé-valeur attaché directement à la carte. Contrairement aux données du connecteur, les données supplémentaires sont persistées dans l'enregistrement de la carte. Elles ne dépendent pas d'un appel de connecteur pour être disponibles au moment du rendu.

Utilisez les données supplémentaires lorsqu'une valeur n'existe dans aucun système connecté ou lorsqu'un remplacement au niveau de la carte doit être stocké directement sur la carte.

Les champs de données supplémentaires sont disponibles dans le contexte de rendu sous la forme de additionalData.fieldName.

Les données supplémentaires peuvent être définies de ces façons :

• À la création de la carte via le Cinto SDK, un flux d'inscription intégré ou un flux de connecteur qui définit des valeurs au niveau de la carte
• Mises à jour par carte via PATCH /api/{tenantId}/passes/{passId} ou PATCH /api/{tenantId}/passes
• Mises à jour en masse via POST /api/{tenantId}/passes/pushUpdate
• Modifiées manuellement dans le back-office

Les mises à jour sont fusionnées dans les données supplémentaires existantes. Les clés non incluses dans une requête sont conservées.

Utilisez la référence de l'API pour obtenir des détails sur le corps de la requête.

Métadonnées

Les métadonnées sont un ensemble de paires clé-valeur calculées automatiquement par la plateforme. Elles ne sont pas définies manuellement et ne sont pas affichées sur la carte.

Les métadonnées servent à la segmentation et au reporting. Elles permettent de regrouper, filtrer et cibler les cartes avec des valeurs calculées telles qu'un niveau, une affectation de magasin ou une fenêtre d'expiration.

Les métadonnées sont recalculées automatiquement lorsque c'est nécessaire pendant les flux de rendu, de mise à jour et de génération de données. Les déclencheurs exacts sont internes et peuvent changer. Si un connecteur échoue et que les données requises sont indisponibles, le recalcul des métadonnées peut également échouer.

Les métadonnées sont réservées à un usage opérationnel. Ne les utilisez pas pour afficher des informations sur une carte. Les valeurs de métadonnées ne sont pas disponibles pour les champs d'affichage du portefeuille.

Quand les données sont récupérées

Les données du connecteur sont récupérées dans quatre situations :

1. Installation de la carte — un client ajoute la carte à un portefeuille et la carte est générée pour la première fois.
2. Mise à jour push — une mise à jour est déclenchée via l'API ou par un événement d'intégration. Pour les premiers appels API, commencez par Premiers pas avec l'API.
3. Aperçu back-office — un aperçu de carte est demandé depuis le back-office.
4. API de rendu — le point de terminaison de rendu est appelé explicitement.

Il n'y a pas de sondage en arrière-plan. En dehors de ces déclencheurs, la carte installée sur un appareil ne change pas.

Utilisation Comment une carte est rendue pour le pipeline de rendu complet.

FAQ

Les données client peuvent-elles être envoyées une seule fois et stockées dans The Wallet Crew ?

Non. La plateforme ne stocke que l'enregistrement de la carte, les identifiants, les données supplémentaires et les métadonnées calculées. Les données client restent dans les systèmes sources, sauf si une intégration spécifique est conçue autrement.

Pourquoi une carte affiche-t-elle encore d'anciennes données après une mise à jour de la source ?

Un changement dans la source ne met pas à jour à lui seul la carte installée. Un déclencheur de rendu reste nécessaire, par exemple une mise à jour push ou une nouvelle installation.

Quel est le premier champ à vérifier lorsque les données du connecteur sont manquantes ?

Vérifiez d'abord les identifiants externes sur la carte. Si le connecteur ne peut pas faire correspondre un enregistrement source, ses champs seront absents du contexte de rendu.