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 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 utrzymaniu aktualności katalogu i skalowaniu go do dużych rozmiarów, gdy ręczna koordynacja jest niepraktyczna. Z tego przewodnika dowiesz się, jak używać interfejsu Play Developer API do tworzenia katalogu produktów i zarządzania nim w aplikacji w Google Play. Zapoznaj się z przewodnikiem Przygotowanie, aby dowiedzieć się, jak skonfigurować interfejs Google Play Developer API na potrzeby integracji backendu.

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

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 dotyczących 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 sekcji 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, będziesz modelować produkty konsumpcyjne (można je kupić dowolną liczbę razy) lub stałe uprawnienia (nie mogą być kupione dwukrotnie 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 objętymi subskrypcją 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 końcowe monetization.subscriptions.basePlans i monetization.subscriptions.basePlans.offers, które służą do zarządzania odpowiednio abonamentami podstawowymi i ofertami.

Metody zbiorcze

Punkty końcowe onetimeproducts, inappproducts i monetization.subscriptions udostępniają szereg metod zbiorczych, które umożliwiają pobieranie maksymalnie 100 elementów w ramach tej samej aplikacji lub zarządzanie nimi jednocześnie.

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 z dużymi katalogami do początkowego tworzenia katalogu lub uzgadniania katalogu.

Czas oczekiwania na wprowadzenie aktualizacji a przepustowość

Po zakończeniu żądania utworzenia lub modyfikacji produktu zmiany mogą nie być od razu widoczne dla użytkowników na ich urządzeniach z powodu opóźnień w sieci lub przetwarzaniu backendu. Domyślnie wszystkie prośby o modyfikację usługi są wrażliwe na opóźnienia. Oznacza to, że są one zoptymalizowane pod kątem szybkiego rozpowszechniania w systemach backendowych i zwykle są odzwierciedlane na urządzeniach użytkowników w ciągu kilku minut. Istnieje jednak godzinowy limit liczby takich żądań modyfikacji. W przypadkach, gdy musisz utworzyć lub zaktualizować wiele produktów (np. podczas tworzenia dużego katalogu), możesz użyć metod zbiorczych z polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Znacznie zwiększy to przepustowość aktualizacji. Aktualizacje, które nie wymagają natychmiastowego zastosowania, zostaną rozpowszechnione na urządzeniach użytkowników w ciągu 24 godzin.

Konfiguracja limitu

Gdy używasz 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 nazywane zasobnikami, z których każdy ma własny limit minutowy. Więcej informacji znajdziesz w artykule na temat limitów.
  2. Punkty końcowe modyfikacji produktów również mają limit 7200 zapytań na godzinę. Jest to jeden limit dotyczący zarówno produktów kupowanych raz, jak i subskrypcji, oraz wszystkich próśb o modyfikację, w tym utworzenia, aktualizacji, aktywacji i usunięcia. Wywołania metody modyfikacji zbiorczej są liczone jako jedno zapytanie w ramach tego limitu, niezależnie od liczby uwzględnionych żądań indywidualnych i ich wrażliwości na opóźnienia.
  3. Modyfikacje wrażliwe na opóźnienia mają też limit 7200 modyfikacji na godzinę. W przypadku metod zbiorczych każde zagnieżdżone żądanie modyfikacji jest liczone osobno na potrzeby tego limitu. Ten limit ma praktyczne znaczenie tylko dla użytkowników interfejsu API do zbiorczego przesyłania danych, 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 przez różne żądania:

  • Pojedyncze żądanie get pobrania jednego elementu zużyje 1 token z limitu 1 i żadnych tokenów z limitów 2 i 3 (ponieważ dotyczą one tylko punktów końcowych modyfikacji).
  • Żądanie zbiorcze get dotyczące pobrania maksymalnie 100 elementów również wykorzysta 1 token z limitu 1 i żadnych tokenów z limitów 2 i 3.
  • Pojedyncze żądanie modification dotyczące jednego elementu zużyje 1 token z limitu 1 i 1 token z limitu 2. Jeśli żądanie jest wrażliwe na czas oczekiwania, wykorzysta też 1 token z limitu 3. Ponieważ limit C ma taki sam limit jak limit 2, nie ma on praktycznego znaczenia dla użytkowników, którzy korzystają tylko z metod pojedynczej modyfikacji.
  • Żądanie zbiorcze modification dotyczące 100 elementów tolerujących opóźnienia wykorzysta 1 token z limitu 1 i 1 token z limitu 2. Taka konfiguracja limitu powinna zapewnić wystarczający margines na aktualizowanie katalogu, ale jeśli algorytm nie uwzględnia tego limitu i przekracza tę częstotliwość, możesz otrzymać błąd przy każdym dodatkowym wywołaniu.
  • Żądanie zbiorcze modification dotyczące 100 elementów wrażliwych na opóźnienia wykorzysta 1 token z limitu 1, 1 token z limitu 2 i 100 tokenów z limitu 3.

Zalecenia dotyczące korzystania z interfejsu Catalog Management API

Przestrzegając tych wytycznych, zoptymalizujesz interakcje z interfejsem API, co zapewni płynne i efektywne zarządzanie katalogiem.

Monitorowanie wykorzystania

Należy pamiętać o procesach, które intensywnie korzystają z zasobów. Na przykład na początku integracji punkty końcowe zarządzania katalogiem mogą zużywać więcej limitu na utworzenie 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żasz się do ogólnego limitu wykorzystania. Musisz monitorować wykorzystanie limitów, 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 Google Cloud API lub dowolnego innego wewnętrznego lub zewnętrznego narzędzia do monitorowania interfejsów API.

Optymalizacja wykorzystania limitu interfejsu API

Zdecydowanie zalecamy optymalizację wykorzystania limitów, 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ż zrozumiesz, jak działa limit interfejsu API, musisz wybrać odpowiednią strategię dla swojej aplikacji, aby skutecznie osiągać cele związane z zarządzaniem katalogiem.
  • Wykonuj tylko minimalną liczbę wywołań potrzebną do odzwierciedlenia zmian.
  • Nie wysyłaj do interfejsów API zbędnych ani niepotrzebnych wywołań modyfikacji. Może to wymagać prowadzenia dziennika zmian w katalogu backendu.
  • Nie przekraczaj godzinowego limitu 7200 zapytań dotyczących modyfikacji produktów. Możesz utworzyć procesy synchronizacji, które wymagają wprowadzenia dużej liczby zmian w produktach w krótkim czasie (np. początkowe utworzenie katalogu). Jeśli spodziewasz się, że te procesy przekroczą limit godzinowy, wprowadź odpowiednie okresy oczekiwania, aby ograniczyć wykorzystanie do bezpiecznego poziomu. Aby uzyskać większą przepustowość, rozważ użycie metod zbiorczych z aktualizacjami tolerującymi opóźnienia.
  • Przygotuj się na skalowanie. W miarę rozwoju 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 dotyczącej limitów interfejsu Google Play Developer API.
  • Strategicznie planuj obciążające procesy. Staraj się planować procesy związane z dużym katalogiem w okresach szczytowego wykorzystania. Możesz na przykład unikać przeprowadzania pełnej synchronizacji katalogu w godzinach szczytu sprzedaży w tygodniu.

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

Niezależnie od tego, jak wydajnie zbudujesz logikę zarządzania katalogiem, powinna ona być odporna na nieoczekiwane limity, 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 ograniczania limitów w obsłudze błędów i zaimplementować odpowiednie czasy 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, który zawiera dalsze szczegóły dotyczące domeny błędu i komunikat 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"
  } ],
}

Implementacja 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ł najnowsze informacje z katalogu backendu, przynosi korzyści w postaci lepszych wrażeń 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 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ć pod ręką szczegóły produktu w backendzie, bez konieczności zwiększania opóźnienia i ryzyka niepowodzenia przez wykonywanie dodatkowych wywołań 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 kwestiach. Gdy już poznasz te limity i będziesz wiedzieć, jak chcesz ustrukturyzować katalog, możesz zdecydować o strategii synchronizacji.

Strategie synchronizacji katalogu

Punkty końcowe publikowania w interfejsie Google Play Developer API umożliwiają aktualizowanie katalogu na bieżąco. Czasami może być konieczne zastosowanie podejścia polegającego na okresowych aktualizacjach, w ramach którego wysyłasz serię zmian w tym samym procesie. Każde podejście wymaga innych decyzji projektowych. Każda strategia synchronizacji będzie lepiej pasować do niektórych przypadków użycia niż do innych. W zależności od sytuacji możesz mieć zestaw potrzeb, które wymagają obu strategii.

Czasami możesz chcieć zaktualizować produkt, gdy tylko dowiesz się o nowej zmianie, na przykład w celu przetworzenia pilnej aktualizacji produktu (np. gdy trzeba jak najszybciej poprawić błędną cenę). W innych przypadkach możesz użyć okresowej synchronizacji w tle, aby zapewnić spójność katalogów backendu i Google Play. Przeczytaj o typowych przypadkach użycia, w których możesz wdrożyć te różne strategie zarządzania katalogiem.

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

Aby zminimalizować rozbieżności, aktualizacje powinny być wprowadzane natychmiast po wprowadzeniu jakichkolwiek zmian w katalogu produktów w backendzie.

Ten typ aktualizacji jest dobrym rozwiązaniem, gdy:

  • Musisz zadbać o to, aby produkty były zawsze aktualne.
  • Musisz codziennie wprowadzać kilka zmian w produktach.
  • 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 przy najmniejszej rozbieżności.

Kiedy używać aktualizacji okresowych

Aktualizacje okresowe są uruchamiane asynchronicznie w stosunku do wersji usługi w 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 do obsługi produktów cyfrowych, który stale aktualizuje katalog.

W przypadku dużych katalogów rozważ użycie metod wsadowych z aktualizacjami tolerującymi 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 wymagającego procesu działa najlepiej, gdy stosowana jest strategia okresowa połączona z metodami wsadowymi tolerującymi opóźnienia.

Tworzenie produktów kupowanych raz

Do początkowego, jednorazowego utworzenia katalogu produktów kupowanych raz zalecamy użycie metody monetization.onetimeproducts.batchUpdate lub inapp_products.insert z polem allowMissing ustawionym na true i polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Dzięki temu skrócisz czas potrzebny na utworzenie katalogu w ramach limitów.

Tworzenie produktów objętych subskrypcją

Do utworzenia dużego katalogu początkowych 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.

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 (podanymi 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 usługi

Te metody umożliwiają skuteczne modyfikowanie dotychczasowych produktów, dzięki czemu 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ć konkretne pola określone 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 jest ustawiony na true, a podany identyfikator produktu jeszcze nie istnieje, punkt końcowy wstawi produkt, zamiast zgłosić błąd.
  • inappproducts.batchUpdate: to jest wersja wsadowa 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 objętych subskrypcją

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 objętym subskrypcją, w parametrze updateMask podaj pole listings.

Możesz użyć metody monetization.subscriptions.batchUpdate, aby zaktualizować wiele subskrypcji jednocześnie. Używaj go razem z polem latencyTolerance ustawionym na PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT, aby uzyskać większą przepustowość.

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

Możesz też 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 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 nie będzie zsynchronizowany z katalogiem w konfiguracji aplikacji w Google Play. Może to być spowodowane awaryjnymi ręcznymi zmianami katalogu w konsoli, przerwą w działaniu systemu zarządzania katalogiem lub utratą najnowszych danych.

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

Uwzględnienie systemu różnic

Zalecamy utworzenie systemu porównywania, który będzie wykrywać niespójności i uzgadniać dane między tymi 2 systemami. Oto kilka kwestii, które warto wziąć pod uwagę podczas tworzenia systemu różnicowego, który pomoże Ci synchronizować katalogi:

  • Zrozumienie modeli danych: pierwszym krokiem jest zrozumienie modeli danych systemu CMS dewelopera i interfejsu Google Play Developer API. Obejmuje to znajomość różnych typów danych przechowywanych w każdym systemie oraz sposobu, w jaki różne elementy danych są ze sobą powiązane.
  • Zdefiniuj reguły różnic: gdy zrozumiesz 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 dopasować identyfikatory produktów i porównać kluczowe atrybuty subskrypcji oraz powiązanych z nią abonamentów podstawowych i ofert.
  • Wdrażanie algorytmu różnicowego: po zdefiniowaniu reguł różnicowych musisz wdrożyć algorytm różnicowy. 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 o różnicach: algorytm różnicowy wygeneruje raport o różnicach. Ten raport pokazuje różnice między tymi systemami.
  • Uzgodnij różnice: po wygenerowaniu raportu o różnicach musisz je uzgodnić. Może to wymagać zaktualizowania danych w systemie CMS lub po stronie Google Play za pomocą punktów końcowych zarządzania katalogiem w interfejsie Developer API, w zależności od tego, jak zwykle aktualizujesz katalog. Aby zsynchronizować produkty, 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ą w wycofywaniu produktów:

W przypadku produktów kupowanych raz:

W przypadku produktów objętych subskrypcją:

Wycofanie usługi może być konieczne w różnych sytuacjach, takich jak:

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

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