Zarządzanie katalogiem produktów

Z tego przewodnika dowiesz się, jak za pomocą interfejsu Google Play Developer API utworzyć katalog produktów dla aplikacji w Google Play i nim zarządzać.

Aby sprzedawać produkty w aplikacji za pomocą systemu rozliczeniowego Google Play, musisz utworzyć katalog ze wszystkimi produktami, które chcesz udostępnić użytkownikom. Możesz to zrobić w Konsoli Play lub zautomatyzować zarządzanie katalogiem za pomocą interfejsu Google Play Developer API. Automatyzacja może pomóc zapewnić aktualność katalogu i skalować go do dużych katalogów, w których ręczna koordynacja jest niepraktyczna. Z tego przewodnika dowiesz się, jak za pomocą interfejsu Play Developer API utworzyć katalog produktów swojej aplikacji w Google Play i nim zarządzać. W przewodniku Przygotowanie znajdziesz instrukcje konfigurowania interfejsu Google Play Developer API na potrzeby integracji backendu.

Interfejsy API do zarządzania katalogiem

Aby poznać różne typy produktów, które możesz sprzedawać w ramach systemu rozliczeniowego Google Play, przeczytaj artykuł Typy produktów w aplikacji i kwestie związane z katalogiem. Google oferuje 2 główne zestawy interfejsów API do zarządzania katalogami w Google Play. Odnoszą się one do 2 głównych kategorii usług:

• Produkty kupowane raz
• Produkty objęte subskrypcją

Produkty kupowane raz

Punkt końcowy inappproducts umożliwia zarządzanie produktami jednorazowymi z backendu. Obejmuje to tworzenie, aktualizowanie i usuwanie produktów oraz zarządzanie cenami i dostępnością. W zależności od tego, jak postępujesz z jednorazowymi zakupami produktów, będziesz modelować produkty zużywalne (można kupić tyle razy, ile chcesz) lub trwałe (nie może być 2 razy dokonywane przez tego samego użytkownika). Możesz decydować, które produkty jednorazowo powinny być używane, a które nie.

Produkty objęte subskrypcją

Punkt końcowy monetization.subscriptions ułatwia zarządzanie usługami subskrypcji z backendu dewelopera. Możesz tworzyć, aktualizować i usuwać subskrypcje oraz kontrolować ich regionalną dostępność i ceny. Oprócz punktu końcowego monetization.subscriptions udostępniamy też narzędzia monetization.subscriptions.basePlans i monetization.subscriptions.basePlans.offers do zarządzania abonamentami podstawowymi i ofertami.

Metody wsadowe

Punkty końcowe inappproducts i monetization.subscriptions udostępniają różne metody wsadowe, które umożliwiają jednoczesne pobieranie maksymalnie 100 elementów w tej samej aplikacji i zarządzanie nimi.

Metody wsadowe używane z włączoną tolerancją czasu oczekiwania zapewniają większą przepustowość i są szczególnie przydatne dla programistów tworzących duże katalogi przy wstępnym tworzeniu lub uzgadnianiu katalogu.

Zaktualizuj czas oczekiwania na propagację w porównaniu z przepustowością

Po zrealizowaniu prośby o utworzenie lub modyfikację usługi zmiany mogą nie być od razu widoczne dla użytkowników na ich urządzeniach z powodu opóźnień w przetwarzaniu sieci lub backendu. Domyślnie wszystkie żądania modyfikacji produktów uwzględniają czas oczekiwania. Oznacza to, że są zoptymalizowane pod kątem szybkiego rozpowszechniania się przez systemy backendu i zwykle znajdują się na urządzeniach użytkowników w ciągu kilku minut. Liczba takich zmian jest jednak ograniczona w ciągu godziny. W przypadkach, gdy musisz utworzyć lub zaktualizować wiele produktów (na przykład podczas tworzenia początkowego dużego katalogu), możesz użyć metod wsadowych z polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Znacznie zwiększy to przepustowość aktualizacji. Rozpowszechnienie aktualizacji odpornych na czas oczekiwania na urządzenia użytkowników może potrwać do 24 godzin.

Konfiguracja limitu

Gdy korzystasz z interfejsu 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 interfejsach API do zarządzania katalogiem.
2. Punkty końcowe modyfikacji produktów wymuszają też limit 7200 zapytań na godzinę. Jest to pojedynczy limit obejmujący zarówno produkty kupno kupowanych raz, jak i subskrypcje, a także wszystkie prośby o zmiany, które obejmują utworzenie, aktualizację, aktywację i usunięcie. Wywołania metody modyfikacji wsadowej są liczone jako 1 zapytanie w przypadku tego limitu, niezależnie od liczby uwzględnionych pojedynczych żądań ani ich wrażliwości na czas oczekiwania.
3. Modyfikacje wrażliwe na czas oczekiwania również mają limit 7200 modyfikacji na godzinę. W przypadku metod wsadowych każde żądanie zagnieżdżonej modyfikacji jest zliczane osobno do celów tego limitu. Ten limit ma praktyczne konsekwencje tylko dla użytkowników interfejsu Batch API wykonujących aktualizacje wrażliwe na czas oczekiwania, ponieważ w innych przypadkach limit 2 zostanie wyczerpany przed lub w tym samym czasie co limit.

Oto kilka przykładów wykorzystania limitów różnych żądań:

• Pojedyncze żądanie get pobrania 1 elementu spowoduje wykorzystanie 1 tokenu limitu 1 oraz żadnych tokenów limitu 2 i 3 (ponieważ dotyczy tylko punktów końcowych modyfikacji).
• Żądanie zbiorcze get umożliwiające pobranie maksymalnie 100 elementów również zużywa 1 token limitu 1 i nie wymaga tokenów limitu 2 i 3.
• Jedno żądanie modification dla 1 elementu spowoduje wykorzystanie 1 tokenu limitu 1 i 1 tokena limitu 2. Jeśli żądanie jest wrażliwe na czas oczekiwania, zużywa też 1 token limitu 3. Limit C ma taki sam limit jak limit 2, więc nie ma żadnych praktycznych konsekwencji dla użytkowników korzystających tylko z pojedynczych metod modyfikacji.
• Zbiorcze żądanie modification dotyczące 100 elementów odpornych na czas oczekiwania będzie zajmować 1 token z limitu 1 i 1 token limitu 2. Taka konfiguracja limitu powinna zapewniać wystarczającą marżę na aktualizowanie katalogu, ale jeśli algorytm nie będzie świadomy tego limitu i przekroczy go, przy każdym kolejnym wywołaniu może pojawić się błąd.
• Zbiorcze żądanie modification dotyczące 100 elementów poufnych związanych z czasem oczekiwania spowoduje wykorzystanie 1 tokena limitu 1, 1 tokena limitu 2 i 100 tokenów limitu 3.

Rekomendacje dotyczące korzystania z interfejsu Catalog Management API

Przestrzegając tych wytycznych, optymalizujesz interakcje z interfejsem API, aby zapewnić sprawne i efektywne zarządzanie katalogiem.

Monitorowanie użytkowania

Zwróć uwagę na procesy intensywności użytkowania. Na przykład na początku integracji punkty końcowe zarządzania katalogiem mogą zużywać więcej limitu do utworzenia pełnego katalogu początkowego, co może mieć wpływ na wykorzystanie w środowisku produkcyjnym innych punktów końcowych, takich jak interfejs API stanu zakupu, jeśli zbliżysz się do ogólnego limitu wykorzystania. Musisz monitorować wykorzystanie limitów, aby mieć pewność, że nie przekraczasz limitów interfejsu API. Wykorzystanie można monitorować na kilka sposobów. Możesz na przykład używać panelu limitów interfejsów Google Cloud APIs lub dowolnego innego własnego narzędzia do monitorowania interfejsów API albo narzędzia do monitorowania interfejsów innych firm.

Wykorzystanie limitu interfejsu API Optimize

Zdecydowanie zalecamy optymalizację wykorzystania tempa, aby zminimalizować prawdopodobieństwo błędów interfejsu API. Aby skutecznie wdrożyć tę strategię, zalecamy wykonanie tych czynności:

• Wybierz odpowiednią strategię zarządzania katalogiem. Gdy zrozumiesz limit interfejsów API, musisz wybrać odpowiednią strategię dla swojej aplikacji, aby skutecznie osiągać cele związane z zarządzaniem katalogiem.
• Wykonuj tylko minimalną liczbę połączeń potrzebną do odzwierciedlenia zmian.
• Nie wysyłaj zbędnych ani niepotrzebnych wywołań modyfikacji do interfejsów API. Może to wymagać zachowania historii zmian w katalogu backendu.
• Nie przekraczaj godzinowego limitu modyfikacji produktów wynoszącego 7200 zapytań. Możesz utworzyć procesy synchronizacji, które wymagają wprowadzenia dużej liczby modyfikacji produktów w krótkim czasie (na przykład początkowego utworzenia katalogu). Jeśli spodziewasz się, że te procesy przekroczą limit godzinowy, zaimplementuj funkcję oczekiwania w razie potrzeby, aby zmniejszyć wykorzystanie do bezpiecznego poziomu. Rozważ użycie metod zbiorczych z aktualizacjami odpornymi na opóźnienia, aby uzyskać większą przepustowość.
• Proaktywnie przygotuj się na skalowanie. W miarę rozwoju aplikacji może być konieczne skalowanie korzystania z interfejsu API i różnych punktów końcowych. Zapoznaj się z dokumentacją dotyczącą limitów interfejsu Google Play Developer API, aby dowiedzieć się, jak zwiększyć limit, gdy zbliżasz się do jego osiągnięcia.
• Strategicznie zaplanuj intensywne procesy. Spróbuj zaplanować intensywne procesy katalogu w okresie nagłego szczytu wykorzystania. Możesz na przykład uniknąć przeprowadzania pełnej synchronizacji katalogu w okresach wzmożonej sprzedaży w tygodniu.

Dodaj logikę obsługi błędów limitu

Bez względu na to, jak wydajnie tworzysz logikę zarządzania katalogiem, zadbaj o to, aby była ona odporna na nieoczekiwane limity, ponieważ limit dzienny jest współdzielony przez punkty końcowe używane w niezależnych modułach integracji. Pamiętaj, aby uwzględnić błędy ograniczania limitu w obsłudze błędów i zaimplementować odpowiednie oczekiwanie. Każde wywołanie interfejsów Google Play Developer API powoduje wygenerowanie odpowiedzi. W przypadku niepowodzenia wywołania otrzymasz odpowiedź zawierającą kod stanu odpowiedzi HTTP i obiekt errors z dodatkowymi informacjami o domenie błędu i komunikatem debugowania. Jeśli na przykład 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 używają punktów końcowych publikowania produktów w interfejsie Google Play Developer API, aby synchronizować katalog między backendem a Google Play. Dbanie o to, aby katalog Google Play był zawsze aktualny i zawierał najświeższe informacje z backendu, ma większe zalety dla użytkowników. Na przykład:

• Będziesz mieć możliwość przeglądania całej listy dostępnych ofert oraz zarządzania tagami ofert i abonamentów podstawowych, aby wpływać na to, czy kwalifikujesz się do skorzystania z oferty i wyświetlać logikę.
• Możesz sprawdzić różne pułapy cenowe i szczegóły produktów, które użytkownicy widzą na różnych platformach, i zadbać o ich spójność.
• Szczegóły produktu będą dostępne w Twoim backendzie podczas przetwarzania nowych zakupów bez konieczności zwiększania czasu oczekiwania i ryzyka niepowodzenia przez wywoływanie interfejsu Google Play Developer API w trakcie procesów o znaczeniu krytycznym dla użytkownika.

Tworząc katalog produktów w Google Play, musisz pamiętać o pewnych ograniczeniach i kwestii. Gdy zrozumiesz te limity i ustalisz strukturę katalogu, musisz wybrać strategię synchronizacji.

Strategie synchronizacji katalogu

Punkty końcowe publikowania interfejsu Google Play Developer API umożliwiają aktualizowanie katalogu w miarę ich występowania. Czasami możesz potrzebować okresowych aktualizacji, aby przesłać cały zestaw zmian w ramach tego samego procesu. Każde podejście wymaga innego wyboru. Każda strategia synchronizacji sprawdzi się lepiej w niektórych przypadkach użycia. W zależności od sytuacji możesz mieć różne potrzeby, które przemawiają do obu tych grup. Czasami możesz chcieć zaktualizować produkt, gdy tylko dowiesz się o nowej zmianie, np.aby przetworzyć pilną aktualizację produktu (np. jak najszybciej poprawić nieprawidłową cenę). Możesz też skorzystać z okresowej synchronizacji w tle, aby zadbać o spójność backendów i katalogów Play. Zapoznaj się z typowymi przypadkami użycia, w których warto wdrożyć te różne strategie zarządzania katalogiem.

Kiedy wysyłać aktualizacje po zmianie katalogu lokalnego

Aby zminimalizować rozbieżności, aktualizacje powinny być przeprowadzane natychmiast po wprowadzeniu zmian w katalogu usług backendu.

Tego typu aktualizacje to dobre rozwiązanie, gdy:

• Musisz dbać 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 wersji produkcyjnej i są sprzedawane.

Takie podejście jest łatwiejsze w implementacji i pozwala synchronizować katalog z minimalnym oknem rozbieżności.

Kiedy okresowo korzystać z aktualizacji

Okresowe aktualizacje są przeprowadzane asynchronicznie do wersji usługi w Twoim backendzie. Mogą się przydać, gdy:

• Nie musisz pilnować, aby produkty były aktualizowane z wyprzedzeniem.
• Musisz zaplanować aktualizacje zbiorcze lub procesy uzgodnień.
• Masz już system zarządzania treścią lub katalogiem do obsługi produktów cyfrowych, który stale aktualizuje Twój katalog

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

Tworzenie katalogu produktów

Jeśli masz do przesłania duży katalog do Google Play, warto zautomatyzować wczytywanie początkowe. Ten rodzaj ciężkiego procesu działa najlepiej, gdy stosowana jest strategia okresowa w połączeniu z metodami wsadowymi odpornymi na czas oczekiwania.

Tworzenie produktów kupowanych raz

W przypadku jednorazowego tworzenia dużego katalogu produktów zalecamy użycie metody inappproducts.batchUpdate z polem allowMissing ustawionym na true i polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Skraca to czas tworzenia 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 w sposób opisany w sekcji Aktualizacje produktów. Dzięki temu skrypt nie musi być stanowy i w razie potrzeby można go uruchomić ponownie od zera.

Tworzenie produktów objętych subskrypcją

Do początkowego tworzenia dużego katalogu subskrypcji zalecamy użycie metody monetization.subscriptions.batchUpdate z polem allowMissing ustawionym na true i latencyTolerancepolem ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Skraca to czas tworzenia 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.update z parametrem allowMissing w sposób opisany w sekcji Aktualizacje produktów.

Wszystkie wcześniejsze metody tworzą subskrypcje wraz z abonamentami podstawowymi (podawanymi w obiekcie subskrypcji). 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. Punkt końcowy monetization.subscriptions.basePlans.offers umożliwia też tworzenie ofert i zarządzanie nimi.

Nowości w usłudze

Podane niżej metody umożliwiają efektywne modyfikowanie dotychczasowych produktów przez dopilnowanie, aby oferta była dopasowana do ostatnich korekt.

Aktualizowanie produktów kupowanych raz

Są 3 metody, które pomogą Ci zaktualizować dotychczasowe produkty kupowane raz.

• inappproducts.patch: punkt końcowy poprawki jest używany do częściowej aktualizacji zasobu. Oznacza to, że możesz aktualizować określone pola określone w treści żądania. Punkt końcowy poprawki jest zwykle używany, gdy trzeba zaktualizować tylko kilka pól zasobu.
• inappproducts.update: punkt końcowy aktualizacji służy do aktualizowania całego zasobu. Oznacza to, że musisz wysłać cały obiekt zasobu w treści żądania. Punkt końcowy aktualizacji jest zwykle używany wtedy, gdy trzeba zaktualizować wszystkie pola w zasobie. Gdy parametr allowMissing ma wartość true, a podany identyfikator produktu jeszcze nie istnieje, punkt końcowy wstawi produkt, zamiast generować błąd.
• inappproducts.batchUpdate: 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żywaj go w połączeniu z polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT.

Aktualizowanie produktów objętych subskrypcją

Aby zaktualizować obecne subskrypcje, możesz użyć metody monetization.subscriptions.patch. Ta metoda przyjmuje te wymagane parametry:

• 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. Jest to rozdzielona przecinkami lista pól, które chcesz zaktualizować.

Jeśli na przykład chcesz zaktualizować tylko informacje o produkcie objętym subskrypcją, wpisz w polu listings parametr updateMask.

Możesz użyć narzędzia monetization.subscriptions.batchUpdate, aby zaktualizować wiele subskrypcji jednocześnie. Aby uzyskać większą przepustowość, używaj go w połączeniu z polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT.

Aby aktywować, dezaktywować i dezaktywować abonamenty podstawowe lub przenieść subskrybentów do najnowszych wersji cen abonamentu podstawowego, użyj punktu końcowego monetization.subscriptions.basePlans.

Możesz też aktualizować oferty abonamentów podstawowych za pomocą metody monetization.subscriptions.basePlans.offers.patch.

Uzgadnianie katalogu

Niezależnie od tego, czy aktualizujesz katalog Google Play po każdej zmianie katalogu backendu czy okresowo, w przypadku systemu zarządzania katalogiem lub bazy danych spoza katalogu Google Play może się zdarzyć, że przestanie on być zsynchronizowany z katalogiem w konfiguracji aplikacji w Google Play. Może to być spowodowane awaryjnymi zmianami w katalogu w konsoli, przerwą w działaniu systemu zarządzania katalogiem lub utratą najnowszych danych.

Aby uniknąć długiego okresu rozbieżności, możesz utworzyć proces uzgadniania katalogu.

Uwzględnienie systemu różnic

Zalecamy stworzenie systemu różnic w celu wykrywania niespójności i uzgodnienia obu systemów. Oto kilka kwestii, które warto wziąć pod uwagę podczas tworzenia systemu różnic, który pomoże w zachowaniu synchronizacji katalogów:

• Informacje o modelach danych: najpierw musisz poznać modele danych w CMS dla programistów i interfejs Google Play Developer API. Obejmuje to znajomość różnych typów danych przechowywanych w poszczególnych systemach oraz tego, jak są one mapowane na siebie.
• Definiowanie reguł różnic: gdy poznasz modele danych, musisz zdefiniować reguły różnic. Reguły te określają sposób porównywania danych z obu systemów. Możesz na przykład dopasować identyfikatory produktów i porównać kluczowe atrybuty subskrypcji oraz powiązanych z nią abonamentów podstawowych i ofert.
• Zaimplementuj algorytm różnic: po zdefiniowaniu reguł różnic musisz wdrożyć algorytm diff. Algorytm ten pobierze dane z obu systemów i porówna je zgodnie ze zdefiniowanymi 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 generuje raport dotyczący różnic. Ten raport ukazuje różnice między tymi systemami.
• Uzgadniaj różnice: po wygenerowaniu raportu różnic musisz rozwiązać różnice. Może to wymagać aktualizacji danych w systemie CMS lub aktualizacji danych po stronie Google Play za pomocą punktów końcowych zarządzania katalogiem Developer API w zależności od tego, jak zwykle aktualizujesz katalog. Aby uzgodnić usługi synchronizacji, użyj punktów końcowych aktualizacji zgodnie z opisem w sekcji Aktualizacje usług.

Wycofanie usług

Interfejs Google Play Developer API udostępnia kilka metod, które pomagają deweloperom w wycofaniu produktów: inappproducts.delete i inappproducts.batchDelete w przypadku produktów kupowanych raz oraz monetization.subscriptions.delete w przypadku subskrypcji. Wycofanie usługi może być konieczne w różnych sytuacjach, na przykład:

• Utworzony przez pomyłkę.
• Wycofanie funkcji lub usługi.

Zalecamy włączenie wycofywania usług w swojej strategii zarządzania katalogiem.

Wycofanie produktów kupowanych raz

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

Wycofywanie produktów objętych subskrypcją

Subskrypcje możesz usuwać za pomocą metody monetization.subscriptions.delete. Po aktywowaniu co najmniej 1 abonamentu podstawowego nie można usunąć subskrypcji.