Gestire il catalogo dei prodotti

Questa guida spiega come utilizzare l'API Google Play Developer per creare e gestire un catalogo di 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 degli utenti. Questa operazione può essere eseguita tramite Play Console oppure automatizzando la gestione del catalogo utilizzando l'API Google Play Developer. L'automazione può aiutare a garantire che il tuo catalogo sia sempre aggiornato e scalare a cataloghi di grandi dimensioni dove il coordinamento manuale non è pratico. In questa guida scoprirai come utilizzare l'API Play Developer per creare e gestire un catalogo di prodotti per la tua app Google Play. Leggi la nostra Guida introduttiva per le istruzioni su come configurare l'API Google Play Developer per l'integrazione del backend.

API di gestione del catalogo

Per informazioni sui diversi tipi di prodotti che puoi vendere con il sistema di fatturazione di Google Play, leggi Comprendere i tipi di prodotti in-app e le considerazioni sul catalogo. Google offre due set principali di API per la gestione del catalogo su Play, corrispondenti alle due categorie di prodotto principali:

• Prodotti a pagamento singolo
• Prodotti in abbonamento

Prodotti a pagamento singolo

L'endpoint inappproducts ti consente di gestire i prodotti a pagamento singolo dal tuo backend. Ciò include la creazione, l'aggiornamento e l'eliminazione dei prodotti e la gestione di prezzi e disponibilità. A seconda di come gestisci gli acquisti una tantum di prodotti, puoi modellare i prodotti di consumo (che possono essere acquistati tutte le volte che vuoi) o i diritti permanenti (non possono essere concessi due volte dallo stesso utente). Puoi decidere quali prodotti a pagamento singolo devono essere consumabili o meno.

Prodotti in abbonamento

L'endpoint monetization.subscriptions ti aiuta a gestire i prodotti in abbonamento dal backend del tuo sviluppatore. Ad esempio, puoi creare, aggiornare ed eliminare abbonamenti o controllare la 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 inappproducts e monetization.subscriptions forniscono diversi metodi batch che consentono di recuperare o gestire contemporaneamente fino a 100 entità nella stessa app.

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

Aggiorna latenza di propagazione e velocità effettiva

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

Configurazione della quota

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

1. Le API Google Play Developer hanno un limite predefinito di 200.000 query al giorno. Questo limite quota si applica all'aggregazione dell'utilizzo in tutti gli endpoint, incluse le API di gestione del catalogo.
2. Gli endpoint di modifica dei prodotti prevedono inoltre un limite di 7200 query all'ora. Si tratta di un singolo limite sia per i prodotti a pagamento singolo che per gli abbonamenti e per tutte le richieste di modifica, incluse creazione, aggiornamento, attivazione e eliminazione. Le chiamate al metodo di modifica in batch vengono conteggiate come una query per questa quota, indipendentemente dal numero di singole richieste incluse o dalla loro sensibilità di latenza.
3. Anche le modifiche sensibili alla latenza hanno 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 di API batch che eseguono aggiornamenti sensibili alla latenza, poiché in altri casi la quota 2 verrà esaurita prima o contemporaneamente a questa quota.

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

• Una singola richiesta get per recuperare un elemento consumerà 1 token della quota 1 e nessun token di quota 2 e 3 (poiché riguardano solo gli endpoint di modifica).
• Una richiesta batch get per recuperare fino a 100 elementi consumerà inoltre 1 token della quota 1 e nessun token della quota 2 e 3.
• Una singola richiesta modification per un elemento consumerà 1 token della quota 1, 1 token della quota 2. Se la richiesta è sensibile alla latenza, utilizzerà anche 1 token di 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 elementi con tolleranza di 100 elementi a tolleranza di latenza consumerà 1 token della quota 1 e 1 token della quota 2. La configurazione di questa quota dovrebbe consentire un ampio margine per mantenere aggiornato il catalogo. Tuttavia, se l'algoritmo non è consapevole di questa quota e supera questo tasso, potresti ricevere un errore per ogni chiamata aggiuntiva.
• Una richiesta batch modification per 100 elementi sensibili alla latenza consumerà 1 token della quota 1, 1 token della quota 2 e 100 token della quota 3.

Suggerimenti sull'utilizzo dell'API Catalog Management

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

Monitora l'utilizzo

È bene prestare attenzione ai processi di utilizzo intensivo. Ad esempio, all'inizio dell'integrazione, è più probabile che gli endpoint di gestione del catalogo utilizzino più quota per creare il catalogo iniziale completo e questo potrebbe influire sull'utilizzo in produzione di altri endpoint come l'API purchase status se ti avvicini al limite di utilizzo complessivo. Devi monitorare il consumo delle quote per assicurarti di non superare le quote dell'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.

Ottimizza l'utilizzo delle quote dell'API

Ti consigliamo vivamente di ottimizzare il consumo delle tariffe per ridurre al minimo la probabilità di errori dell'API. Per implementarlo in modo efficace, ti consigliamo di:

• Scegli la giusta strategia di gestione del catalogo. Una volta compresa la quota API, devi scegliere la strategia giusta per la tua applicazione per raggiungere gli obiettivi di gestione del catalogo in modo efficiente.
• 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 sotto il limite orario di 7200 query di modifica del prodotto. 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, una creazione iniziale del catalogo). Se prevedi che questi processi superino il limite orario, implementa i tempi di attesa secondo necessità per rallentare l'utilizzo a un livello sicuro. Valuta la possibilità di utilizzare metodi batch con aggiornamenti con tolleranza di latenza per ottenere una velocità effettiva più elevata.
• Preparati in modo proattivo alla scalabilità. Man mano che l'applicazione cresce, potrebbe essere necessario fare lo scale up dell'utilizzo dell'API e dei vari endpoint. Leggi la documentazione sulle quote dell'API Google Play Developer per i dettagli su come aumentare la tua quota quando stai per raggiungere l'utilizzo massimo.
• Pianifica in modo strategico processi intensivi. Prova a pianificare i processi intensivi del catalogo in funzione dei picchi di utilizzo critici, ad esempio per evitare di eseguire una sincronizzazione completa del catalogo durante i momenti di picco delle vendite della settimana.

Aggiungi logica di gestione degli errori di quota

Indipendentemente da quanto sia efficiente la tua logica di gestione del catalogo, dovresti renderla resiliente a limiti di quota imprevisti, dato che la quota giornaliera è condivisa da endpoint utilizzati in moduli indipendenti dell'integrazione. Assicurati di includere errori di limitazione delle quote nella gestione degli errori e implementa i tempi di attesa appropriati. Ogni chiamata effettuata alle API Google Play Developer genererà una risposta. In caso di errore di una chiamata, riceverai una risposta di errore che include un codice di stato della risposta HTTP e un oggetto errors, con 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 API Google Play Developer per mantenere sincronizzato il proprio catalogo tra il loro backend e Google Play. Garantire che il catalogo di Google Play sia sempre aggiornato con le ultime informazioni del catalogo del backend presenta alcuni vantaggi per creare un'esperienza utente migliore. Ecco alcuni esempi:

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

Esistono determinati limiti e considerazioni che dovresti tenere a mente quando crei il tuo catalogo dei prodotti su Google Play. Una volta compresi questi limiti e sapere come vuoi strutturare il catalogo, è il momento di decidere la tua strategia di sincronizzazione.

Strategie di sincronizzazione del catalogo

Gli endpoint di pubblicazione dell'API Google Play Developer ti consentono di aggiornare il catalogo man mano che vengono apportate modifiche. A volte, potrebbe essere necessario adottare un approccio di aggiornamenti periodici, che prevede l'invio di una batteria di modifiche durante la stessa procedura. Ogni approccio richiede diverse scelte di progettazione. Ogni strategia di sincronizzazione si adatta meglio ad alcuni casi d'uso e a una serie di esigenze che richiedono entrambi, a seconda della situazione. A volte potresti voler aggiornare un prodotto nel momento in cui sei a conoscenza di una nuova modifica, ad esempio per elaborare un aggiornamento urgente di prodotto (ovvero, è necessario correggere il prima possibile un prezzo errato). Altre volte puoi ricorrere a una sincronizzazione periodica in background per garantire la coerenza del backend e dei cataloghi di Google Play. Leggi alcuni casi d'uso comuni in cui potresti voler implementare queste diverse strategie di gestione del catalogo.

Quando inviare aggiornamenti quando il catalogo locale cambia

Idealmente, gli aggiornamenti dovrebbero avvenire non appena vengono apportate modifiche al catalogo dei prodotti del backend per ridurre al minimo le discrepanze.

Questo tipo di aggiornamenti è una buona soluzione quando:

• Devi assicurarti che i tuoi prodotti siano sempre aggiornati.
• Ogni giorno devi apportare alcune modifiche ai tuoi prodotti.
• 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 della quantità minima.

Quando utilizzare gli aggiornamenti periodici

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

• Non devi assicurarti che i tuoi prodotti vengano aggiornati con un breve preavviso.
• Devi pianificare aggiornamenti collettivi o processi di conciliazione.
• Disponi già di un sistema di gestione dei contenuti o del catalogo per gestire i tuoi prodotti digitali

Nel caso di cataloghi di grandi dimensioni, valuta la possibilità di utilizzare metodi batch con aggiornamenti con tolleranza di latenza per ottenere la velocità effettiva massima.

Creare il catalogo dei prodotti

Se hai un ampio catalogo da caricare su Google Play, ti consigliamo di automatizzare il caricamento iniziale. Questo tipo di processo ad alta intensità funziona meglio se si segue una strategia periodica combinata con metodi batch a tolleranza di latenza.

Creare prodotti a pagamento singolo

Per la creazione iniziale di un catalogo di prodotti di grandi dimensioni una tantum, ti consigliamo di utilizzare il metodo inappproducts.batchUpdate con il campo allowMissing impostato su true e il campo latencyTolerance impostato su PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. In questo modo ridurrai al minimo il tempo necessario per creare il catalogo entro i limiti di quota.

Per cataloghi più piccoli, puoi utilizzare il metodo inapp_products.insert. In alternativa, puoi utilizzare il metodo inappproducts.update con il parametro allowMissing come descritto nella sezione Aggiornamenti di prodotto. Questo approccio ha il vantaggio di eliminare la necessità di uno script stateful e di poterlo riavviare da zero in caso di problemi.

Creare prodotti in abbonamento

Per creare un catalogo di grandi dimensioni in abbonamento iniziale, 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 ridurrai al minimo il tempo necessario per creare il catalogo entro i limiti di quota.

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.update con il parametro allowMissing come descritto nella sezione Aggiornamenti di prodotto.

Tutti i metodi precedenti creano abbonamenti insieme ai relativi piani base (forniti nell'oggetto Subscription). 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 consente di creare e gestire le offerte.

Aggiornamenti sul prodotto

I seguenti metodi ti consentono di modificare in modo efficiente i prodotti esistenti, assicurandoti che le offerte siano in linea con le modifiche più recenti.

Aggiorna i prodotti a pagamento singolo

Hai a disposizione tre metodi per aiutarti ad aggiornare i prodotti a pagamento singolo esistenti.

• 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 è necessario aggiornare tutti i campi di una risorsa. Se il parametro allowMissing è impostato su true e l'ID prodotto fornito non esiste ancora, l'endpoint inserisce il prodotto invece di eseguire l'errore.
• 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 una velocità effettiva più elevata.

Aggiornare i prodotti in abbonamento

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

• packageName: il nome del pacchetto dell'app a cui appartiene l'abbonamento.
• productId: ID prodotto univoco dell'abbonamento.
• regionsVersion: la versione di configurazione della regione.

A meno che tu non stia creando una nuova sottoscrizione utilizzando il parametro allowMissing, devi fornire il parametro updateMask. Questo parametro è un elenco di campi separati da virgole da aggiornare.

Ad esempio, se vuoi solo aggiornare una scheda di un prodotto in abbonamento, devi specificare 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 di prezzo più recenti dei piani 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

Che tu scelga di aggiornare il catalogo di Google Play ogni volta che il catalogo del tuo backend viene modificato o periodicamente, se hai un sistema di gestione del catalogo o un database esterno al catalogo di Google Play, potrebbero verificarsi situazioni in cui non è sincronizzato con il catalogo nella configurazione delle tue app su Play. Ciò potrebbe essere dovuto a modifiche manuali al catalogo di emergenza nella console, a un'interruzione del sistema di gestione del catalogo o alla perdita dei dati più recenti.

Puoi creare un processo di riconciliazione del catalogo per evitare una finestra di discrepanza prolungata.

Considerazione del sistema diff

Consigliamo di creare un sistema delle differenze per rilevare incoerenze e riconciliare i due sistemi. Di seguito sono riportati alcuni aspetti da considerare quando si crea un sistema di differenze per mantenere sincronizzati i cataloghi:

• Comprendere i modelli dei dati: il primo passaggio consiste nel comprendere i modelli dei dati del CMS per sviluppatori e dell'API Google Play Developer. Ciò include la conoscenza dei diversi tipi di dati archiviati in ciascun sistema e del modo in cui i diversi elementi dei dati sono mappati tra loro.
• Definisci le regole di diff: dopo aver compreso i modelli dei dati, devi definire le regole di diff. Queste regole determineranno il modo in cui vengono confrontati i dati nei due sistemi. Ad esempio, puoi trovare una corrispondenza tra gli ID prodotto e confrontare gli attributi chiave dell'abbonamento e delle offerte e dei piani base associati.
• Implementa un algoritmo diff: dopo aver definito le regole diff, devi implementare l'algoritmo diff. Questo algoritmo prende i dati dai due sistemi e li confronterà in base alle regole definite. Per recuperare i dati del catalogo da Google Play, puoi utilizzare i metodi inappproducts.list, inappproducts.batchGet monetization.subscriptions.list e monetization.subscriptions.batchGet.
• Generare report delle differenze: l'algoritmo delle differenze genera un report sulle differenze. Questo report mostrerà le differenze tra i due sistemi.
• Riconciliazione delle differenze: dopo aver generato il report delle differenze, devi risolvere le differenze. Ciò potrebbe comportare l'aggiornamento dei dati nel CMS o l'aggiornamento dei dati da parte di Google Play tramite gli endpoint di gestione del catalogo dell'API Developer, a seconda di come aggiorni normalmente il catalogo. Per riconciliare prodotti non sincronizzati, utilizzare gli endpoint di aggiornamento come descritto nella sezione Aggiornamenti di prodotto.

Ritiro del prodotto

L'API Google Play Developer offre diversi metodi per aiutare gli sviluppatori a ritirare i propri prodotti: inappproducts.delete e inappproducts.batchDelete per i prodotti a pagamento singolo e monetization.subscriptions.delete per gli abbonamenti. Il ritiro di un prodotto potrebbe essere necessario in vari scenari, ad esempio:

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

Consigliamo di incorporare il ritiro dei prodotti nella strategia di gestione del catalogo.

Ritira i prodotti a pagamento singolo

Per eliminare i prodotti a pagamento singolo con l'API Google Play Developer, devi utilizzare il metodo inappproducts.delete o inappproducts.batchDelete.

Ritira i prodotti in abbonamento

Puoi eliminare gli abbonamenti utilizzando il metodo monetization.subscriptions.delete. Non è possibile rimuovere un abbonamento dopo aver attivato almeno un piano base.