Zarządzanie katalogiem produktów

Z tego przewodnika dowiesz się, jak używać interfejsu Google Play Developer API do tworzenia katalogu produktów dla aplikacji w Google 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 Google Play Developer API. Automatyzacja może pomóc w zapewnieniu, że katalog jest zawsze aktualny, a także w skalowaniu 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 tworzyć katalog produktów i nim zarządzać w przypadku aplikacji w Google Play. Zapoznaj się z naszym przewodnikiem Przygotowanie, aby uzyskać instrukcje konfigurowania interfejsu Google Play Developer API na potrzeby integracji z backendem.

Interfejsy API do zarządzania katalogiem

Więcej informacji 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

Produkty kupowane raz (wcześniej nazywane produktami w aplikacji) korzystają z modelu obiektowego produktów kupowanych raz, który umożliwia skonfigurowanie wielu opcji zakupu i ofert dla produktów kupowanych raz. Model obiektowy produktów kupowanych raz zapewnia większą elastyczność w zakresie sprzedaży produktów i ułatwia zarządzanie nimi. Obecne produkty w aplikacji zostaną przeniesione do modelu obiektowego produktów kupowanych raz. Więcej informacji znajdziesz w artykule Migracja produktów w aplikacji.

Punkty końcowe monetization.onetimeproducts i inappproducts umożliwiają zarządzanie produktami kupowanymi raz 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 zakupy produktów kupowanych raz, możesz modelować produkty konsumpcyjne (można je kupować dowolną liczbę razy) lub uprawnienia stałe (nie mogą być kupione 2 razy przez tego samego użytkownika). Możesz zdecydować, które produkty kupowane raz mają być konsumpcyjne, a które nie.

Produkty objęte subskrypcją

Punkt końcowy monetization.subscriptions pomaga zarządzać produktami subskrypcyjnymi z poziomu backendu dewelopera. Możesz na przykład tworzyć, aktualizować i usuwać subskrypcje oraz kontrolować ich regionalną dostępność i ceny. Oprócz punktu końcowego monetization.subscriptions udostępniamy też punkty monetization.subscriptions.basePlans i monetization.subscriptions.basePlans.offers, które służą do zarządzania odpowiednio abonamentami podstawowymi i ofertami subskrypcji.

Metody wsadowe

Punkty końcowe onetimeproducts, inappproducts i monetization.subscriptions udostępniają wiele metod wsadowych, które umożliwiają pobieranie lub zarządzanie maksymalnie 100 podmiotami w ramach tej samej aplikacji w tym samym czasie.

Metody wsadowe, gdy są używane z włączoną tolerancją opóźnienia, obsługują większą przepustowość i są szczególnie przydatne dla deweloperów dużych katalogów podczas tworzenia początkowego katalogu lub jego uzgadniania.

Opóźnienie propagacji a przepustowość

Po zrealizowaniu prośby o utworzenie lub zmodyfikowanie produktu zmiany mogą nie być od razu widoczne dla użytkowników na ich urządzeniach z powodu opóźnień w przetwarzaniu w sieci lub na serwerze backendu. Domyślnie wszystkie żądania modyfikacji produktu są wrażliwe na opóźnienia. Oznacza to, że są one zoptymalizowane pod kątem szybkiego rozpowszechniania w systemach backendu, co zwykle odzwierciedla się na urządzeniach użytkowników w ciągu kilku minut. Obowiązuje jednak godzinny limit liczby takich próśb o zmianę. Jeśli musisz utworzyć lub zaktualizować wiele produktów (np. podczas tworzenia 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. Wprowadzenie zmian w przypadku aktualizacji odpornych na opóźnienia może potrwać do 24 godzin.

Konfiguracja limitu

Podczas korzystania z interfejsu Play Developer API do zarządzania katalogiem produktów musisz pamiętać o kilku limitach:

  1. Interfejsy Google Play Developer API są podzielone na kategorie zwane zasobnikami. Każdy zasobnik ma własny limit minutowy. Więcej informacji znajdziesz w artykule o limitach.
  2. Punkty końcowe modyfikacji produktu również mają limit 7200 zapytań na godzinę. Jest to jeden limit obejmujący zarówno produkty jednorazowe, jak i subskrypcje oraz wszystkie żądania modyfikacji, w tym tworzenie, aktualizowanie, aktywowanie i usuwanie. Wywołania metody modyfikacji zbiorczej liczą się jako 1 zapytanie w ramach tego limitu, niezależnie od liczby uwzględnionych w nich pojedynczych żądań lub ich wrażliwości na opóźnienia.
  3. Zmiany wrażliwe na opóźnienia mają też limit 7200 modyfikacji na godzinę. W przypadku metod wsadowych każde zagnieżdżone żądanie modyfikacji jest zliczane osobno na potrzeby tego limitu. Ten limit ma praktyczne znaczenie tylko dla użytkowników interfejsu Batch API, którzy wykonują aktualizacje wrażliwe na opóźnienia, ponieważ w innych przypadkach limit 2 zostanie wyczerpany przed tym limitem lub w tym samym czasie.

Oto kilka przykładów ilustrujących wykorzystanie limitu w przypadku różnych żądań:

  • Pojedyncze żądanie get pobrania 1 produktu zużyje 1 token z limitu 1 i 0 tokenów z limitów 2 i 3 (ponieważ dotyczą one tylko punktów końcowych modyfikacji).
  • Żądanie zbiorcze get pobrania maksymalnie 100 elementów zużyje też 1 token z limitu 1 i 0 tokenów z limitów 2 i 3.
  • Pojedyncze żądanie modification dotyczące 1 produktu zużyje 1 token limitu 1 i 1 token limitu 2. Jeśli żądanie jest wrażliwe na opóźnienia, zużyje też 1 token z limitu 3. Limit C jest taki sam jak limit 2, więc nie ma praktycznego znaczenia dla użytkowników, którzy korzystają tylko z metod pojedynczej modyfikacji.
  • Żądanie zbiorcze modification dotyczące 100 elementów odpornych na opóźnienia wykorzysta 1 token limitu 1 i 1 token limitu 2. Ta konfiguracja limitu powinna zapewniać wystarczający margines, aby katalog był aktualny, ale jeśli Twój algorytm nie uwzględnia tego limitu i przekroczy tę szybkość, możesz otrzymać błąd przy każdym dodatkowym wywołaniu.
  • Żądanie zbiorcze modification dotyczące 100 elementów wrażliwych na opóźnienia zużyje 1 token limitu 1, 1 token limitu 2 i 100 tokenów limitu 3.

Rekomendacje dotyczące korzystania z interfejsu Catalog Management API

Postępując zgodnie z tymi wytycznymi, możesz zoptymalizować interakcje z interfejsem API, co zapewni płynne i wydajne zarządzanie katalogiem.

Monitorowanie wykorzystania

Zwróć uwagę na procesy, które zużywają dużo zasobów. Na przykład na początku integracji punkty końcowe zarządzania katalogiem prawdopodobnie zużyją więcej limitu na utworzenie pełnego katalogu początkowego, co może wpłynąć na produkcyjne wykorzystanie innych punktów końcowych, takich jak interfejs API stanu zakupu, jeśli zbliżasz się do ogólnego limitu wykorzystania. Musisz monitorować wykorzystanie limitu, aby nie przekraczać limitów interfejsu API. Istnieje kilka sposobów monitorowania wykorzystania. Możesz na przykład użyć panelu limitów interfejsów Google Cloud API lub dowolnego innego wewnętrznego lub zewnętrznego narzędzia do monitorowania interfejsów API.

Optymalizacja wykorzystania limitu interfejsu API

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

  • Wybierz odpowiednią strategię zarządzania katalogiem. Gdy poznasz limit interfejsu API, musisz wybrać odpowiednią strategię dla swojej aplikacji, aby skutecznie realizować cele związane z zarządzaniem katalogiem.
  • Wykonuj tylko minimalną liczbę połączeń potrzebną do odzwierciedlenia zmian.
  • Nie wysyłaj do interfejsów API zbędnych wywołań modyfikacji. Może to wymagać prowadzenia dziennika zmian w katalogu backendu.
  • nie przekraczać limitu 7200 zapytań na godzinę dotyczącego modyfikacji produktów; Możesz chcieć utworzyć procesy synchronizacji, które wymagają wprowadzenia dużej liczby zmian w produktach w krótkim czasie (np. początkowe utworzenie katalogu). Jeśli przewidujesz, że te procesy przekroczą limit godzinowy, wdróż w razie potrzeby oczekiwanie, aby spowolnić wykorzystanie do bezpiecznego poziomu. Aby uzyskać większą przepustowość, rozważ użycie metod przetwarzania wsadowego z aktualizacjami odpornymi na opóźnienia.
  • Proaktywnie przygotuj się na skalowanie. Wraz z rozwojem aplikacji może być konieczne zwiększenie wykorzystania interfejsu API i różnych punktów końcowych. Szczegółowe informacje o tym, jak zwiększyć limit, gdy zbliżasz się do maksymalnego wykorzystania, znajdziesz w dokumentacji limitów interfejsu Google Play Developer API.
  • Strategicznie planuj procesy wymagające dużych zasobów. Spróbuj zaplanować procesy związane z dużym katalogiem w okresach największego natężenia ruchu, np. unikaj przeprowadzania pełnej synchronizacji katalogu w godzinach największej sprzedaży w ciągu tygodnia.

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

Niezależnie od tego, jak wydajnie zbudujesz logikę zarządzania katalogiem, musisz zadbać o jej odporność na nieoczekiwane limity, ponieważ dzienny limit jest wspólny dla punktów końcowych używanych w niezależnych modułach integracji. Pamiętaj, aby w obsłudze błędów uwzględnić błędy ograniczania limitu i wdrożyć odpowiednie oczekiwania. Każde wywołanie interfejsów Google Play Developer API generuje odpowiedź. W przypadku nieudanego wywołania otrzymasz odpowiedź o niepowodzeniu, która zawiera kod stanu odpowiedzi HTTP i obiekt errors z dodatkowymi szczegółami dotyczącymi domeny błędu i komunikatem debugowania. Jeśli na przykład przekroczysz dzienny limit, 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"
  } ],
}

Wdrażanie 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 w Google Play był zawsze aktualny i zawierał najnowsze informacje z katalogu backendu, ma wiele zalet, które przekładają się na większą wygodę użytkowników. Przykład:

  • Będziesz mieć dostęp do całej listy dostępnych ofert i możliwość zarządzania tagami ofert i abonamentów podstawowych, aby wpływać na własne kryteria kwalifikacji 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ć w backendzie szczegóły produktu, bez konieczności zwiększania opóźnień i ryzyka awarii przez wykonywanie dodatkowych wywołań interfejsu Google Play Developer API w trakcie krytycznych działań użytkownika.

Podczas tworzenia katalogu produktów w Google Play musisz pamiętać o pewnych ograniczeniach i kwestiach. Gdy poznasz te limity i zdecydujesz, jak chcesz uporządkować katalog, czas wybrać strategię synchronizacji.

Strategie synchronizacji katalogu

Punkty końcowe publikowania w interfejsie Google Play Developer API umożliwiają wprowadzanie aktualizacji w katalogu w miarę zachodzenia zmian. Czasami może być konieczne zastosowanie podejścia polegającego na okresowych aktualizacjach, w ramach którego wysyłasz wiele zmian w tym samym procesie. Każde z tych podejść wymaga innych decyzji projektowych. Każda strategia synchronizacji lepiej pasuje do niektórych zastosowań niż do innych. W zależności od sytuacji możesz mieć zestaw potrzeb, które wymagają obu tych strategii. Czasami możesz chcieć zaktualizować produkt od razu po wykryciu nowej zmiany, np.aby przetworzyć pilną aktualizację produktu (np. nieprawidłową cenę należy jak najszybciej poprawić). W innych przypadkach możesz użyć okresowej synchronizacji w tle, aby mieć pewność, że katalogi backendu i Google Play są zawsze spójne. Zapoznaj się z kilkoma typowymi przypadkami użycia, w których warto wdrożyć różne strategie zarządzania katalogiem.

Kiedy wysyłać aktualizacje w miarę zmian w lokalnym katalogu

Aby zminimalizować rozbieżności, aktualizacje powinny być przeprowadzane natychmiast po wprowadzeniu zmian w katalogu produktów na serwerze backendu.

Ten typ aktualizacji jest dobrym rozwiązaniem, gdy:

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

To podejście jest prostsze we wdrożeniu i pozwala zachować synchronizację katalogu z najmniejszym przedziałem rozbieżności.

Kiedy używać okresowych aktualizacji

Okresowe aktualizacje są przeprowadzane asynchronicznie w stosunku do wersji produktu na Twoim backendzie i są dobrym rozwiązaniem, gdy:

  • Nie musisz dbać o to, aby Twoje produkty były aktualizowane w krótkim czasie.
  • Musisz zaplanować aktualizacje zbiorcze lub procesy uzgadniania.
  • masz już system zarządzania treścią lub katalogiem, który obsługuje Twoje produkty cyfrowe i stale aktualizuje 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 duży katalog do przesłania do Google Play, możesz zautomatyzować początkowe przesyłanie. Ten typ złożonego procesu działa najlepiej, jeśli stosuje się strategię okresową w połączeniu z metodami wsadowymi odpornymi na opóźnienia.

Tworzenie produktów kupowanych raz

Do początkowego jednorazowego tworzenia katalogu produktów zalecamy użycie metody monetization.onetimeproducts.batchUpdate lub metody inapp_products.insert z polem allowMissing ustawionym na true i polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Pozwoli to zminimalizować czas tworzenia katalogu w ramach limitów.

Tworzenie produktów subskrypcyjnych

Do początkowego tworzenia dużego katalogu subskrypcji zalecamy użycie metody monetization.subscriptions.batchUpdate z polem allowMissing ustawionym na true i polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Pozwoli to skrócić czas tworzenia katalogu w ramach limitów przydziału.

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

Wszystkie wcześniejsze metody tworzą subskrypcje wraz z abonamentami podstawowymi (dostarczanymi 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

Poniższe metody umożliwiają efektywne modyfikowanie istniejących produktów, dzięki czemu Twoja oferta będzie zgodna z najnowszymi zmianami.

Aktualizowanie produktów kupowanych raz

Aby zaktualizować dotychczasowe produkty kupowane raz, możesz skorzystać z tych metod.

  • monetization.onetimeproducts.batchUpdate
  • inappproducts.patch : punkt końcowy PATCH służy do częściowej aktualizacji zasobu. Oznacza to, że możesz aktualizować określone pola, które wskażesz w treści żą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 wysłać cały obiekt zasobu. Punkt końcowy aktualizacji jest zwykle używany, gdy trzeba zaktualizować wszystkie pola w zasobie. Gdy parametr allowMissing ma wartość true, a podany identyfikator produktu jeszcze nie istnieje, punkt końcowy wstawia produkt zamiast zwracać błąd.
  • inappproducts.batchUpdate : to wersja zbiorcza punktu końcowego aktualizacji, która umożliwia modyfikowanie wielu produktów za pomocą jednego zapytania. Używaj go razem z polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT, aby uzyskać większą przepustowość.

Aktualizowanie produktów subskrypcyjnych

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

Jeśli na przykład chcesz zaktualizować tylko informacje o produkcie subskrypcyjnym, ustawisz pole listings na parametr updateMask.

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

Aby aktywować, dezaktywować lub usuwać abonamenty podstawowe albo przenosić subskrybentów na najnowsze wersje cenowe abonamentów podstawowych, 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 zdecydujesz się aktualizować katalog Google Play za każdym razem, gdy zmieni się katalog backendu, czy okresowo, jeśli masz system zarządzania katalogiem lub bazę danych poza katalogiem Google Play, mogą wystąpić sytuacje, w których katalog ten przestanie być zsynchronizowany z katalogiem w konfiguracji aplikacji w Google Play. Może to być spowodowane awaryjnymi ręcznymi zmianami w katalogu w Konsoli, awarią systemu zarządzania katalogiem lub utratą najnowszych danych.

Możesz utworzyć proces uzgadniania katalogu, aby uniknąć długotrwałej rozbieżności.

Rozważania dotyczące systemu różnic

Zalecamy utworzenie systemu różnicowego, który będzie wykrywać niespójności i uzgadniać dane w obu systemach. Oto kilka kwestii, które warto wziąć pod uwagę podczas tworzenia systemu różnicowego, który pomoże utrzymać synchronizację katalogów:

  • Poznaj modele danych: pierwszym krokiem jest poznanie modeli danych systemu CMS dewelopera i interfejsu Google Play Developer API. Obejmuje to znajomość różnych typów danych przechowywanych w poszczególnych systemach oraz sposobu, w jaki różne elementy danych są ze sobą powiązane.
  • Określ reguły różnic: po zapoznaniu się z modelami danych musisz określić reguły różnic. Te reguły określają sposób porównywania danych w obu systemach. Możesz na przykład dopasować identyfikatory produktów i porównać kluczowe atrybuty subskrypcji oraz powiązanych z nią planów podstawowych i ofert.
  • Wdróż algorytm różnicowy: po zdefiniowaniu reguł różnicowych musisz wdrożyć algorytm różnicowy. 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 monetization.onetimeproducts.list, monetization.onetimeproducts.batchGet, inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list i monetization.subscriptions.batchGet.
  • Generowanie raportów różnicowych: algorytm różnicowy wygeneruje raport różnicowy. Raport będzie zawierać różnice między obydwoma systemami.
  • Uzgodnij różnice: po wygenerowaniu raportu różnic musisz rozwiązać różnice. Może to obejmować aktualizację danych w systemie CMS lub aktualizację danych po stronie Google Play za pomocą punktów końcowych interfejsu Developer API do zarządzania katalogiem, w zależności od tego, jak zwykle aktualizujesz katalog. Aby uzgodnić produkty, które nie są zsynchronizowane, użyj punktów końcowych aktualizacji zgodnie z opisem w sekcji Aktualizacje produktów.

Wycofanie usługi

Interfejs Google Play Developer API udostępnia te metody, które pomagają wycofać produkty:

W przypadku produktów kupowanych raz:

W przypadku produktów objętych subskrypcją:

Wycofanie produktu może być konieczne w różnych sytuacjach, np.:

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

Zalecamy uwzględnienie wycofania produktu w strategii zarządzania katalogiem.