28 lutego 2026 r. wycofaliśmy i wyłączyliśmy wersję 1 beta interfejsu Merchant API. Instrukcje przejścia na najnowszą stabilną wersję znajdziesz w artykule Migracja z wersji 1 beta do wersji 1.

Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Omówienie usługi kierowania na listę klientów w programie lojalnościowym

Ten przewodnik opisuje, jak korzystać z usługi kierowania na listę klientów w programie lojalnościowym w interfejsie Merchant API. Ta usługa umożliwia sprzedawcom zarządzanie danymi o programach lojalnościowych, takimi jak identyfikatory użytkowników i informacje o poziomach, na potrzeby personalizacji wyników wyszukiwania w Google bez konieczności posiadania aktywnego konta Google Ads.

Przegląd

Użyj usługi kierowania na listę klientów w programie lojalnościowym, aby przesyłać dane o lojalności, które są następnie wykorzystywane do udostępniania w wyszukiwarce Google bezpłatnych funkcji personalizacji w programie lojalnościowym, takich jak wyświetlanie cen dla uczestników programu. Za pomocą ManageLoyaltyCustomerMatchmetody niestandardowej możesz powiązać klientów z poziomami programu lojalnościowego, co umożliwia wstawianie, aktualizowanie i usuwanie ich statusu w programie lojalnościowym na podstawie identyfikatorów użytkowników.

Kluczowych pojęć

Ujednolicony interfejs: unikalny punkt końcowy do dodawania, aktualizowania i usuwania informacji o poziomach lojalności klientów.
Projekt skoncentrowany na ochronie prywatności: aby chronić prywatność użytkowników i zapobiegać nieautoryzowanemu sprawdzaniu kont, interfejs API nie obsługuje operacji GET ani LIST, co zapewnia zarządzanie danymi bez ich pobierania ani audytu.
Elastyczna identyfikacja: dopasowuj użytkowników za pomocą co najmniej jednego prawidłowego identyfikatora, takiego jak adres e-mail, adres fizyczny lub numer telefonu.
Przetwarzanie oparte na zgodzie: usługa przechowuje i wykorzystuje dane klientów tylko wtedy, gdy użytkownik udzielił Google niezbędnej zgody. Aby chronić użytkowników przed sprawdzaniem istnienia konta lub stanu zgody, usługa zwraca ciche potwierdzenie, jeśli nie znajdzie dopasowania lub nie uzyska zgody.

Wymagania wstępne

Aby korzystać z usługi kierowania na listę klientów w programie lojalnościowym, musisz spełniać te wymagania:

Konfiguracja konta: upewnij się, że masz aktywne konto Merchant Center. Aby korzystać z usługi kierowania na listę klientów w programie lojalnościowym, nie musisz tworzyć konta Google Ads.
Konfiguracja programu lojalnościowego: włącz program lojalnościowy na koncie Merchant Center i upewnij się, że masz zdefiniowane poziomy lojalnościowe.
Kolejność poziomów: zwróć uwagę na kolejność, w jakiej poziomy programu lojalnościowego są zdefiniowane w interfejsie Merchant Center. Interfejs API używa tej dokładnej sekwencji do mapowania wyliczeń.

Metoda: `ManageLoyaltyCustomerMatch`

Metoda ManageLoyaltyCustomerMatch jest głównym interfejsem do zarządzania powiązaniami z programem lojalnościowym. Na podstawie podanych danych usługa automatycznie określa, czy wstawić, zaktualizować czy usunąć status poziomu lojalności klienta. Operacja jest idempotentna: powtarzane identyczne żądania mają taki sam efekt jak jedno żądanie.

Poniższe żądanie pokazuje, jak zarządzać powiązaniami lojalnościowymi klientów za pomocą interfejsu API:

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

To żądanie definiuje te wymagane parametry ścieżki:

api_version: wersja interfejsu API, np. v1.
account_id: identyfikator konta Merchant Center.

W treści żądania umieść obiekt loyaltyCustomer.

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

pola loyaltyCustomer

userIdentifier: zestaw identyfikatorów używanych do dopasowywania klienta. W polu userIdentifier musi być podane co najmniej 1 prawidłowe pole.
loyaltyTier: poziom lojalności do powiązania z klientem. Odpowiada kolejności poziomu w konfiguracji Merchant Center. Więcej informacji znajdziesz w artykule Wyjaśnienie mapowania loyaltyTier. Aby usunąć istniejące powiązanie, użyj wartości NON_MEMBER.
pointBalance: aktualna liczba punktów klienta.

Pola userIdentifier

Musisz wypełnić co najmniej jedno z tych pól:

emailAddress: adres e-mail klienta.
address: fizyczny adres klienta. Wymagany jest kod pocztowy.
phoneNumber: numer telefonu klienta. Zalecany jest format E.164.

Omówienie mapowania `loyaltyTier`

Interfejs API nie używa niestandardowych nazw. Wartości wyliczeniowe loyaltyTier (od TIER1 do TIER7) to etykiety semantyczne. Nie używają one niestandardowych nazw (np. „Gold Rewards”) ani niestandardowych etykiet (np. „gold_tier”), które zostały przypisane w interfejsie Merchant Center. Zamiast tego są one ściśle powiązane z kolejnością, w jakiej zdefiniowano poziomy w ustawieniach programu lojalnościowego w Merchant Center:

TIER1: odpowiada pierwszemu poziomowi wymienionemu w konfiguracji programu lojalnościowego w Merchant Center.
TIER2: odpowiada drugiemu poziomowi wymienionemu w konfiguracji programu lojalnościowego w Merchant Center.
TIER3–TIER7: odpowiadają poziomom od trzeciego do siódmego wymienionym w konfiguracji programu lojalnościowego w Merchant Center.

Przykład:

Jeśli Twój program lojalnościowy w Merchant Center ma zdefiniowane poziomy w tej kolejności:

Nazwa poziomu: „Silver Status”, etykieta poziomu: „silver”
Nazwa poziomu: „Złoty członek”, etykieta poziomu: „złoty”
Nazwa poziomu: „Platinum Elite”, etykieta poziomu: „platinum”

Następnie w sekcji accounts.loyaltyCustomers.manage wywołania interfejsu API:

Aby przypisać klienta do „Silver Status”, musisz użyć loyaltyTier: TIER1.
Aby przypisać klienta do grupy „Złoty klient”, musisz użyć wartości loyaltyTier: TIER2.
Aby przypisać klienta do poziomu „Platinum Elite”, musisz użyć wartości loyaltyTier: TIER3.

Wartości wyliczeniowe LoyaltyTier

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER (sygnalizuje usunięcie powiązania klienta z programem lojalnościowym)

Opis treści odpowiedzi ManageLoyaltyCustomerMatch

Metoda ManageLoyaltyCustomerMatch zwraca obiekt ManageLoyaltyCustomerMatchResponse:

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

Ważne uwagi dotyczące możliwych odpowiedzi:

Pomyślne wstawienie lub aktualizacja (dane zapisane): aby zapisać lub zaktualizować powiązanie klienta z poziomem programu lojalnościowego, spełnij te warunki:
- dopasujesz użytkownika Google do podanego userIdentifier.
- ustawisz w żądaniu parametr loyaltyTier na prawidłową wartość inną niż NON_MEMBER.
- dopasowany użytkownik wyraził zgodę na wykorzystanie danych o programie lojalnościowym.

Odpowiedź zawiera obiekt loyaltyCustomer z Twojego żądania, co oznacza, że dane zostały przetworzone i zapisane:

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

Usunięcie powiązania: aby usunąć powiązanie klienta z programem lojalnościowym u tego sprzedawcy, muszą być spełnione te warunki:
- dopasujesz użytkownika Google do podanego userIdentifier.
- ustawisz w prośbie wartość loyaltyTier na NON_MEMBER,

Odpowiedzią jest pusty obiekt JSON:

{}

Brak dopasowania lub brak zgody (ciche powodzenie): jeśli podany userIdentifier nie pasuje do konta Google lub jeśli dopasowany użytkownik nie wyraził zgody na używanie danych o programie lojalnościowym, interfejs API zwraca stan HTTP 200 OK z pustym obiektem JSON: {}. Dotyczy to zarówno prób wstawiania lub aktualizowania, jak i usuwania.

Przykłady

TIER1 odpowiada pierwszemu zdefiniowanemu poziomowi sprzedawcy, czyli poziomowi „Podstawowy”, a TIER2 drugiemu poziomowi, czyli „Premium”.

Aby dodać klienta do poziomu TIER2 lub zaktualizować jego stan za pomocą adresu e-mail, wyślij to żądanie:

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

Gdy użytkownik zostanie dopasowany i wyrazi zgodę, interfejs API zwróci tę odpowiedź:

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

Jeśli nie ma dopasowania lub użytkownik nie wyraził zgody, interfejs API zwraca tę odpowiedź:

{}

Aby usunąć powiązanie klienta z programem lojalnościowym za pomocą numeru telefonu, wyślij to żądanie:

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

Niezależnie od tego, czy rekord istniał, interfejs API zwraca następującą odpowiedź o sukcesie:

{}

Aby dodać lub zaktualizować klienta za pomocą wielu identyfikatorów, wyślij to żądanie:

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

Odpowiedź jest podobna do pierwszego przykładu, w zależności od dopasowania i zgody.

Obsługa błędów

Interfejs API używa standardowych kodów HTTP. Typowe ciągi błędów to:

Kod HTTP	Error String	Opis
400	INVALID_ARGUMENT	Brak atrybutu user_identifier lub loyalty_tier albo identyfikator jest pusty.
401	UNAUTHENTICATED	Nieprawidłowe lub brakujące dane logowania.
403	PERMISSION_DENIED	Uwierzytelniony użytkownik nie ma dostępu do określonego konta Merchant Center.
404	NOT_FOUND	Podana etykieta poziomu lojalności nie istnieje w Twojej konfiguracji.
412	FAILED_PRECONDITION	Nie masz skonfigurowanego programu lojalnościowego na koncie.
429	RESOURCE_EXHAUSTED	Osiągnięto limit.

Przykłady błędów

Przykład dla 404 NOT_FOUND:

Każde prawidłowe żądanie identyfikatora konta, na którym nie skonfigurowano programu lojalnościowego.