Gestire il catalogo dei prodotti

Questa guida spiega come utilizzare l'API Google Play Developer per creare e gestire un catalogo dei 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 mettere a disposizione 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ò contribuire a garantire che il tuo catalogo sia sempre aggiornato e a scalare in base a cataloghi di grandi dimensioni in cui la coordinazione manuale non è praticabile. In questa guida scoprirai come utilizzare l'API Google Play Developer per creare e gestire un catalogo di prodotti per la tua app Google Play. Consulta la nostra guida Preparativi per 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, consulta Informazioni sui tipi di prodotti in-app e considerazioni relative al catalogo. Google offre due insiemi principali di API per la gestione del catalogo su Play, corrispondente alle due principali categorie di prodotti:

  • Prodotti a pagamento singolo
  • Prodotti in abbonamento

Prodotti a pagamento singolo

L'endpoint inappproducts ti consente di gestire i prodotti una tantum dal tuo backend. Sono inclusi la creazione, l'aggiornamento e l'eliminazione di 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 (che possono essere acquistati tutte le volte che vuoi) o i diritti permanenti (che non possono essere acquistati due volte dallo stesso utente). Puoi decidere quali prodotti una tantum devono essere consumabili o meno.

Prodotti in abbonamento

L'endpoint monetization.subscriptions ti aiuta a gestire i prodotti con abbonamento dal tuo backend per sviluppatori. Puoi, ad esempio, creare, aggiornare e eliminare abbonamenti oppure 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 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 abilitata, supportano un throughput più elevato e sono particolarmente utili per gli sviluppatori di cataloghi di grandi dimensioni per la creazione iniziale o la riconciliazione del catalogo.

Latenza di propagazione dell'aggiornamento rispetto alla velocità in Mbps

Una volta completata la richiesta di creazione o modifica di un prodotto, le modifiche potrebbero non essere immediatamente visibili agli utenti finali sui loro dispositivi a causa di ritardi nell'elaborazione della rete o del backend. Per impostazione predefinita, tutte le richieste di modifica del prodotto sono sensibili alla latenza. Ciò significa che sono ottimizzati per una rapida propagazione attraverso i sistemi di backend e in genere si riflettono sui dispositivi degli utenti finali entro pochi minuti. Tuttavia, esiste un limite orario al numero di queste richieste di modifica. Nei 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à notevolmente il throughput degli aggiornamenti. La propagazione degli aggiornamenti tolleranti alla latenza ai dispositivi degli utenti finali richiede fino a 24 ore.

Configurazione delle quote

Quando utilizzi l'API Play Console, devi tenere presente diversi limiti di quota per gestire il tuo catalogo di prodotti:

  1. Le API Google Play Developer hanno un limite predefinito di 200.000 query al giorno. Questo limite di 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 applicano anche un limite di 7200 query all'ora. Si tratta di un unico limite per i prodotti una tantum e gli abbonamenti e per tutte le richieste di modifica, tra cui creazione, aggiornamento, attivazione ed eliminazione. Le chiamate al metodo di modifica batch vengono conteggiate come una query per questa quota, indipendentemente dal numero di singole richieste incluse o dalla loro sensibilità alla 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 distintamente ai fini di questa quota. Questa quota ha implicazioni pratiche solo per gli utenti dell'API batch che eseguono aggiornamenti sensibili alla latenza, poiché in altri casi la quota 2 verrà esaurita prima o contemporaneamente a questa quota.

Di seguito sono riportati 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 (poiché 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 della quota 1 e 1 token della quota 2. Se la richiesta è sensibile alla latenza, consumerà anche un 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 singola.
  • Una richiesta batch modification per 100 elementi tolleranti alla latenza consumerà 1 token della quota 1 e 1 token della quota 2. Questa configurazione della quota dovrebbe consentire un margine sufficiente per mantenere aggiornato il tuo catalogo, ma se l'algoritmo non è consapevole di questa quota e supera questa percentuale, 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 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 consapevole dei processi di utilizzo intensivo. Ad esempio, all'inizio dell'integrazione, gli endpoint di gestione del catalogo hanno maggiori probabilità di consumare più quota per creare il catalogo iniziale completo e questo potrebbe potenzialmente influire sull'utilizzo in produzione di altri endpoint come l'API di stato dell'acquisto se sei vicino al limite di utilizzo complessivo. Devi monitorare il consumo della quota 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 di Google Cloud o qualsiasi altro strumento di monitoraggio delle API interno o di terze parti a tua scelta.

Ottimizza l'utilizzo della quota API

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

  • Scegli la strategia di gestione del catalogo giusta. Una volta compresa la quota dell'API, devi scegliere la strategia giusta per la tua applicazione in modo da raggiungere in modo efficiente i tuoi obiettivi di gestione del catalogo.
  • Effettua solo il numero minimo di chiamate necessarie per riflettere le modifiche.
  • Non inviare alle API chiamate di modifica ridondanti o non necessarie. Per farlo, potrebbe essere necessario mantenere un log delle modifiche nel catalogo di backend.
  • Non superare il limite orario di 7200 query per la modifica dei prodotti. Ti consigliamo di 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 di un catalogo). Se prevedi che queste procedure superino il limite orario, implementa le interruzioni necessarie per rallentare l'utilizzo a un livello sicuro. Valuta la possibilità di utilizzare metodi batch con aggiornamenti tolleranti alla latenza per ottenere una maggiore velocità in uscita.
  • 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 stai avvicinando al limite di utilizzo.
  • Pianifica in modo strategico i processi più pesanti. Prova a pianificare le operazioni più complesse sul catalogo in base ai picchi di utilizzo critici, ad esempio puoi evitare di eseguire una sincronizzazione completa del catalogo durante i periodi 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 ai limiti di quota imprevisti, dato che la quota giornaliera è condivisa dagli endpoint utilizzati nei moduli indipendenti della tua integrazione. Assicurati di includere gli errori di throttling delle quote nella gestione degli errori e di implementare le attese appropriate. Ogni chiamata alle API per sviluppatori Google Play genererà una risposta. In caso di fallimento 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 dell'errore e un messaggio di debug. Ad esempio, se superi il limite giornaliero, potresti visualizzare un messaggio di 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 proprio 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. Ad esempio:

  • Potrai consultare l'intero elenco delle offerte disponibili e gestire i tag delle offerte e dei piani base per influenzare la tua idoneità e la 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 disposizione i dettagli del prodotto nel tuo backend durante l'elaborazione dei nuovi acquisti, senza dover aumentare la latenza e il rischio di errori effettuando chiamate aggiuntive all'API Google Play Developer durante i flussi critici per l'utente.

Esistono determinati limiti e considerazioni da tenere presente quando crei il tuo catalogo di prodotti su Google Play. Una volta compresi questi limiti e stabilito come strutturare il tuo catalogo, è il momento di decidere la strategia di sincronizzazione.

Strategie di sincronizzazione dei cataloghi

Gli endpoint di pubblicazione dell'API Google Play Developer ti consentono di aggiornare il 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 design diverse. Ogni strategia di sincronizzazione è più adatta ad alcuni casi d'uso rispetto ad altri e potresti avere un insieme di esigenze che richiedono entrambe, a seconda della situazione. A volte potresti voler aggiornare un prodotto nel momento in cui ne conosci una nuova modifica, ad esempio per elaborare un aggiornamento urgente del prodotto (ad es. un prezzo errato deve essere corretto il prima possibile). In altri casi, puoi utilizzare una sincronizzazione in background periodica per assicurarti che il tuo backend e i cataloghi di Google Play siano sempre coerenti. Leggi alcuni casi d'uso comuni in cui potresti voler implementare queste diverse strategie di gestione del catalogo.

Quando inviare aggiornamenti man mano che il catalogo locale cambia

Idealmente, gli aggiornamenti dovrebbero avvenire non appena viene apportata una modifica al catalogo dei prodotti del tuo 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 il tuo catalogo sincronizzato con la finestra di discrepanza più ridotta.

Quando utilizzare gli aggiornamenti periodici

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

  • Non devi assicurarti che i tuoi prodotti vengano aggiornati in breve tempo.
  • Devi pianificare aggiornamenti collettivi o procedure di conciliazione.
  • Hai già un sistema di gestione dei contenuti o dei cataloghi per gestire i tuoi prodotti digitali e aggiornare costantemente il tuo catalogo

In caso di cataloghi di grandi dimensioni, valuta la possibilità di utilizzare metodi batch con aggiornamenti tolleranti alla latenza per ottenere una velocità in uscita massima.

Creare il catalogo dei prodotti

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

Creare prodotti a pagamento singolo

Per la creazione iniziale di un catalogo dei prodotti di grandi dimensioni a pagamento singolo, 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, il tempo necessario per creare il catalogo entro i limiti di quota sarà ridotto al minimo.

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 dei prodotti. Questo approccio ha il vantaggio di eliminare la necessità che lo script sia stato eseguito e può essere riavviato da zero in caso di problemi.

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 sarà ridotto al minimo.

Per i cataloghi di abbonamenti più piccoli, l'API Google 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 di base (forniti all'interno dell'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 di prodotto

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

Aggiornare i prodotti una tantum

Esistono tre metodi per aggiornare i prodotti una tantum esistenti.

  • inappproducts.patch: l'endpoint patch viene utilizzato per aggiornare parzialmente una risorsa. Ciò significa che puoi aggiornare campi specifici specificati 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 della risorsa nel corpo della richiesta. L'endpoint update viene in genere utilizzato quando è necessario 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é restituire un 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 maggiore velocità in uscita.

Aggiornare i prodotti in abbonamento

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

A meno che non crei una nuova sottoscrizione utilizzando il parametro allowMissing, devi fornire il parametro updateMask. Questo parametro è un elenco separato da virgole dei campi da aggiornare.

Ad esempio, se vuoi aggiornare solo la scheda di un prodotto in abbonamento, devi specificare il campo listings per il 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 un throughput più elevato.

Per attivare, disattivare ed eliminare i piani base o per eseguire la migrazione degli abbonati alle ultime versioni dei prezzi 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

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

Puoi creare una procedura di riconciliazione del catalogo per evitare un periodo di tempo prolungato in cui si verificano discrepanze.

Considerazione del sistema di confronto

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

  • Comprendi i modelli di dati: il primo passaggio consiste nel comprendere i modelli di dati del CMS per gli sviluppatori e dell'API Google Play Developer. Ciò include conoscere i diversi tipi di dati archiviati in ogni sistema e come i diversi elementi di dati sono mappati tra loro.
  • Definire le regole di differenza: dopo aver compreso i modelli di dati, devi definire le regole di differenza. Queste regole determineranno il modo in cui i dati dei due sistemi vengono confrontati. Ad esempio, potresti voler associare gli ID prodotto e confrontare gli attributi chiave dell'abbonamento e i relativi piani base e offerte associati.
  • Implementa un algoritmo di confronto:dopo aver definito le regole di confronto, devi implementare l'algoritmo di confronto. Questo algoritmo prende i dati dei due sistemi e li confronta in base alle regole che hai definito. Per recuperare i dati del catalogo da Google Play, puoi utilizzare i metodi inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list e monetization.subscriptions.batchGet.
  • Genera report sulle differenze:l'algoritmo diff genera un report sulle differenze. Questo report mostrerà le differenze tra i due sistemi.
  • Riconcilia le differenze: dopo aver generato il report sulle differenze, devi risolvere le differenze. Potrebbe essere necessario aggiornare i dati nel tuo CMS o aggiornare i dati lato Google Play utilizzando gli endpoint di gestione del catalogo dell'API per gli sviluppatori, a seconda di come aggiorni normalmente il catalogo. 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 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.
  • Ritiro di una funzionalità o di un servizio.

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

Ritirare i prodotti a pagamento singolo

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

Ritirare i prodotti in abbonamento

Puoi eliminare gli abbonamenti utilizzando il metodo monetization.subscriptions.delete. Un abbonamento non può essere rimosso dopo che è stato attivato almeno un piano base.