Zarządzanie katalogiem produktów

Z tego przewodnika dowiesz się, jak używać interfejsu Google Play Developer API do tworzenia katalogu produktów w aplikacji Play i zarządzania nim.

Aby sprzedawać produkty w aplikacji za pomocą systemu rozliczeniowego Google Play, musisz skonfigurować katalog ze wszystkimi produktami, które chcesz udostępnić użytkownikom do zakupu. Możesz to zrobić w Konsoli Play lub zautomatyzować zarządzanie katalogiem za pomocą interfejsu API Google Play Developer. Automatyzacja może pomóc w zapewnieniu, że katalog jest zawsze aktualny, oraz skalowaniu go do dużych katalogów, w których ręczna koordynacja jest niepraktyczna. W tym przewodniku dowiesz się, jak używać interfejsu Play Developer API do tworzenia katalogu produktów w aplikacji w Google Play i zarządzania nim. Zapoznaj się z naszym przewodnikiem Przygotowania, aby dowiedzieć się, jak skonfigurować interfejs Play Developer API do integracji z backendem.

Interfejsy API do zarządzania katalogiem

Informacje o różnych typach produktów, które możesz sprzedawać za pomocą systemu rozliczeniowego Google Play, znajdziesz w artykule Typy produktów w aplikacji i uwagi dotyczące katalogu. Google oferuje 2 główne zestawy interfejsów API do zarządzania katalogiem w Google Play, które odpowiadają 2 głównym kategoriom produktów:

  • Produkty kupowane raz
  • Produkty objęte subskrypcją

Produkty kupowane raz

Punkt końcowy inappproducts umożliwia zarządzanie produktami jednorazowymi z poziomu backendu. Obejmuje to tworzenie, aktualizowanie i usuwanie produktów oraz zarządzanie cenami i dostępnością. W zależności od tego, jak obsługujesz jednorazowe zakupy produktów, możesz modelować produkty jednorazowe (można je kupić dowolną liczbę razy) lub stałe uprawnienia (nie można ich kupić dwukrotnie przez tego samego użytkownika). Możesz zdecydować, które produkty jednorazowe mają być zużywalne, a które nie.

Produkty objęte subskrypcją

Punkt końcowy monetization.subscriptions pomaga zarządzać produktami z subskrypcją z poziomu backendu dewelopera. Możesz tworzyć, aktualizować i usuwać subskrypcje oraz kontrolować ich dostępność i ceny w poszczególnych regionach. Oprócz punktu końcowego monetization.subscriptions udostępniamy też punkty końcowe monetization.subscriptions.basePlans i monetization.subscriptions.basePlans.offers, które umożliwiają odpowiednio zarządzanie abonamentami i abonamentami podstawowymi.

Metody zbiorcze

Punkty końcowe inappproducts i monetization.subscriptions udostępniają kilka metod zbiorczych, które umożliwiają jednoczesne pobieranie lub zarządzanie maksymalnie 100 elementami w ramach tej samej aplikacji.

Metody zbiorcze, gdy są używane z włączoną tolerancją opóźnienia, zapewniają większą przepustowość i są szczególnie przydatne dla deweloperów dużych katalogów na potrzeby tworzenia katalogu lub jego uzgadniania.

Aktualizacja opóźnienia propagacji w porównaniu z przepustowością

Po zakończeniu tworzenia produktu lub modyfikacji prośby o jego utworzenie zmiany mogą nie być widoczne od razu na urządzeniach użytkowników z powodu opóźnień w przetwarzaniu na poziomie sieci lub zaplecza. Domyślnie wszystkie żądania modyfikacji produktów są podatne na opóźnienia. Oznacza to, że są one optymalizowane pod kątem szybkiego rozprzestrzeniania się w systemach backendowych i zwykle odzwierciedlają się na urządzeniach użytkowników w ciągu kilku minut. Istnieje jednak godzinowy limit liczby takich próśb. Jeśli chcesz utworzyć lub zaktualizować wiele produktów (np. podczas tworzenia dużego katalogu), możesz użyć metod zbiorczych z ustawionym zestawem pól latencyTolerance PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Znacznie zwiększy to przepustowość aktualizacji. Zastosowanie aktualizacji odpornych na opóźnienia na urządzeniach użytkowników może potrwać do 24 godzin.

Konfiguracja limitu

Jeśli korzystasz z Play Developer API do zarządzania katalogiem produktów, musisz pamiętać o kilku limitach:

  1. Interfejsy Google Play Developer API mają domyślny limit 200 tys. zapytań dziennie. Ten limit dotyczy agregacji wykorzystania we wszystkich punktach końcowych, w tym interfejsów API do zarządzania katalogiem.
  2. Punkty końcowe modyfikacji produktu również narzucają limit 7200 zapytań na godzinę. Jest to jeden limit dla wszystkich produktów jednorazowych i subskrypcji oraz wszystkich próśb o modyfikację, w tym tworzenia, aktualizowania, aktywowania i usuwania. Wywołania metody zbiorczej modyfikacji są traktowane jako jedno zapytanie w ramach tej puli, niezależnie od liczby uwzględnionych indywidualnych żądań i ich wrażliwości na opóźnienia.
  3. Modyfikacje, które mogą powodować opóźnienia, mają też limit 7200 modyfikacji na godzinę. W przypadku metod zbiorczych każda zagnieżdżona prośba o modyfikację jest liczona osobno na potrzeby tego limitu. Ten limit ma praktyczne konsekwencje tylko w przypadku użytkowników interfejsu API do wykonywania zbiorczych operacji aktualizujących, które są wrażliwe na opóźnienia. W innych przypadkach limit 2 zostanie wyczerpany przed lub w tym samym czasie co ten limit.

Oto kilka przykładów, które pomogą Ci zrozumieć wykorzystanie limitu w różnych żądaniach:

  • Pojedyncze żądanie get służące do pobierania 1 elementu zużywa 1 token z limitu 1 i żaden z limitów 2 i 3 (ponieważ dotyczą one tylko punktów końcowych modyfikacji).
  • Żądanie zbiorcze get służące do pobierania do 100 elementów spowoduje wykorzystanie 1 tokena z limitu 1 i żadnego z limitów 2 i 3.
  • Pojedyncze żądanie modification dotyczące jednego elementu spowoduje wykorzystanie 1 tokena limitu 1 i 1 tokena limitu 2. Jeśli żądanie jest wrażliwe na opóźnienia, zużyje też 1 znacznik z limitu 3. Ponieważ limit w przypadku puli C jest taki sam jak w przypadku puli 2, nie ma on praktycznego znaczenia dla użytkowników korzystających tylko z jednego sposobu modyfikacji.
  • Żądanie zbiorcze modification dotyczące 100 elementów z dopuszczalną latencją wykorzysta 1 token limitu 1 i 1 token limitu 2. Ta konfiguracja limitu powinna zapewnić wystarczającą ilość miejsca na bieżące aktualizowanie katalogu, ale jeśli Twój algorytm nie jest świadomy tego limitu i przekracza go, możesz otrzymać błąd za każde dodatkowe wywołanie.
  • Zbiorcze żądanie modification dotyczące 100 elementów wrażliwych na opóźnienia spowoduje wykorzystanie 1 tokena z limitu 1, 1 tokena z limitu 2 i 100 tokenów z limitu 3.

Zalecenia dotyczące korzystania z interfejsu API zarządzania katalogiem

Dzięki przestrzeganiu tych wytycznych możesz zoptymalizować interakcje z interfejsem API, co zapewni płynne i efektywne zarządzanie katalogiem.

Monitorowanie wykorzystania

Pamiętaj o procesach intensywnego wykorzystania. Na przykład na początku integracji punkty końcowe zarządzania katalogiem prawdopodobnie zużywają więcej limitu, aby utworzyć pełny początkowy katalog. Może to potencjalnie wpłynąć na korzystanie z innych punktów końcowych w wersji produkcyjnej, takich jak interfejs API stanu zakupu, jeśli jesteś blisko ogólnego limitu wykorzystania. Musisz monitorować wykorzystanie limitu, aby mieć pewność, że nie przekraczasz limitów interfejsu API. Istnieje kilka sposobów monitorowania wykorzystania. Możesz na przykład użyć panelu limitów interfejsów API Google Cloud lub dowolnego wewnętrznego lub zewnętrznego narzędzia do monitorowania interfejsów API.

Optymalizacja wykorzystania limitu interfejsu API

Zalecamy optymalizację współczynnika wykorzystania, aby zminimalizować prawdopodobieństwo wystąpienia błędów interfejsu API. Aby skutecznie wdrożyć tę funkcję, zalecamy:

  • Wybierz odpowiednią strategię zarządzania katalogiem. Gdy już poznasz limit interfejsu API, musisz wybrać odpowiednią strategię dla swojej aplikacji, aby skutecznie osiągnąć cele związane z zarządzaniem katalogiem.
  • Wykonuj tylko minimalną liczbę połączeń, która jest potrzebna do wprowadzenia zmian.
  • Nie wysyłaj do interfejsów API zbędnych ani niepotrzebnych wywołań metod modyfikacji. Może to wymagać przechowywania informacji o zmianach w katalogu na serwerze.
  • Nie przekraczaj limitu godzinnego modyfikacji produktu wynoszącego 7200 zapytań. Możesz tworzyć procesy synchronizacji, które wymagają wprowadzenia dużej liczby modyfikacji produktów w krótkim czasie (np. początkowe tworzenie katalogu). Jeśli przewidujesz, że te procesy przekroczą limit godzinny, wprowadź opóźnienia, aby spowolnić wykorzystanie do bezpiecznego poziomu. Aby zwiększyć przepustowość, rozważ użycie metod przetwarzania w grupach z uwzględnieniem opóźnień.
  • Proaktywnie przygotuj się do skalowania. W miarę rozwoju aplikacji może być konieczne zwiększenie skali korzystania z interfejsu API i różnych punktów końcowych. Aby dowiedzieć się, jak zwiększyć limit, gdy zbliżasz się do maksymalnego użycia, zapoznaj się z dokumentacją dotyczącą limitów interfejsu API dla deweloperów Google Play.
  • Strategicznie planuj intensywne procesy. Staraj się zaplanować procesy związane z katalogiem na czasy największego obciążenia, na przykład unikaj pełnej synchronizacji katalogu w szczytowym okresie sprzedaży w tygodniu.

Dodawanie logiki obsługi błędów związanych z limitem

Niezależnie od tego, jak skutecznie tworzysz logikę zarządzania katalogiem, musisz ją zabezpieczyć przed nieoczekiwanymi limitami kwoty, ponieważ dzienny limit jest współdzielony przez punkty końcowe używane w niezależnych modułach integracji. Pamiętaj, aby uwzględnić błędy związane z ograniczeniem przepustowości w obsługiwaniu błędów i wdrożyć odpowiednie opóźnienia. Każde wywołanie interfejsów Google Play Developer API spowoduje otrzymanie odpowiedzi. W przypadku niepowodzenia wywołania otrzymasz odpowiedź z kodem stanu odpowiedzi HTTP i obiektem errors, który zawiera dodatkowe informacje o domenie błędu i komunikat debugowania. Jeśli np. przekroczysz limit dzienny, może pojawić się błąd podobny do tego:

{
  "code" : 403,
  "errors" : [ {
    "domain" : "usageLimits",
    "message" : "Daily Limit Exceeded. The quota will be reset at midnight Pacific Time (PT). You may monitor your quota usage and adjust limits in the API
  Console: https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxxx",
  "reason" : "dailyLimitExceeded",
  "extendedHelp" : "https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxx"
  } ],
}

Wdrożenie zarządzania katalogiem

Deweloperzy korzystają z punktów końcowych interfejsu Google Play Developer API do publikowania produktów, aby zachować synchronizację katalogu między backendem a Google Play. Dbanie o to, aby katalog Google Play był zawsze aktualny i odzwierciedlał najnowsze informacje z katalogu na zapleczu, ma wiele zalet, które przekładają się na większą wygodę użytkowników. Przykład:

  • Możesz zapoznać się z całą listą dostępnych ofert i zarządzać tagami ofert i abonamentów podstawowych, aby wpływać na kryteria kwalifikowania się i logikę wyświetlania ofert.
  • Możesz sprawdzić różne pułapy cenowe i szczegóły produktów, które użytkownicy widzą na różnych platformach, i upewnić się, że są one spójne.
  • Podczas przetwarzania nowych zakupów będziesz mieć pod ręką szczegóły produktów w backendzie, bez konieczności zwiększania opóźnień i ryzyka niepowodzenia przez dodatkowe wywołania interfejsu Google Play Developer API podczas kluczowych procesów użytkownika.

Podczas tworzenia katalogu produktów w Google Play należy pamiętać o pewnych ograniczeniach i uwzględniać pewne kwestie. Gdy już poznasz te limity i wiesz, jaką strukturę nadać katalogowi, czas na wybór strategii synchronizacji.

Strategie synchronizacji katalogu

Punkty końcowe interfejsu Google Play Developer API umożliwiają wprowadzanie zmian w katalogu w miarę ich występowania. Czasami konieczne może być okresowe aktualizowanie danych, czyli wysyłanie wielu zmian w ramach tego samego procesu. Każde z tych podejść wymaga innych decyzji projektowych. Każda strategia synchronizacji lepiej sprawdzi się w niektórych zastosowaniach niż w innych. W zależności od sytuacji możesz mieć potrzeby, które wymagają stosowania obu strategii. Czasami możesz chcieć zaktualizować produkt, gdy tylko dowiesz się o nowej zmianie, na przykład aby przetworzyć pilną aktualizację produktu (np. gdy niezwłocznie trzeba poprawić nieprawidłową cenę). W innych przypadkach możesz użyć okresowej synchronizacji w tle, aby mieć pewność, że twój backend i katalogi w Google Play są zawsze spójne. Zapoznaj się z kilkoma typowymi przypadkami użycia, w których warto zastosować różne strategie zarządzania katalogiem.

Kiedy wysyłać aktualizacje w przypadku zmian w lokalnym katalogu

W idealnej sytuacji aktualizacje powinny być przeprowadzane od razu po wprowadzeniu zmian w katalogu produktów na serwerze, aby zminimalizować rozbieżności.

Ten typ aktualizacji jest dobrym rozwiązaniem, gdy:

  • Musisz zadbać o to, aby Twoje produkty były zawsze aktualne.
  • Musisz wprowadzić kilka zmian w produktach każdego dnia.
  • Musisz zaktualizować produkty, które są już w produkcji i są sprzedawane.

To podejście jest łatwiejsze do wdrożenia i pozwala zachować synchronizację katalogu z najmniejszym oknem rozbieżności kwot.

Kiedy używać okresowych aktualizacji

Aktualizacje okresowe są wykonywane asynchronicznie w stosunku do wersji produktu na zapleczu. Są one dobrym rozwiązaniem, gdy:

  • Nie musisz aktualizować produktów w krótkim czasie.
  • Musisz zaplanować aktualizacje zbiorcze lub procesy uzgadniania.
  • masz już system zarządzania treściami lub katalogiem, który obsługuje Twoje produkty cyfrowe i stale aktualizuje katalog;

W przypadku dużych katalogów rozważ użycie metod zbiorczych z aktualizacjami odpornymi na opóźnienia, aby uzyskać maksymalną przepustowość.

Tworzenie katalogu produktów

Jeśli masz duży katalog, który chcesz przesłać do Google Play, możesz zautomatyzować początkowe przesyłanie. Ten typ czasochłonnego procesu sprawdza się najlepiej, jeśli stosujesz strategię okresową połączoną z metodami przetwarzania w partiach, które są odporne na opóźnienia.

Tworzenie produktów kupowanych raz

W przypadku początkowego jednorazowego utworzenia dużego katalogu produktów zalecamy użycie metody inappproducts.batchUpdate z ustawieniem pola allowMissing na true i pola latencyTolerance na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Pozwoli to zminimalizować czas potrzebny na utworzenie katalogu w ramach limitów.

W przypadku mniejszych katalogów możesz użyć metody inapp_products.insert. Możesz też użyć metody inappproducts.update z parametrem allowMissing, jak opisano w sekcji Aktualizacje usługi. Dzięki temu nie musisz tworzyć skryptu z uwzględnieniem stanu. Jeśli coś pójdzie nie tak, możesz go uruchomić od początku.

Tworzenie produktów z subskrypcją

W przypadku początkowego tworzenia dużego katalogu subskrypcji zalecamy użycie metody monetization.subscriptions.batchUpdate z ustawieniem pola allowMissing na true i latencyTolerance na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Pozwoli to zminimalizować czas potrzebny na utworzenie katalogu w ramach limitów.

W przypadku mniejszych katalogów subskrypcji interfejs Play Developer API udostępnia metodę monetization.subscriptions.create. Możesz też utworzyć subskrypcje za pomocą metody monetization.subscriptions.patch z parametrem allowMissing, jak opisano w sekcji Aktualizacje usługi.

Wszystkie wcześniejsze metody tworzą subskrypcje wraz z abonamentami podstawowymi (dostarczają je w obiekcie Subscription). Te abonamenty podstawowe są początkowo nieaktywne. Aby zarządzać stanem abonamentów podstawowych, możesz użyć punktu końcowego monetization.subscriptions.basePlans, w tym aktywować abonament podstawowy, aby udostępnić go do zakupu. Dodatkowo punkt końcowy monetization.subscriptions.basePlans.offers umożliwia tworzenie ofert i zarządzanie nimi.

Aktualizacje produktowe

Podane niżej metody umożliwiają skuteczną modyfikację dotychczasowych produktów, dzięki czemu oferty będą zgodne z najnowszymi zmianami.

Aktualizowanie produktów jednorazowych

Dostępne są 3 metody aktualizacji dotychczasowych produktów jednorazowych.

  • inappproducts.patch: punkt końcowy poprawki służy do częściowej aktualizacji zasobu. Oznacza to, że możesz aktualizować określone pola, które podasz w ciele żądania. Punkt końcowy patch jest zwykle używany, gdy trzeba zaktualizować tylko kilka pól zasobu.
  • inappproducts.update: punkt końcowy aktualizacji służy do aktualizowania zasobu w całości. Oznacza to, że w treści żądania musisz przesłać cały obiekt zasobu. Punkt końcowy update jest zwykle używany, gdy trzeba zaktualizować wszystkie pola w zasobie. Jeśli parametr allowMissing ma wartość true, a podany identyfikator produktu nie istnieje, punkt końcowy wstawi produkt zamiast zakończyć działanie.
  • inappproducts.batchUpdate: jest to wersja zbiorcza punktu końcowego aktualizacji, która umożliwia modyfikowanie wielu produktów za pomocą jednego zapytania. Aby uzyskać większą przepustowość, użyj go razem z polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT.

Aktualizowanie produktów subskrypcji

Aby zaktualizować istniejące subskrypcje, możesz użyć metody monetization.subscriptions.patch. Ta metoda wymaga podania tych parametrów:

  • packageName: nazwa pakietu aplikacji, do której należy subskrypcja.
  • productId: unikalny identyfikator produktu subskrypcji.
  • regionsVersion: wersja konfiguracji regionu.

Jeśli nie tworzysz nowej subskrypcji za pomocą parametru allowMissing, musisz podać parametr updateMask. Ten parametr to lista pól, które chcesz zaktualizować, rozdzielona przecinkami.

Jeśli na przykład chcesz zaktualizować tylko informacje o produkcie z subskrypcją, pole listings należy ustawić jako parametr updateMask.

Aby zaktualizować wiele subskrypcji jednocześnie, możesz użyć monetization.subscriptions.batchUpdate. Aby uzyskać większą przepustowość, użyj go razem z polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT.

Aby aktywować, dezaktywować lub usunąć abonamenty podstawowe albo przenieść subskrybentów na najnowsze wersje cen abonamentu podstawowego, użyj punktu końcowego monetization.subscriptions.basePlans.

Dodatkowo możesz zaktualizować oferty abonamentów podstawowych za pomocą metody monetization.subscriptions.basePlans.offers.patch.

Uzgadnianie katalogu

Niezależnie od tego, czy zdecydujesz się aktualizować katalog Google Play za każdym razem, gdy katalog backendu ulegnie zmianie, czy okresowo, jeśli masz system zarządzania katalogiem lub bazę danych poza katalogiem Google Play, mogą wystąpić sytuacje, w których katalog nie będzie zgodny z katalogiem w konfiguracji aplikacji w Google Play. Może to być spowodowane nagłymi ręcznymi zmianami w katalogu w konsoli, awarią systemu zarządzania katalogiem lub utratą najnowszych danych.

Aby uniknąć wydłużonego okna rozbieżności, możesz utworzyć proces uzgadniania katalogu.

Uwzględnienie systemu różnic

Zalecamy skonfigurowanie systemu porównywania, aby wykrywać niespójności i zgodność obu systemów. Oto kilka kwestii, które warto wziąć pod uwagę podczas tworzenia systemu porównywania, aby utrzymać synchronizację katalogów:

  • Poznanie modeli danych: pierwszym krokiem jest poznanie modeli danych w systemie CMS dewelopera i interfejsie Google Play Developer API. Obejmuje to znajomość różnych typów danych przechowywanych w każdym systemie oraz sposobu mapowania różnych elementów danych.
  • Zdefiniuj reguły różnic: gdy już poznasz modele danych, musisz zdefiniować reguły różnic. Te reguły określają sposób porównywania danych w obu systemach. Możesz na przykład dopasowywać identyfikatory produktów i porównywać kluczowe atrybuty subskrypcji oraz powiązanych z nią abonamentów podstawowych i ofert.
  • Wdróż algorytm porównywania: po zdefiniowaniu reguł porównywania musisz wdrożyć algorytm porównywania. Ten algorytm pobierze dane z obu systemów i porówna je zgodnie z określonymi przez Ciebie regułami. Aby pobrać dane katalogu z Google Play, możesz użyć metod inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list i monetization.subscriptions.batchGet.
  • Generowanie raportów różnic: algorytm różnic wygeneruje raport różnic. Ten raport będzie zawierać różnice między obydwoma systemami.
  • Pojednanie różnic: po wygenerowaniu raportu różnic musisz uzgodnić różnice. Może to wymagać zaktualizowania danych w systemie CMS lub zaktualizowania danych po stronie Google Play za pomocą punktów końcowych interfejsu API dla deweloperów do zarządzania katalogiem, w zależności od tego, jak zwykle aktualizujesz katalog. Aby zrekompensować brak synchronizacji produktów, użyj punktów końcowych aktualizacji zgodnie z opisem w sekcji Aktualizacje produktów.

Wycofanie usługi

Interfejs Google Play Developer API oferuje kilka metod, które pomagają deweloperom wycofywać produkty: inappproducts.delete i inappproducts.batchDelete w przypadku produktów kupowanych raz oraz monetization.subscriptions.delete w przypadku subskrypcji. Wycofanie produktu może być konieczne w różnych sytuacjach, takich jak:

  • Tworzenie przez pomyłkę.
  • wycofanie funkcji lub usługi.

Zalecamy uwzględnienie wycofywania produktów w swojej strategii zarządzania katalogiem.

Wycofanie produktów kupowanych raz

Aby usunąć produkty jednorazowe za pomocą interfejsu Google Play Developer API, musisz użyć metody inappproducts.delete lub inappproducts.batchDelete.

Wycofanie produktów objętych subskrypcją

Subskrypcje możesz usuwać, korzystając z metody monetization.subscriptions.delete. Subskrypcji nie można usunąć, gdy aktywowano co najmniej 1 abonament podstawowy.