Omówienie programów lojalnościowych

Prezentuj korzyści z zakupów w Twoim sklepie w Google za pomocą programów lojalnościowych. Możesz przesłać wiele korzyści, takich jak bezpłatna dostawa, punkty do wykorzystania przez klientów oraz specjalne ceny dla uczestników programu. Korzyści z udziału w programie lojalnościowym mogą się wyświetlać w bezpłatnych informacjach, reklamach produktowych i reklamach lokalnego asortymentu produktów na platformach Google, takich jak wyszukiwarka Google, karta Zakupy czy Portfel Google.

Dzięki interfejsowi Merchant API sprzedawcy i zewnętrzni dostawcy programów lojalnościowych działający w imieniu sprzedawców mogą programowo konfigurować i utrzymywać programy lojalnościowe za pomocą LoyaltyProgramService. Ta usługa umożliwia tworzenie, pobieranie, wyświetlanie, aktualizowanie i usuwanie programów lojalnościowych.

Więcej informacji o wymaganiach biznesowych i wytycznych dotyczących zasad znajdziesz w artykule Program lojalnościowy sprzedawcy w Centrum pomocy Merchant Center.

Kluczowe pojęcia

Podczas pracy z programami lojalnościowymi pamiętaj o tych pojęciach i ograniczeniach:

  • Identyfikator na poziomie konta: interfejs Merchant API identyfikuje programy lojalnościowe według identyfikatora konta Merchant Center, do którego należą.

  • Limit jednego programu: interfejs Merchant API obsługuje tylko jeden program lojalnościowy na konto sprzedawcy.

  • Bezpośrednia własność konta: programy lojalnościowe muszą być skonfigurowane bezpośrednio na docelowym koncie sprzedawcy (accounts/{ACCOUNT_ID}). Usługa nie obsługuje zarządzania programami lojalnościowymi na poziomie konta zaawansowanego w przypadku subkont. Zewnętrzni dostawcy programów lojalnościowych, którzy mają autoryzowany dostęp do konta sprzedawcy, mogą zarządzać programem w imieniu sprzedawcy.

  • Sprawdzanie pod kątem zgodności z zasadami redakcyjnymi: po utworzeniu lub zaktualizowaniu programu lojalnościowego jest on sprawdzany. Pole review_result.review_status wskazuje, czy program jest UNDER_REVIEW, APPROVED czy REJECTED. Każda udana aktualizacja powoduje, że program wraca do kolejki do sprawdzenia, nawet jeśli aktualizacja nie wprowadza żadnych istotnych zmian. Podczas procesu weryfikacji Google ukrywa program przed kupującymi. Sprawdzanie może potrwać do 48 godzin.

  • Obsługiwane regiony: programy lojalnościowe sprzedawców są dostępne w obsługiwanych krajach, takich jak Australia, Brazylia, Francja, Hiszpania, Holandia, Indie, Japonia, Kanada, Korea Południowa, Meksyk, Niemcy, Stany Zjednoczone, Wielka Brytania i Włochy.

  • Aktywne regiony: regionCodes programu lojalnościowego musi być podzbiorem activeRegionCodes accounts/{ACCOUNT_ID}/programs/loyalty. W przeciwnym razie żądania utworzenia, aktualizacji i usunięcia nie powiodą się i wystąpi błąd LOYALTY_PROGRAM_DISABLED. Google aktywuje obsługiwany kraj, gdy dodatek Program lojalnościowy jest włączony, a konto spełnia wymagania w tym kraju. Konto kwalifikuje się na przykład, jeśli program bezpłatnych informacji jest włączony, a podstawowe źródło danych o produktach jest kierowane na kraj dla miejsca docelowego FREE_LISTINGS. Aby dowiedzieć się, dlaczego dany kraj nie jest aktywny, przeczytaj artykuł Sprawdzanie aktywnych regionów.

  • Wymagania dotyczące poziomów: dołączenie do poziomów może być bezpłatne, wymagać opłaty członkowskiej, progu wydatków lub karty kredytowej marki sprzedawcy. Poziomy oparte na zawodzie (np. student, żołnierz itp.) nie są obsługiwane.

  • Bonusy i korzyści: programy obsługują bezpłatną dostawę, punkty do wykorzystania i ceny dla uczestników programu. W reklamach cena dla uczestników programu wymaga rabatu w wysokości co najmniej 5% lub 5 jednostek waluty poniżej ceny standardowej lub promocyjnej.

Wymagania wstępne

Zanim zaczniesz zarządzać programami lojalnościowymi za pomocą interfejsu Merchant API, upewnij się, że spełniasz te wymagania:

  • Musisz mieć aktywne konto Merchant Center (lub autoryzowany dostęp do konta sprzedawcy, jeśli jesteś zewnętrznym dostawcą programu lojalnościowego).

  • Włącz dodatek Program lojalnościowy na swoim koncie. Dodatek możesz włączyć na 2 sposoby:

  • Kraje, w których chcesz oferować program lojalnościowy, muszą być aktywne na Twoim koncie. Aby dowiedzieć się, które kraje są aktywne, przeczytaj artykuł Sprawdzanie aktywnych regionów.

Oto przykładowe żądanie włączenia dodatku do programu lojalnościowego za pomocą podrzędnego interfejsu API programów:

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

cURL

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

Sprawdzanie aktywnych regionów

Po włączeniu dodatku Program lojalnościowy wywołaj metodę accounts.programs.get dla accounts/{ACCOUNT_ID}/programs/loyalty. Odpowiedź pokazuje, gdzie możesz korzystać z programów lojalnościowych i dlaczego inne obsługiwane kraje są nieaktywne.

Oto przykładowe żądanie:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty

cURL

curl --request GET \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --compressed

Zastąp {ACCOUNT_ID} unikalnym identyfikatorem konta Merchant Center.

Oto przykładowa odpowiedź dotycząca konta, na którym włączono dodatek i które kwalifikuje się tylko w Stanach Zjednoczonych:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}

W odpowiedzi zwróć uwagę na te pola:

  • activeRegionCodes: kraje, które możesz użyć w regionCodes programu lojalnościowego. W powyższym przykładzie aktywny jest tylko US.
  • unmetRequirements: powód, dla którego inne obsługiwane kraje są nieaktywne. W przypadku programów lojalnościowych jest to wymaganie IS_ELIGIBLE_FOR_LOYALTY.
    • affectedRegionCodes: obsługiwane kraje, w których konto nie jest odpowiednie.
    • documentationUri: link do wymagań.

W powyższym przykładzie nie możesz jeszcze używać krajów w affectedRegionCodes. Jeśli regionCodes programu lojalnościowego zawiera jeden z nich, żądania utworzenia, aktualizacji i usunięcia nie powiodą się i pojawi się błąd LOYALTY_PROGRAM_DISABLED. Aby aktywować kraj, wykonaj te czynności:

  1. Upewnij się, że konto spełnia wymagania w danym kraju. Możesz na przykład włączyć program Bezpłatne informacje i ustawić podstawowe źródło danych o produktach, aby kierować reklamy na kraj dla miejsca docelowego FREE_LISTINGS. Aby poznać wszystkie sposoby uzyskania dostępu, zapoznaj się z wymaganiami.
  2. Wywołaj ponownie accounts.programs.get i sprawdź, czy kraj jest w activeRegionCodes.

affectedRegionCodes może obejmować kraje, w których nie prowadzisz sprzedaży. Nie musisz podejmować żadnych działań w przypadku tych krajów. Nie mają wpływu na kraje w regionie activeRegionCodes.

Metody

Programami lojalnościowymi możesz zarządzać na te sposoby:

Tworzenie programu lojalnościowego

Aby utworzyć nowy program lojalnościowy dla konta, użyj metody loyaltyPrograms.create. Podaj szczegóły, takie jak opisy programów, adres URL rejestracji i poziomy programu z unikalnymi korzyściami i wymaganiami.

Wymagany parametr program_label ustawia unikalny identyfikator programu lojalnościowego. Na przykład podanie etykiety my-rewards powoduje, że zasób name ma wartość accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

Oto przykładowe żądanie:

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

Zastąp {ACCOUNT_ID} unikalnym identyfikatorem konta Merchant Center.

Oto przykładowa odpowiedź na żądanie, które zostało zrealizowane:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Pobieranie programu lojalnościowego

Aby pobrać szczegóły konkretnego własnego programu lojalnościowego, użyj metody loyaltyPrograms.get.

Oto przykładowe żądanie:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Zastąp {ACCOUNT_ID} identyfikatorem konta, a {PROGRAM_LABEL} unikalną etykietą programu lojalnościowego (np. my-rewards).

Oto przykładowa odpowiedź na żądanie, które zostało zrealizowane:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Wyświetlanie listy programów lojalnościowych

Aby wyświetlić listę wszystkich własnych programów lojalnościowych powiązanych z Twoim kontem, użyj metody loyaltyPrograms.list.

Oto przykładowe żądanie:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

Oto przykładowa odpowiedź na żądanie, które zostało zrealizowane:

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

Aktualizowanie programu lojalnościowego

Aby zaktualizować istniejący program lojalnościowy, użyj metody loyaltyPrograms.update. Wykonaj częściową aktualizację za pomocą update_mask lub pełną wymianę, pomijając maskę. Każda udana aktualizacja powoduje rozpoczęcie nowej weryfikacji redakcyjnej, dlatego wysyłaj aktualizacje tylko wtedy, gdy wartość ulegnie zmianie.

Częściowa aktualizacja z maską aktualizacji

update_mask pozwala określić dokładne pola do zaktualizowania. Modyfikowane są tylko pola wymienione w masce, a pola niewymienione pozostają bez zmian. Wszystkie pola pominięte w masce aktualizacji są ignorowane, nawet jeśli zostały podane w treści żądania.

Poniższe przykładowe żądanie aktualizuje tylko parametry programDescriptions i advancedSettings:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

W tym przykładzie usługa ignoruje signupUrl, ponieważ nie jest on uwzględniony w update_mask. Pole programDescriptions całkowicie zastępuje wszystkie wcześniej skonfigurowane opisy.

Oto przykładowa odpowiedź na udane żądanie:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

Pełne zastąpienie bez maski aktualizacji

Jeśli pominiesz parametr update_mask, żądanie spowoduje całkowite zastąpienie konfiguracji programu lojalnościowego.

Oto przykładowe żądanie:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

Oto przykładowa odpowiedź na udane żądanie:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Usuwanie programu lojalnościowego

Aby usunąć program lojalnościowy z konta, użyj metody loyaltyPrograms.delete.

Oto przykładowe żądanie:

HTTP

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Jeśli operacja się uda, treść odpowiedzi będzie pusta.

Dalsze kroki

Wstecz
Overview
Dalej
Manage customer loyalty data