Panoramica del servizio Customer Match per la fedeltà

Questa guida descrive come utilizzare il servizio Customer Match per i programmi fedeltà nell'API Merchant. Questo servizio consente ai commercianti di gestire i dati di fidelizzazione dei clienti, come gli identificatori utente e le informazioni sul livello, per la personalizzazione organica sulla Ricerca Google, senza richiedere un account Google Ads attivo.

Panoramica

Utilizza il servizio Customer Match per la fedeltà per caricare i dati fedeltà, che vengono poi utilizzati per fornire funzionalità di personalizzazione organica della fedeltà nella Ricerca Google, ad esempio la visualizzazione di prezzi specifici per i membri. Utilizzi il metodo personalizzato ManageLoyaltyCustomerMatch per associare i tuoi clienti ai livelli del programma fedeltà, consentendoti di inserire, aggiornare o rimuovere il loro stato fedeltà in base agli identificatori utente.

Concetti fondamentali

  • Interfaccia unificata:un endpoint univoco per aggiungere, aggiornare o rimuovere i dettagli del livello di fedeltà dei clienti.
  • Progettazione incentrata sulla privacy:per proteggere la privacy degli utenti e impedire il probing non autorizzato degli account, l'API non supporta le operazioni GET o LIST, garantendo che i dati vengano gestiti senza recupero o controllo.
  • Identificazione flessibile:abbina gli utenti utilizzando almeno un identificatore valido, ad esempio un indirizzo email, un indirizzo fisico o un numero di telefono.
  • Trattamento basato sul consenso:il servizio memorizza e utilizza i dati dei clienti solo quando l'utente finale ha concesso il consenso necessario a Google. Per proteggere e impedire il probing dell'esistenza dell'account o dello stato del consenso, il servizio restituisce un esito positivo silenzioso se non viene trovato un match o il consenso non viene concesso.

Prerequisiti

Segui questi requisiti per utilizzare il servizio Customer Match per i programmi fedeltà:

  • Configurazione dell'account:assicurati di avere un account Merchant Center attivo. Non è necessario creare un account Google Ads per utilizzare il servizio Customer Match per i programmi fedeltà.
  • Configurazione del programma fedeltà:attiva il programma fedeltà nel tuo account Merchant Center e assicurati di aver definito i livelli fedeltà.
  • Ordine dei livelli:tieni presente l'ordine in cui i tuoi livelli fedeltà sono definiti nell'interfaccia utente di Merchant Center. L'API utilizza questa sequenza esatta per la mappatura dell'enumerazione.

Metodo: ManageLoyaltyCustomerMatch

Il metodo ManageLoyaltyCustomerMatch funge da interfaccia centrale per gestire le associazioni di fedeltà dei clienti. In base all'input fornito, il servizio determina automaticamente se inserire, aggiornare o rimuovere lo stato del livello fedeltà di un cliente. L'operazione è idempotente: le richieste identiche ripetute hanno lo stesso effetto di una singola richiesta.

La seguente richiesta mostra come gestire le associazioni di fedeltà dei clienti tramite l'API:

POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage

Questa richiesta definisce i seguenti parametri di percorso obbligatori:

  • api_version: La versione dell'API, ad esempio v1.
  • account_id: l'ID account Merchant Center.

Includi un oggetto loyaltyCustomer nel corpo della richiesta.

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

loyaltyCustomer fields

  • userIdentifier: l'insieme di identificatori utilizzati per trovare la corrispondenza con il cliente. Deve essere fornito e valido almeno un campo all'interno di userIdentifier.
  • loyaltyTier: il livello fedeltà da associare al cliente. Corrisponde all'ordine del livello nella configurazione di Merchant Center. Per maggiori dettagli, vedi Informazioni sulla mappatura di loyaltyTier. Utilizza NON_MEMBER per rimuovere un'associazione esistente.
  • pointBalance: il saldo punti attuale del cliente.

Campi userIdentifier

È necessario compilare almeno uno dei seguenti campi:

  • emailAddress: l'indirizzo email del cliente.
  • Indirizzo: l'indirizzo fisico del cliente. PostalCode è obbligatorio.
  • phoneNumber: il numero di telefono del cliente. È consigliabile il formato E.164.

Informazioni sulla mappatura di loyaltyTier

L'API non utilizza i nomi personalizzati. I valori enum loyaltyTier (da TIER1 a TIER7) sono etichette semantiche. Non utilizzano i nomi personalizzati (ad esempio, "Gold Rewards") o le etichette personalizzate (ad esempio, "gold_tier") che hai assegnato nell'interfaccia utente di Merchant Center. ma corrispondono rigorosamente all'ordine in cui hai definito i livelli nelle impostazioni del programma fedeltà in Merchant Center:

  • TIER1: corrisponde al primo livello elencato nella configurazione del programma fedeltà di Merchant Center.
  • TIER2: corrisponde al secondo livello elencato nella configurazione del programma fedeltà di Merchant Center.
  • TIER3 - TIER7: corrispondono al terzo e al settimo livello elencati nella configurazione del programma fedeltà di Merchant Center.

Esempio:

Se il tuo programma fedeltà Merchant Center ha livelli definiti in questo ordine:

  1. Nome del livello: "Silver Status", Etichetta del livello: "silver"
  2. Nome del livello: "Gold Member", etichetta del livello: "gold"
  3. Nome del livello: "Platinum Elite", etichetta del livello: "platinum"

Poi, in accounts.loyaltyCustomers.manage chiamate API:

  • Per assegnare un cliente allo "Stato Silver", devi utilizzare loyaltyTier: TIER1.
  • Per assegnare un cliente a "Membro Gold", devi utilizzare loyaltyTier: TIER2.
  • Per assegnare un cliente a "Platinum Elite", devi utilizzare loyaltyTier: TIER3.

Valori enum LoyaltyTier

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (utilizzato per segnalare la rimozione dell'associazione al programma fedeltà del cliente)

Comprendere il corpo della risposta ManageLoyaltyCustomerMatch

Il metodo ManageLoyaltyCustomerMatch restituisce un oggetto ManageLoyaltyCustomerMatchResponse:

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

Considerazioni importanti sulle possibili risposte:

  • Upsert riuscito (dati memorizzati): per memorizzare o aggiornare correttamente l'associazione del livello fedeltà di un cliente, soddisfa le seguenti condizioni:

    • corrispondi a un utente Google con il userIdentifier fornito
    • hai impostato il valore loyaltyTier nella richiesta su un valore valido diverso da NON_MEMBER
    • l'utente corrispondente ha acconsentito all'utilizzo dei dati fedeltà

La risposta contiene l'oggetto loyaltyCustomer della richiesta, che indica che i dati sono stati elaborati e archiviati correttamente:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • Eliminazione riuscita:per rimuovere correttamente qualsiasi associazione di fedeltà esistente per il cliente con questo commerciante, devono essere soddisfatte le seguenti condizioni:
    • corrispondi a un utente Google con il userIdentifier fornito
    • hai impostato loyaltyTier nella richiesta su NON_MEMBER

La risposta è un oggetto JSON vuoto:

{}
  • Nessuna corrispondenza / nessun consenso (operazione riuscita silenziosa): se il userIdentifier fornito non corrisponde a un Account Google o se l'utente corrispondente non ha acconsentito all'utilizzo dei dati fedeltà, l'API restituisce uno stato HTTP 200 OK con un oggetto JSON vuoto: {}. Ciò si verifica sia per i tentativi di upsert che di rimozione.

Esempi

TIER1 corrisponde al primo livello definito del commerciante, quello chiamato "Base", mentre TIER2 corrisponde al secondo, "Premium"

Per aggiungere un cliente al TIER2 o aggiornarne lo stato utilizzando un indirizzo email, invia la seguente richiesta:

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

Quando un utente viene abbinato correttamente e ha dato il consenso, l'API restituisce la seguente risposta:

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

Quando non viene trovata alcuna corrispondenza o l'utente non ha dato il consenso, l'API restituisce la seguente risposta:

{}

Per rimuovere l'associazione fedeltà di un cliente utilizzando un numero di telefono, invia la seguente richiesta:

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

Indipendentemente dall'esistenza di un record, l'API restituisce la seguente risposta di esito positivo:

{}

Per aggiungere o aggiornare un cliente utilizzando più identificatori, invia la seguente richiesta:

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 risposta è simile al primo esempio, a seconda della corrispondenza e del consenso.

Gestione degli errori

L'API utilizza codici HTTP standard. Le stringhe di errore comuni includono:

Codice HTTP Error String Descrizione
400 INVALID_ARGUMENT user_identifier o loyalty_tier mancante oppure identificatore vuoto.
401 UNAUTHENTICATED Credenziali non valide o mancanti.
403 PERMISSION_DENIED L'utente autenticato non ha accesso all'account Merchant Center specificato.
404 NOT_FOUND L'etichetta del livello fedeltà specificata non esiste nella tua configurazione.
412 FAILED_PRECONDITION Non hai configurato un programma fedeltà nel tuo account.
429 RESOURCE_EXHAUSTED Limite quota raggiunto.

Esempi di errori

Esempio per 404 NOT_FOUND:

Qualsiasi richiesta valida a un ID account per cui non è configurato un programma fedeltà.

L'API restituisce la seguente risposta di errore:

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

Motivo:l'account commerciante nel percorso non ha un programma fedeltà attivo.

Esempi di 400 INVALID_ARGUMENT:

Si verifica un errore se la richiesta contiene un valore non valido per il campo loyaltyTier:

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

L'API restituisce la seguente risposta di errore:

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

Motivo: TIER11 non è un valore enum valido per loyaltyTier. Lo stesso errore può verificarsi quando provi a specificare TIER2 quando è disponibile un solo livello.

Si verifica un errore se nel corpo della richiesta manca il campo obbligatorio loyaltyTier:

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

L'API restituisce la seguente risposta di errore:

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

Motivo:il campo loyaltyTier è obbligatorio.

Si verifica un errore se un identificatore di indirizzo è incompleto, ad esempio quando manca il campo postalCode:

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

L'API restituisce la seguente risposta di errore:

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

Motivo:è stato fornito un indirizzo, ma manca il campo obbligatorio postalCode, quindi non è considerato un identificatore valido.

Si verifica un errore se richiedi un indice di livello che non rientra nei limiti del programma configurato:

Scenario: il commerciante ha configurato un solo livello in Merchant Center.

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

L'API restituisce la seguente risposta di errore:

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

Motivo: è stato richiesto il LIVELLO2, ma il programma fedeltà collegato all'account non ha un secondo livello definito.

Si verifica un errore se la richiesta contiene un emailAddress non valido:

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

L'API restituisce la seguente risposta di errore:

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

Motivo: il formato dell'indirizzo email non è valido.

Si verifica un errore se l'oggetto userIdentifier è vuoto:

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

L'API restituisce la seguente risposta di errore:

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

Motivo:l'oggetto userIdentifier è presente, ma non contiene campi identificatori effettivi.

Nota sulla convalida dell'identificatore:

  • L'API esegue controlli di formato di base sugli identificatori (ad esempio, struttura email, presenza di postalCode negli indirizzi).
  • Tuttavia, alcuni identificatori che superano i controlli iniziali potrebbero non corrispondere a nessun account utente Google o potrebbero non essere in un formato riconosciuto dal sistema di corrispondenza backend. In questi casi, riceverai la risposta vuota di operazione riuscita silenziosa {} con stato HTTP 200 OK.

Best practice

Segui queste best practice per ottimizzare l'integrazione.

  • Per l'integrazione su larga scala:poiché l'API opera su base per richiesta, è necessario il parallelismo lato client per ottenere il throughput necessario per i set di dati di grandi dimensioni. Devi progettare l'integrazione in modo da gestire più richieste simultanee. Per indicazioni su come strutturare l'implementazione per gestire volumi più elevati tramite la parallelizzazione, consulta la nostra guida su come inviare più richieste.

  • Gestione delle quote:la quota predefinita è di 1.000.000 di richieste al giorno e di 10.000 richieste al minuto. Per scoprire come monitorare e controllare le quote, consulta Quote e limiti.

  • Dai la priorità all'indirizzo email:se possibile, includi l'emailAddress del cliente nell'userIdentifier. Gli indirizzi email sono in genere l'identificatore più preciso e affidabile per abbinare gli utenti ai loro Account Google.

  • Gestisci le risposte vuote: progetta la tua applicazione in modo che interpreti correttamente le risposte vuote {} come riuscite, comprendendo che i dati non sono stati archiviati per motivi di privacy (nessuna corrispondenza o nessun consenso). Non riprovare a inviare la richiesta.

  • Verifica l'ordine dei livelli: conferma sempre l'ordine dei livelli del programma fedeltà nell'interfaccia utente di Merchant Center per assicurarti di utilizzare i valori enum TIER1-TIER7 corretti nelle chiamate API. Questo mapping si basa sull'ordine definito nell'UI, non sui nomi.

  • Monitora gli errori:registra e monitora le risposte API, prestando attenzione a eventuali errori 4xx per rilevare problemi di integrazione, in particolare gli errori 404 che potrebbero indicare una mancata corrispondenza nella comprensione del livello.