Présentation du service de ciblage par liste de clients pour les programmes de fidélité

Ce guide explique comment utiliser le service de ciblage par liste de clients pour les programmes de fidélité dans l'API Merchant. Ce service permet aux marchands et aux fournisseurs de programmes de fidélité tiers agissant pour le compte de marchands de gérer les données de fidélité client, telles que les identifiants utilisateur et les informations sur les niveaux, pour une personnalisation naturelle dans la recherche Google, sans nécessiter de compte Google Ads actif.

Présentation

Utilisez le service de ciblage par liste de clients pour les programmes de fidélité afin d'importer des données de fidélité, qui sont ensuite utilisées pour fournir des fonctionnalités de personnalisation de fidélité naturelles dans la recherche Google, comme l'affichage de tarifs spécifiques aux membres. Vous utilisez la méthode personnalisée ManageLoyaltyCustomerMatch pour associer vos clients à des niveaux de programme de fidélité, ce qui vous permet d'insérer, de mettre à jour ou de supprimer leur statut de fidélité en fonction des identifiants utilisateur.

Concepts clés

  • Interface unifiée : un point de terminaison unique pour ajouter, mettre à jour ou supprimer les détails du niveau de fidélité d'un client.
  • Conception axée sur la confidentialité : pour protéger la confidentialité des utilisateurs et empêcher l'exploration non autorisée des comptes, l'API n'est pas compatible avec les opérations GET ou LIST, ce qui garantit que les données sont gérées sans récupération ni audit.
  • Identification flexible : mettez en correspondance les utilisateurs à l'aide d'au moins un identifiant valide, tel qu'une adresse e-mail, une adresse physique ou un numéro de téléphone.
  • Traitement basé sur le consentement : le service stocke et utilise les données client uniquement lorsque l'utilisateur final a accordé le consentement nécessaire à Google. Pour protéger et empêcher l'analyse de l'existence d'un compte ou de l'état du consentement, le service renvoie un message de réussite silencieux si aucune correspondance n'est trouvée ou si le consentement n'est pas accordé.

Prérequis

Pour utiliser le service de ciblage par liste de clients pour les programmes de fidélité, vous devez respecter les exigences suivantes :

  • Configuration du compte : assurez-vous de disposer d'un compte Merchant Center actif (ou d'un accès autorisé au compte du marchand si vous êtes un fournisseur de programme de fidélité tiers). Vous n'avez pas besoin de créer un compte Google Ads pour utiliser le service de ciblage par liste de clients du programme de fidélité.
  • Configuration du programme de fidélité : activez le programme de fidélité dans votre compte Merchant Center et assurez-vous d'avoir défini des niveaux de fidélité.
  • Ordre des niveaux : tenez compte de l'ordre dans lequel vos niveaux de fidélité sont définis dans l'interface utilisateur de Merchant Center. L'API utilise cette séquence exacte pour son mappage d'énumération.

Méthode : ManageLoyaltyCustomerMatch

La méthode ManageLoyaltyCustomerMatch sert d'interface centrale pour gérer les associations de fidélité client. En fonction des informations fournies, le service détermine automatiquement s'il doit insérer, mettre à jour ou supprimer le niveau de fidélité d'un client. L'opération est idempotente : des requêtes identiques répétées ont le même effet qu'une seule requête.

La requête suivante montre comment gérer les associations de fidélité client via l'API :

POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage

Cette requête définit les paramètres de chemin d'accès obligatoires suivants :

  • API_VERSION : version de l'API, par exemple v1.
  • ACCOUNT_ID : ID du compte Merchant Center.

Incluez un objet loyaltyCustomer dans le corps de la requête.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

Champs loyaltyCustomer

  • userIdentifier : ensemble d'identifiants utilisés pour mettre en correspondance le client. Au moins un champ de userIdentifier doit être fourni et valide.
  • loyaltyTier : niveau de fidélité à associer au client. Correspond à l'ordre du niveau dans la configuration Merchant Center. Pour en savoir plus, consultez Comprendre le mappage loyaltyTier. Utilisez NON_MEMBER pour supprimer une association existante.
  • pointBalance : solde de points actuel du client.

Champs userIdentifier

Indiquez au moins l'un des champs suivants :

  • emailAddress : adresse e-mail du client.
  • address : adresse physique du client. Veuillez indiquer un code postal.
  • phoneNumber : numéro de téléphone du client. Le format E.164 est recommandé.

Comprendre le mappage loyaltyTier

L'API n'utilise pas les noms personnalisés. Les valeurs d'énumération loyaltyTier (TIER1 à TIER7) sont des étiquettes sémantiques. Ils n'utilisent pas les noms personnalisés (par exemple, "Gold Rewards") ni les libellés personnalisés (par exemple, "gold_tier") que vous avez attribués dans l'interface utilisateur de Merchant Center. Ils correspondent strictement à l'ordre dans lequel vous avez défini vos niveaux dans les paramètres du programme de fidélité dans Merchant Center :

  • TIER1 : correspond au premier niveau listé dans la configuration de votre programme de fidélité Merchant Center.
  • TIER2 : correspond au deuxième niveau listé dans la configuration de votre programme de fidélité Merchant Center.
  • TIER3 à TIER7 : correspondent aux troisième à septième niveaux listés dans la configuration de votre programme de fidélité Merchant Center.

Exemple :

Si votre programme de fidélité Merchant Center comporte des niveaux définis dans cet ordre :

  1. Nom du niveau : "Silver Status", libellé du niveau : "silver"
  2. Nom du niveau : "Membre Gold", libellé du niveau : "gold"
  3. Nom du niveau : "Platinum Elite", libellé du niveau : "platinum"

Ensuite, dans les appels d'API accounts.loyaltyCustomers.manage :

  • Pour attribuer le "Silver Status" à un client, vous devez utiliser loyaltyTier: TIER1.
  • Pour attribuer un client à "Gold Member", vous devez utiliser loyaltyTier: TIER2.
  • Pour attribuer le niveau "Platinum Elite" à un client, vous devez utiliser loyaltyTier: TIER3.

Valeurs d'énumération LoyaltyTier

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (utilisé pour signaler la suppression de l'association de fidélité du client)

Comprendre le corps de la réponse ManageLoyaltyCustomerMatch

La méthode ManageLoyaltyCustomerMatch renvoie un objet ManageLoyaltyCustomerMatchResponse :

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

Remarques importantes concernant les réponses

  • Upsert réussi (données stockées) : pour stocker ou mettre à jour l'association d'un client à un niveau de fidélité, remplissez les conditions suivantes :

    • vous mettez en correspondance un utilisateur Google avec le userIdentifier fourni
    • vous définissez loyaltyTier dans la requête sur une valeur valide autre que NON_MEMBER.
    • l'utilisateur mis en correspondance a autorisé l'utilisation des données de fidélité.

La réponse contient l'objet loyaltyCustomer de votre requête, ce qui indique que le service a bien traité et stocké les données :

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • Suppression réussie : pour supprimer une association de fidélité existante entre le client et ce marchand, les conditions suivantes doivent être remplies :
    • vous mettez en correspondance un utilisateur Google avec le userIdentifier fourni
    • vous définissez le loyaltyTier dans la requête sur NON_MEMBER

La réponse est un objet JSON vide :

{}
  • Aucune correspondance/Aucun consentement (réussite silencieuse) : si l'userIdentifier fourni ne correspond pas à un compte Google ou si l'utilisateur correspondant n'a pas consenti à l'utilisation des données de fidélité, l'API renvoie un état HTTP 200 OK avec un objet JSON vide : {}. Cela se produit pour les tentatives d'upsert et de suppression.

Exemples

TIER1 correspond au premier niveau défini (par exemple, 'Basic') et TIER2 correspond au deuxième niveau (par exemple, 'Premium').

Pour ajouter un client à TIER2 ou mettre à jour son état à l'aide d'une adresse e-mail, envoyez la requête suivante :

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

Lorsqu'un utilisateur est mis en correspondance et qu'il a donné son consentement, l'API renvoie la réponse suivante :

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

En l'absence de correspondance ou si l'utilisateur n'a pas donné son consentement, l'API renvoie la réponse suivante :

{}

Pour supprimer l'association de fidélité d'un client à l'aide d'un numéro de téléphone, envoyez la requête suivante :

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

Qu'un enregistrement existe ou non, l'API renvoie la réponse de réussite suivante :

{}

Pour ajouter ou mettre à jour un client à l'aide de plusieurs identifiants, envoyez la requête suivante :

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

La réponse est semblable à celle du premier exemple, en fonction de la correspondance et du consentement.

Gestion des exceptions

L'API utilise des codes HTTP standards. Voici quelques chaînes d'erreur courantes :

Code HTTP Chaîne d'erreur Description
400 INVALID_ARGUMENT user_identifier ou loyalty_tier manquant, ou identifiant vide.
401 UNAUTHENTICATED Identifiants non valides ou manquants.
403 PERMISSION_DENIED L'utilisateur authentifié n'a pas accès au compte Merchant Center spécifié.
404 NOT_FOUND Le libellé de niveau de fidélité spécifié n'existe pas dans votre configuration.
412 FAILED_PRECONDITION Vous n'avez pas configuré de programme de fidélité dans votre compte.
429 RESOURCE_EXHAUSTED Limite de quota atteinte.

Exemples d'erreurs

Exemple pour 404 NOT_FOUND :

Toute requête valide vers un ID de compte pour lequel aucun programme de fidélité n'est configuré.

L'API renvoie la réponse d'erreur suivante :

{
  "error": {
    "code": 404,
    "message": "The loyalty program is not found for account: {ACCOUNT_ID}.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "notFound",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_ID": "{ACCOUNT_ID}",
          "REASON": "NOT_FOUND_LOYALTY_PROGRAM"
        }
      }
    ]
  }
}

Motif : Le compte marchand indiqué dans le chemin d'accès ne comporte pas de programme de fidélité actif.

Exemples d'erreurs 400 INVALID_ARGUMENT :

Une erreur se produit si la requête contient une valeur non valide pour le champ loyaltyTier :

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

L'API renvoie la réponse d'erreur suivante :

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "loyalty_customer.loyalty_tier",
            "description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
          }
        ]
      }
    ]
  }
}

Motif : TIER11 n'est pas une valeur d'énumération valide pour loyaltyTier. La même erreur peut se produire lorsque vous essayez de spécifier TIER2 alors qu'un seul niveau est disponible.

Une erreur se produit si le champ loyaltyTier obligatoire est manquant dans le corps de la requête :

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "pointBalance": 100
  }
}

L'API renvoie la réponse d'erreur suivante :

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.loyalty_tier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

Motif : le champ loyaltyTier est obligatoire.

Une erreur se produit si un identifiant d'adresse est incomplet, par exemple si le champ "postalCode" est manquant :

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "address": {
        "locality": "Sunnyvale",
        "administrativeArea": "CA",
        "regionCode": "US"
      }
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

L'API renvoie la réponse d'erreur suivante :

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Motif : une adresse est fournie, mais le champ obligatoire postalCode est manquant. Elle n'est donc pas considérée comme un identifiant valide.

Une erreur se produit si vous demandez un index de niveau qui n'est pas compris dans les limites du programme configuré :

Scénario : Le marchand n'a configuré qu'un seul niveau dans Merchant Center.

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 100
  }
}

L'API renvoie la réponse d'erreur suivante :

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.loyalty_tier",
          "PATTERN": "valid LoyaltyTier",
          "FIELD_VALUE": "TIER2",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Motif : TIER2 est demandé, mais le programme de fidélité associé au compte n'a pas de deuxième niveau défini.

Une erreur se produit si la requête contient un emailAddress incorrect :

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@google"
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

L'API renvoie la réponse d'erreur suivante :

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Motif : le format de l'adresse e-mail n'est pas valide.

Une erreur se produit si l'objet userIdentifier est vide :

{
  "loyaltyCustomer": {
    "userIdentifier": {},
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

L'API renvoie la réponse d'erreur suivante :

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.user_identifier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

Motif : l'objet userIdentifier est présent, mais ne contient aucun champ d'identifiant réel.

Remarque : Validation de l'identifiant

  • L'API effectue des vérifications de format de base sur les identifiants (par exemple, la structure de l'adresse e-mail, la présence de postalCode dans les adresses).
  • Toutefois, certains identifiants qui passent les vérifications initiales peuvent ne correspondre à aucun compte utilisateur Google ou ne pas être dans un format reconnu par le système de mise en correspondance du backend. Dans ce cas, vous recevrez la réponse vide de réussite silencieuse {} avec l'état HTTP 200 OK.

Bonnes pratiques

Suivez ces bonnes pratiques pour optimiser votre intégration.

  • Pour une intégration à grande échelle : l'API fonctionnant sur la base de requêtes individuelles, le parallélisme côté client est nécessaire pour atteindre le débit requis pour les grands ensembles de données. Vous devez concevoir votre intégration de manière à gérer plusieurs requêtes simultanées. Pour savoir comment structurer votre implémentation afin de gérer des volumes plus importants grâce au chargement en parallèle, consultez notre guide sur l'envoi de plusieurs requêtes.

  • Gestion des quotas : le quota par défaut est de 1 000 000 de requêtes/jour et de 10 000 requêtes/minute. Pour savoir comment surveiller et vérifier vos quotas, consultez Quotas et limites.

  • Priorisez l'adresse e-mail : dans la mesure du possible, incluez l'emailAddress du client dans le userIdentifier. Les adresses e-mail sont généralement l'identifiant le plus précis et le plus fiable pour mettre en correspondance les utilisateurs avec leur compte Google.

  • Gérer les réponses vides : concevez votre application de manière à interpréter correctement les réponses {} vides comme une réussite, en comprenant que cela signifie que les données n'ont pas été stockées pour des raisons de confidentialité (aucune correspondance ou aucun consentement). Ne relancez pas la requête.

  • Vérifiez l'ordre des niveaux : confirmez toujours l'ordre de vos niveaux de fidélité dans l'UI Merchant Center pour vous assurer que vous utilisez les valeurs d'énumération correctes de TIER1 à TIER7 dans vos appels d'API. Ce mappage est basé sur l'ordre défini dans l'interface utilisateur, et non sur leurs noms.

  • Surveiller les erreurs : enregistrez et surveillez les réponses de l'API, en prêtant attention aux erreurs 4xx pour détecter les problèmes d'intégration, en particulier les erreurs 404 qui peuvent indiquer une incompatibilité dans la compréhension des niveaux.

Précédent
Manage loyalty programs