Gestire il catalogo dei prodotti

Questa guida spiega come utilizzare l'API Google Play Developer per creare e gestire un catalogo prodotti per la tua app Google Play.

Per vendere prodotti nella tua app tramite il sistema di fatturazione di Google Play, devi configurare un catalogo con tutti i prodotti che vuoi rendere disponibili per l'acquisto da parte dei tuoi utenti. Puoi farlo tramite Play Console oppure puoi automatizzare la gestione del catalogo utilizzando l'API Google Play Developer. L'automazione può aiutarti a garantire che il tuo catalogo sia sempre aggiornato e a scalare i cataloghi di grandi dimensioni in cui il coordinamento manuale è impraticabile. In questa guida vedrai come utilizzare l'API Play Developer per creare e gestire un catalogo prodotti per la tua app Google Play. Consulta la nostra guida Preparazione per istruzioni su come configurare l'API Google Play Developer per l'integrazione del backend.

API Catalog Management

Per informazioni sui diversi tipi di prodotti che puoi vendere con il sistema di fatturazione di Google Play, consulta Informazioni sui tipi di prodotti in-app e considerazioni relative al catalogo. Google offre due set principali di API per la gestione del catalogo su Play, corrispondenti alle due categorie principali di prodotti:

  • Prodotti a pagamento singolo
  • Prodotti in abbonamento

Prodotti a pagamento singolo

I prodotti a pagamento singolo (precedentemente denominati prodotti in-app) utilizzano il modello degli oggetti prodotto a pagamento singolo che ti consente di configurare più opzioni di acquisto e offerte per i tuoi prodotti a pagamento singolo. Il modello degli oggetti dei prodotti a pagamento singolo ti offre maggiore flessibilità nella vendita dei prodotti e ne riduce la complessità di gestione. Verrà eseguita la migrazione dei tuoi prodotti in-app esistenti al modello degli oggetti prodotto a pagamento singolo. Per maggiori informazioni, consulta la sezione Migrazione dei prodotti in-app.

Gli endpoint monetization.onetimeproducts e inappproducts ti consentono di gestire i prodotti a pagamento singolo dal backend. Ciò include la creazione, l'aggiornamento e l'eliminazione dei prodotti, nonché la gestione di prezzi e disponibilità. A seconda di come gestisci gli acquisti di prodotti a pagamento singolo, modellerai i prodotti di consumo (possono essere acquistati tutte le volte che si desidera) o i diritti permanenti (non possono essere acquistati due volte dallo stesso utente). Puoi decidere quali prodotti a pagamento singolo devono essere di consumo o meno.

Prodotti in abbonamento

L'endpoint monetization.subscriptions ti aiuta a gestire i prodotti in abbonamento dal backend dello sviluppatore. Puoi creare, aggiornare ed eliminare abbonamenti o controllare la loro disponibilità e i prezzi a livello regionale. Oltre all'endpoint monetization.subscriptions, forniamo anche monetization.subscriptions.basePlans e monetization.subscriptions.basePlans.offers per gestire rispettivamente i piani base e le offerte degli abbonamenti.

Metodi batch

Gli endpoint onetimeproducts, inappproducts e monetization.subscriptions forniscono una serie di metodi batch che consentono di recuperare o gestire fino a 100 entità nella stessa app contemporaneamente.

I metodi batch, se utilizzati con la tolleranza alla latenza attivata, supportano una velocità effettiva superiore e sono particolarmente utili per gli sviluppatori di cataloghi di grandi dimensioni per la creazione iniziale del catalogo o la riconciliazione del catalogo.

Latenza di propagazione dell'aggiornamento rispetto alla velocità effettiva

Una volta completata una richiesta di creazione o modifica di un prodotto, le modifiche potrebbero non essere visibili immediatamente agli utenti finali sui loro dispositivi a causa di ritardi di elaborazione di rete o di backend. Per impostazione predefinita, tutte le richieste di modifica dei prodotti sono sensibili alla latenza. Ciò significa che sono ottimizzati per una rapida propagazione attraverso i sistemi di backend, in genere riflettendosi sui dispositivi degli utenti finali in pochi minuti. Tuttavia, esiste un limite orario al numero di richieste di modifica. Per i casi in cui devi creare o aggiornare molti prodotti (ad esempio durante la creazione iniziale di un catalogo di grandi dimensioni), puoi utilizzare i metodi batch con il campo latencyTolerance impostato su PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Ciò aumenterà in modo significativo la velocità effettiva degli aggiornamenti. L'applicazione degli aggiornamenti tolleranti alla latenza sui dispositivi degli utenti finali può richiedere fino a 24 ore.

Configurazione delle quote

Esistono diversi limiti di quota di cui devi essere a conoscenza quando utilizzi l'API Play Developer per gestire il catalogo prodotti:

  1. Le API Google Play Developer sono organizzate in categorie chiamate bucket, dove ogni bucket ha il proprio limite di quota al minuto. Per saperne di più, consulta Quote.
  2. Anche gli endpoint di modifica del prodotto applicano un limite di 7200 query all'ora. Si tratta di un limite unico per i prodotti una tantum e gli abbonamenti e per tutte le richieste di modifica, inclusi creazione, aggiornamento, attivazione, eliminazione. Le chiamate al metodo di modifica batch vengono conteggiate come una query per questa quota, indipendentemente dal numero di richieste individuali incluse o dalla sensibilità alla latenza.
  3. Le modifiche sensibili alla latenza hanno anche un limite di 7200 modifiche all'ora. Per i metodi batch, ogni richiesta di modifica nidificata viene conteggiata separatamente ai fini di questa quota. Questa quota ha implicazioni pratiche solo per gli utenti dell'API batch che eseguono aggiornamenti sensibili alla latenza, poiché negli altri casi la quota 2 verrà esaurita prima o contemporaneamente a questa quota.

Ecco alcuni esempi illustrativi per comprendere l'utilizzo della quota di diverse richieste:

  • Una singola richiesta get per recuperare un elemento consumerà 1 token della quota 1 e nessun token delle quote 2 e 3 (in quanto riguardano solo gli endpoint di modifica).
  • Una richiesta batch get per recuperare fino a 100 elementi consumerà anche 1 token della quota 1 e nessun token delle quote 2 e 3.
  • Una singola richiesta modification per un elemento consumerà 1 token di quota 1 e 1 token di quota 2. Se la richiesta è sensibile alla latenza, consumerà anche 1 token della quota 3. Poiché la quota C ha lo stesso limite della quota 2, non ha implicazioni pratiche per gli utenti che utilizzano solo metodi di modifica singoli.
  • Una richiesta batch modification per 100 elementi tolleranti alla latenza consumerà 1 token di quota 1 e 1 token di quota 2. Questa configurazione della quota dovrebbe consentire un ampio margine per mantenere aggiornato il catalogo, ma se il tuo algoritmo non è consapevole di questa quota e supera questa velocità, potresti ricevere un errore per ogni chiamata aggiuntiva.
  • Una richiesta batch modification per 100 elementi sensibili alla latenza consumerà 1 token di quota 1, 1 token di quota 2 e 100 token di quota 3.

Consigli per l'utilizzo dell'API Catalog Management

Se rispetti queste linee guida, ottimizzi le tue interazioni con l'API, garantendo un'esperienza di gestione del catalogo fluida ed efficiente.

Monitorare l'utilizzo

Devi essere a conoscenza dei processi di utilizzo intensivo. Ad esempio, all'inizio dell'integrazione è più probabile che gli endpoint di gestione del catalogo consumino più quota per creare il catalogo iniziale completo e ciò potrebbe potenzialmente influire sull'utilizzo in produzione di altri endpoint come l'API per lo stato dell'acquisto se ti avvicini al limite di utilizzo complessivo. Devi monitorare il consumo della quota per assicurarti di non superare le quote API. Esistono diversi modi per monitorare l'utilizzo. Ad esempio, puoi utilizzare la dashboard delle quote delle API Google Cloud o qualsiasi altro strumento di monitoraggio delle API interno o di terze parti di tua scelta.

Ottimizzare l'utilizzo della quota API

L'ottimizzazione del consumo di limiti di frequenza è vivamente consigliata per ridurre al minimo la probabilità di errori API. Per implementare questa strategia in modo efficace, ti consigliamo di:

  • Scegli la strategia di gestione del catalogo giusta. Una volta compresa la quota API, devi scegliere la strategia giusta per la tua applicazione per raggiungere in modo efficiente i tuoi obiettivi di gestione del catalogo.
  • Effettua solo il numero minimo di chiamate necessario per riflettere le modifiche.
  • Non inviare chiamate di modifica ridondanti o non necessarie alle API. Ciò potrebbe richiedere di mantenere un log delle modifiche nel catalogo di backend.
  • Rimani al di sotto del limite orario di 7200 query per la modifica dei prodotti. Potresti voler creare processi di sincronizzazione che richiedono di apportare un numero elevato di modifiche ai prodotti in un breve periodo di tempo (ad esempio, la creazione iniziale del catalogo). Se prevedi che questi processi superino il limite orario, implementa le attese necessarie per rallentare l'utilizzo a un livello sicuro. Prendi in considerazione l'utilizzo di metodi batch con aggiornamenti tolleranti alla latenza per ottenere un throughput più elevato.
  • Preparati in modo proattivo per la scalabilità. Man mano che la tua applicazione cresce, potresti dover aumentare l'utilizzo dell'API e dei vari endpoint. Leggi la documentazione sulle quote dell'API Google Play Developer per informazioni dettagliate su come aumentare la quota quando ti avvicini all'utilizzo massimo.
  • Pianifica in modo strategico i processi pesanti. Cerca di programmare i processi del catalogo pesanti in base ai picchi di utilizzo critici. Ad esempio, puoi evitare di eseguire una sincronizzazione completa del catalogo durante gli orari di picco delle vendite della settimana.

Aggiungere la logica di gestione degli errori di quota

Indipendentemente dall'efficienza con cui crei la logica di gestione del catalogo, devi renderla resiliente a limiti di quota imprevisti, dato che la quota giornaliera è condivisa dagli endpoint utilizzati in moduli indipendenti dell'integrazione. Assicurati di includere gli errori di limitazione della quota nella gestione degli errori e di implementare le attese appropriate. Ogni chiamata effettuata alle API Google Play Developer genererà una risposta. In caso di errore della chiamata, riceverai una risposta di errore che include un codice di stato della risposta HTTP e un oggetto errors, che fornisce ulteriori dettagli sul dominio di errore e un messaggio di debug. Ad esempio, se superi il limite giornaliero, potresti riscontrare un errore simile al seguente:

{
  "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"
  } ],
}

Implementazione della gestione del catalogo

Gli sviluppatori utilizzano gli endpoint di pubblicazione dei prodotti dell'API Google Play Developer per mantenere sincronizzato il catalogo tra il backend e Google Play. Assicurarsi che il catalogo di Google Play sia sempre aggiornato con le informazioni più recenti del catalogo del backend offre vantaggi per creare un'esperienza utente migliore. Per esempio:

  • Potrai consultare l'intero elenco delle offerte disponibili e gestire i tag delle offerte e dei piani base per influire sulla tua idoneità e sulla logica di visualizzazione delle offerte.
  • Puoi controllare i diversi prezzi e i dettagli dei prodotti visualizzati dagli utenti sulle varie piattaforme e assicurarti che siano coerenti.
  • Avrai a portata di mano i dettagli del prodotto nel backend durante l'elaborazione di nuovi acquisti, senza la necessità di aumentare la latenza e il rischio di errori effettuando chiamate aggiuntive all'API Google Play Developer durante i flussi critici degli utenti.

Esistono determinati limiti e considerazioni da tenere a mente quando crei il catalogo prodotti su Google Play. Una volta compresi questi limiti e definita la struttura del catalogo, è il momento di decidere la strategia di sincronizzazione.

Strategie di sincronizzazione del catalogo

Gli endpoint di pubblicazione dell'API Google Play Developer ti consentono di apportare aggiornamenti al tuo catalogo man mano che si verificano modifiche. A volte, potrebbe essere necessario adottare un approccio di aggiornamenti periodici, in cui invii una serie di modifiche nella stessa procedura. Ogni approccio richiede scelte di progettazione diverse. Ogni strategia di sincronizzazione si adatta meglio ad alcuni casi d'uso rispetto ad altri e potresti avere una serie di esigenze che richiedono entrambe le strategie, a seconda della situazione. A volte potresti voler apportare un aggiornamento a un prodotto nel momento in cui vieni a conoscenza di una nuova modifica, ad esempio per elaborare un aggiornamento urgente del prodotto (ovvero un prezzo errato deve essere corretto il prima possibile). Altre volte puoi utilizzare una sincronizzazione periodica in background per assicurarti che i cataloghi di backend e Play siano sempre coerenti. Leggi alcuni casi d'uso comuni in cui potresti voler implementare queste diverse strategie di gestione del catalogo.

Quando inviare gli aggiornamenti man mano che il catalogo locale cambia

Idealmente, gli aggiornamenti devono essere eseguiti non appena viene apportata una modifica al catalogo dei prodotti del backend, per ridurre al minimo le discrepanze.

Questo tipo di aggiornamenti è una buona opzione quando:

  • Devi assicurarti che i tuoi prodotti siano sempre aggiornati.
  • Devi apportare alcune modifiche ai tuoi prodotti ogni giorno.
  • Devi aggiornare i prodotti già in produzione e in vendita.

Questo approccio è più semplice da implementare e ti consente di mantenere sincronizzato il catalogo con la finestra di discrepanza minima.

Quando utilizzare gli aggiornamenti periodici

Gli aggiornamenti periodici vengono eseguiti in modo asincrono rispetto all'edizione del prodotto nel backend e sono una buona opzione quando:

  • Non devi assicurarti che i tuoi prodotti vengano aggiornati con breve preavviso.
  • Devi pianificare aggiornamenti collettivi o procedure di riconciliazione.
  • Hai già un sistema di gestione dei contenuti o del catalogo per gestire i tuoi prodotti digitali e che aggiorna costantemente il catalogo

In caso di cataloghi di grandi dimensioni, valuta la possibilità di utilizzare metodi batch con aggiornamenti tolleranti alla latenza per ottenere il massimo rendimento.

Creare il catalogo dei prodotti

Se hai un catalogo di grandi dimensioni da caricare su Google Play, potresti voler automatizzare il caricamento iniziale. Questo tipo di processo pesante funziona meglio se viene seguita una strategia periodica combinata con metodi batch tolleranti alla latenza.

Creare prodotti a pagamento singolo

Per la creazione iniziale una tantum del catalogo dei prodotti, ti consigliamo di utilizzare il metodo monetization.onetimeproducts.batchUpdate o inapp_products.insert con il campo allowMissing impostato su true e il campo latencyTolerance impostato su PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. In questo modo, il tempo necessario per creare il catalogo entro i limiti di quota viene ridotto al minimo.

Creare prodotti in abbonamento

Per la creazione iniziale di un catalogo di grandi dimensioni, ti consigliamo di utilizzare il metodo monetization.subscriptions.batchUpdate con il campo allowMissing impostato su true e il campo latencyTolerance impostato su PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. In questo modo il tempo necessario per creare il catalogo entro i limiti di quota verrà ridotto al minimo.

Per i cataloghi di abbonamenti più piccoli, l'API Play Developer fornisce il metodo monetization.subscriptions.create. In alternativa, puoi creare abbonamenti utilizzando il metodo monetization.subscriptions.patch con il parametro allowMissing, come descritto nella sezione Aggiornamenti dei prodotti.

Tutti i metodi precedenti creano abbonamenti insieme ai relativi piani base (forniti all'interno dell'oggetto Abbonamento). Questi piani base sono inizialmente inattivi. Per gestire lo stato dei piani base, puoi utilizzare l'endpoint monetization.subscriptions.basePlans, inclusa l'attivazione di un piano base per renderlo disponibile per l'acquisto. Inoltre, l'endpoint monetization.subscriptions.basePlans.offers ti consente di creare e gestire le offerte.

Aggiornamenti di prodotto

I seguenti metodi ti consentono di modificare in modo efficiente i tuoi prodotti esistenti, garantendo che le tue offerte siano in linea con gli ultimi aggiustamenti.

Aggiornare i prodotti a pagamento singolo

Sono disponibili i seguenti metodi per aiutarti ad aggiornare i prodotti una tantum esistenti.

  • monetization.onetimeproducts.batchUpdate
  • inappproducts.patch : l'endpoint patch viene utilizzato per aggiornare parzialmente una risorsa. Ciò significa che puoi aggiornare campi specifici che specifichi nel corpo della richiesta. L'endpoint patch viene in genere utilizzato quando devi aggiornare solo alcuni campi di una risorsa.
  • inappproducts.update : l'endpoint di aggiornamento viene utilizzato per aggiornare una risorsa nella sua interezza. Ciò significa che dovrai inviare l'intero oggetto risorsa nel corpo della richiesta. L'endpoint di aggiornamento viene in genere utilizzato quando devi aggiornare tutti i campi di una risorsa. Quando il parametro allowMissing è impostato su true e l'ID prodotto fornito non esiste già, l'endpoint inserirà il prodotto anziché non riuscire.
  • inappproducts.batchUpdate : si tratta di una versione batch dell'endpoint di aggiornamento, che consente di modificare più prodotti con una singola query. Utilizzalo insieme al campo latencyTolerance impostato su PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT per ottenere un throughput maggiore.

Aggiornare i prodotti in abbonamento

Per aggiornare gli abbonamenti esistenti, puoi utilizzare il metodo monetization.subscriptions.patch. Questo metodo accetta i seguenti parametri obbligatori:

A meno che tu non stia creando un nuovo abbonamento utilizzando il parametro allowMissing, devi fornire il parametro updateMask. Questo parametro è un elenco separato da virgole dei campi che vuoi aggiornare.

Ad esempio, se vuoi aggiornare solo una scheda di un prodotto in abbonamento, specifica il campo listings nel parametro updateMask.

Puoi utilizzare monetization.subscriptions.batchUpdate per aggiornare più abbonamenti contemporaneamente. Utilizzalo insieme al campo latencyTolerance impostato su PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT per ottenere una velocità effettiva maggiore.

Per attivare, disattivare, eliminare i piani base o per eseguire la migrazione degli abbonati alle versioni più recenti del prezzo del piano base, utilizza l'endpoint monetization.subscriptions.basePlans.

Inoltre, puoi aggiornare le offerte dei tuoi piani base con il metodo monetization.subscriptions.basePlans.offers.patch.

Riconciliazione del catalogo

Se scegli di aggiornare il catalogo di Google Play ogni volta che il catalogo del backend cambia o periodicamente, se hai un sistema di gestione del catalogo o un database al di fuori del catalogo di Google Play, potrebbero verificarsi situazioni in cui non è sincronizzato con il catalogo nella configurazione delle app su Play. Ciò potrebbe essere dovuto a modifiche manuali di emergenza al catalogo in Console, a un'interruzione del tuo sistema di gestione del catalogo o forse alla perdita dei dati più recenti.

Puoi creare una procedura di riconciliazione del catalogo per evitare un periodo prolungato di discrepanza.

Considerazione del sistema di differenziali

Ti consigliamo di creare un sistema di differenze per rilevare le incongruenze e riconciliare i due sistemi. Ecco alcuni aspetti da considerare quando crei un sistema di differenze per mantenere sincronizzati i cataloghi:

  • Comprendere i modelli di dati:il primo passaggio consiste nel comprendere i modelli di dati del CMS per sviluppatori e dell'API Google Play Developer. Ciò include la conoscenza dei diversi tipi di dati archiviati in ogni sistema e il modo in cui i diversi elementi di dati vengono mappati tra loro.
  • Definisci le regole di differenziazione: dopo aver compreso i modelli di dati, devi definire le regole di differenziazione. Queste regole determineranno il modo in cui i dati nei due sistemi vengono confrontati. Ad esempio, potresti voler abbinare gli ID prodotto e confrontare gli attributi chiave dell'abbonamento e dei piani base e delle offerte associati.
  • Implementa un algoritmo diff: dopo aver definito le regole diff, devi implementare l'algoritmo diff. Questo algoritmo prenderà i dati dei due sistemi e li confronterà in base alle regole che hai definito. Per ottenere i dati del catalogo da Google Play, puoi utilizzare i metodi monetization.onetimeproducts.list, monetization.onetimeproducts.batchGet, inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list e monetization.subscriptions.batchGet.
  • Genera report sulle differenze:l'algoritmo di differenze genererà un report sulle differenze. Questo report mostrerà le differenze tra i due sistemi.
  • Riconcilia le differenze:dopo aver generato il report sulle differenze, devi risolverle. A seconda di come aggiorni normalmente il catalogo, potrebbe essere necessario aggiornare i dati nel CMS oppure aggiornare i dati lato Google Play utilizzando gli endpoint di gestione del catalogo dell'API Developer. Per riconciliare i prodotti non sincronizzati, utilizza gli endpoint di aggiornamento come descritto nella sezione Aggiornamenti dei prodotti.

Ritiro del prodotto

L'API Google Play Developer fornisce i seguenti metodi per aiutarti a ritirare i tuoi prodotti:

Per i prodotti a pagamento singolo:

Per i prodotti in abbonamento:

Il ritiro di un prodotto potrebbe essere necessario in vari scenari, ad esempio:

  • Creazione per errore.
  • Interruzione di una funzionalità o di un servizio.

Ti consigliamo di integrare il ritiro dei prodotti nella tua strategia di gestione del catalogo.