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 des clients fidèles dans l'API Merchant. Ce service permet aux marchands de gérer les données de fidélité des clients, telles que les identifiants utilisateur et les informations sur les niveaux, pour la 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 fidèles pour importer des données de fidélité, qui sont ensuite utilisées pour fournir des fonctionnalités de personnalisation de la fidélité naturelle 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 : point de terminaison unique pour ajouter, modifier ou supprimer les informations sur le niveau de fidélité des clients.
  • Conception axée sur la confidentialité : pour protéger la confidentialité des utilisateurs et empêcher le sondage non autorisé des comptes, l'API n'est pas compatible avec les opérations GET ni LIST. Cela permet de s'assurer que les données sont gérées sans récupération ni audit.
  • Identification flexible : associez les utilisateurs à l'aide d'au moins un identifiant valide, comme 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 donné le consentement nécessaire à Google. Pour protéger et empêcher l'exploration de l'existence d'un compte ou de l'état du consentement, le service renvoie une réussite silencieuse si aucune correspondance n'est établie ou si le consentement n'est pas accordé.

Prérequis

Pour utiliser le service de ciblage par liste de clients fidèles, vous devez respecter les conditions suivantes :

  • Configuration du compte : assurez-vous d'avoir un compte Merchant Center actif. Vous n'avez pas besoin de créer un compte Google Ads pour utiliser le service de ciblage des clients fidèles par liste.
  • 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 : veillez à 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 statut du niveau de fidélité d'un client. L'opération est idempotente : les 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é des clients 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 faire correspondre 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

Vous devez fournir au moins l'un des champs suivants :

  • emailAddress : adresse e-mail du client.
  • address : adresse physique du client. PostalCode est obligatoire.
  • 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 (de TIER1 à TIER7) sont des libellés sémantiques. Ils n'utilisent pas les noms personnalisés (par exemple, "Récompenses Gold") ni les libellés personnalisés (par exemple, "niveau_or") que vous avez attribués dans l'UI Merchant Center. Ils correspondent strictement à l'ordre dans lequel vous avez défini vos niveaux dans les paramètres du programme de fidélité de 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 : "Statut Argent", libellé du niveau : "argent"
  2. Nom du niveau : "Gold Member", 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 statut Silver à un client, vous devez utiliser loyaltyTier: TIER1.
  • Pour attribuer un client à "Membre Gold", vous devez utiliser loyaltyTier: TIER2.
  • Pour attribuer le statut Platinum Elite à un client, vous devez utiliser loyaltyTier: TIER3.

Valeurs enum LoyaltyTier

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

Comprendre le corps de la réponse ManageLoyaltyCustomerMatch

La méthode ManageLoyaltyCustomerMatch renvoie un objet ManageLoyaltyCustomerMatchResponse :

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

Remarques importantes sur les réponses possibles :

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

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

La réponse contient l'objet loyaltyCustomer de votre requête, ce qui indique que les données ont été traitées et stockées avec succès :

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

La réponse est un objet JSON vide :

{}
  • Aucune correspondance / aucun consentement (succès silencieux) : si le userIdentifier fourni ne correspond à aucun 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 à la fois pour les tentatives d'insertion/mise à jour et de suppression.

Exemples

TIER1 correspond au premier niveau défini par le marchand, appelé "Basic", et TIER2 à son deuxième niveau, "Premium".

Pour ajouter un client au 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 associé et 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 d'un client à un programme de fidélité à 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"
  }'

Que l'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 au 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 L'attribut user_identifier ou loyalty_tier est manquant, ou l'identifiant est 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 La limite de quota a été atteinte.

Exemples d'erreurs

Exemple pour 404 NOT_FOUND :

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

L'API renvoie le message d'erreur suivant :

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

Raison : Le compte marchand dans le chemin d'accès ne dispose pas d'un programme de fidélité actif.

Exemples de 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 le message d'erreur suivant :

{
  "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\""
          }
        ]
      }
    ]
  }
}

Raison : 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'il n'y a qu'un seul niveau 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 le message d'erreur suivant :

{
  "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 lorsque le champ postalCode est manquant :

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

L'API renvoie le message d'erreur suivant :

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

Raison : Une adresse est fournie, mais le champ postalCode obligatoire 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 est hors limites pour le 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 le message d'erreur suivant :

{
  "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 : le NIVEAU2 est demandé, mais le programme de fidélité associé au compte ne comporte pas de deuxième niveau.

Une erreur se produit si la requête contient un emailAddress mal formé :

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

L'API renvoie le message d'erreur suivant :

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

Raison : 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 le message d'erreur suivant :

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

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

Remarque sur la validation des identifiants :

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

Bonnes pratiques

Suivez ces bonnes pratiques pour optimiser votre intégration.

  • Pour une intégration à grande échelle : comme l'API fonctionne sur une base de requête par requête, 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 pour gérer plusieurs requêtes simultanées. Pour savoir comment structurer votre implémentation afin de gérer des volumes plus importants grâce à la parallélisation, consultez notre guide sur la manière d'envoyer 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.

  • Prioriser l'adresse e-mail : dans la mesure du possible, incluez l'emailAddress du client dans userIdentifier. Les adresses e-mail sont généralement l'identifiant le plus précis et le plus fiable pour faire correspondre les utilisateurs à leurs comptes Google.

  • Gérez les réponses vides : concevez votre application pour qu'elle interprète correctement les réponses {} vides comme un succès, 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 réessayez pas d'envoyer la demande.

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

  • Surveillez 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 inadéquation dans la compréhension des niveaux.