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 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. Puoi farlo tramite Play Console o automatizzare la gestione del catalogo utilizzando l'API Google Play Developer. L'automazione può contribuire a garantire che il catalogo sia sempre aggiornato e a scalare i cataloghi di grandi dimensioni in cui il coordinamento manuale non è pratico. In questa guida scoprirai come utilizzare l'API Play Developer per creare e gestire un catalogo dei prodotti per la tua app 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 scoprire i diversi tipi di prodotti che puoi vendere con il sistema di fatturazione di Google Play, leggi 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 di prodotti principali:

  • 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ù offerte e opzioni di acquisto per i tuoi prodotti a pagamento singolo. Il modello degli oggetti dei prodotti a pagamento singolo ti offre una maggiore flessibilità nella modalità in cui vendi i 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 tuo backend. Ciò include la creazione, l'aggiornamento e l'eliminazione dei prodotti, nonché la gestione dei prezzi e della disponibilità. A seconda di come gestisci gli acquisti di prodotti a pagamento singolo, modellerai prodotti di consumo (che possono essere acquistati tutte le volte che vuoi) o diritti permanenti (che 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 eseguire operazioni come creare, aggiornare ed eliminare gli abbonamenti o controllarne i prezzi e la disponibilità 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 contemporaneamente fino a 100 entità nella stessa app.

I metodi batch, se utilizzati con la tolleranza di latenza attivata, supportano un throughput più elevato e sono particolarmente utili per gli sviluppatori con cataloghi di grandi dimensioni per la creazione iniziale o la riconciliazione del catalogo.

Latenza di propagazione degli aggiornamenti e throughput

Una volta completata una 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 dei prodotti sono sensibili alla latenza. Ciò significa che sono ottimizzati per una rapida propagazione attraverso i sistemi di backend, che in genere si riflette 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. In questo modo, la velocità effettiva degli aggiornamenti aumenterà in modo significativo. La propagazione degli aggiornamenti con tolleranza alla latenza ai dispositivi degli utenti finali richiederà 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 tuo catalogo dei prodotti:

  1. Le API Google Play Developer sono organizzate in categorie chiamate bucket, ognuno dei quali ha un proprio limite di quota al minuto. Per saperne di più, consulta Quote.
  2. Gli endpoint di modifica dei prodotti applicano anche un limite di 7200 query all'ora. Si tratta di un limite unico per i prodotti a pagamento singolo e gli abbonamenti e per tutte le richieste di modifica, tra cui creazione, aggiornamento, attivazione ed eliminazione. Le chiamate ai metodi di modifica in batch vengono conteggiate come una singola query per questa quota, indipendentemente dal numero di singole richieste incluse o dalla loro 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é in 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 (poiché riguardano solo gli endpoint di modifica).
  • Anche una richiesta batch get per recuperare fino a 100 elementi utilizzerà 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 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 singola.
  • Una richiesta batch modification per 100 elementi con tolleranza alla latenza consumerà 1 token della quota 1 e 1 token della quota 2. Questa configurazione della quota dovrebbe consentire un ampio margine per mantenere aggiornato il catalogo, ma se l'algoritmo non è a conoscenza di questa quota e supera questa frequenza, potresti ricevere un errore per ogni chiamata aggiuntiva.
  • Una richiesta modification batch 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.

Monitora l'utilizzo

Devi essere a conoscenza dei processi con un utilizzo elevato. Ad esempio, all'inizio dell'integrazione, gli endpoint di gestione del catalogo probabilmente consumeranno 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 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 Google Cloud o qualsiasi altro strumento di monitoraggio delle API interno o di terze parti di tua scelta.

Ottimizza l'utilizzo della quota API

Ti consigliamo vivamente di ottimizzare il consumo della frequenza 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 per 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 chiamate di modifica ridondanti o non necessarie alle API. Potrebbe essere necessario tenere un log delle modifiche nel catalogo di backend.
  • Rimanere al di sotto del limite orario di modifica dei prodotti di 7200 query. 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 di un catalogo iniziale). Se prevedi che questi processi superino il limite orario, implementa le attese necessarie per rallentare l'utilizzo a un livello sicuro. Valuta la possibilità di utilizzare metodi batch con aggiornamenti tolleranti alla latenza per ottenere un throughput più elevato.
  • Preparati in modo proattivo alla scalabilità. Man mano che la tua applicazione cresce, potresti dover scalare 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 i processi pesanti in modo strategico. Prova a pianificare i processi del catalogo più pesanti 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.

Aggiungi 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 nei moduli indipendenti della tua 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 il proprio catalogo sincronizzato tra il backend e Google Play. Assicurarti che il tuo catalogo di Google Play sia sempre aggiornato con le informazioni più recenti del catalogo del tuo 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 consigliati e i dettagli dei prodotti che gli utenti visualizzano sulle varie piattaforme e assicurarti che siano coerenti.
  • Avrai a portata di mano i dettagli del prodotto nel tuo backend durante l'elaborazione di nuovi acquisti, senza dover aumentare la latenza e il rischio di errori effettuando chiamate aggiuntive all'API Google Play Developer durante i flussi critici degli utenti.

Esistono alcuni limiti e considerazioni da tenere presente quando crei il tuo catalogo dei prodotti su Google Play. Una volta compresi questi limiti e stabilito come strutturare il 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 aggiornare il tuo catalogo man mano che vengono apportate modifiche. A volte, potrebbe essere necessario adottare un approccio di aggiornamenti periodici, in cui invii una serie di modifiche nello stesso processo. Ogni approccio richiede scelte di progettazione diverse. Ogni strategia di sincronizzazione si adatta ad alcuni casi d'uso meglio di altri e potresti avere un insieme di esigenze che richiedono entrambe, a seconda della situazione.

A volte potresti voler aggiornare un prodotto non appena vieni a conoscenza di 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 periodica in background per assicurarti che i tuoi 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 aggiornamenti in base alle modifiche del catalogo locale

Idealmente, gli aggiornamenti dovrebbero avvenire 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 che sono già in produzione e in vendita.

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

Quando utilizzare gli aggiornamenti periodici

Gli aggiornamenti periodici vengono eseguiti in modo asincrono rispetto alla modifica 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 in blocco o processi di conciliazione.
  • Hai già un sistema di gestione dei contenuti o del catalogo 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 il massimo throughput.

Crea il tuo 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 meglio se viene seguita una strategia periodica combinata con metodi batch con tolleranza della latenza.

Crea prodotti a pagamento singolo

Per la creazione iniziale una tantum del catalogo dei prodotti, ti consigliamo di utilizzare il metodo monetization.onetimeproducts.batchUpdate o il metodo 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, ridurrai al minimo il tempo necessario per creare il catalogo entro i limiti di quota.

Crea prodotti in abbonamento

Per la creazione iniziale di un catalogo di grandi dimensioni per l'abbonamento, 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 della 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.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 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 le ultime modifiche.

Aggiorna i prodotti a pagamento singolo

Per aggiornare i prodotti a pagamento singolo esistenti, puoi utilizzare i seguenti metodi.

  • 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 inserisce il prodotto anziché non riuscire.
  • inappproducts.batchUpdate: questa è una versione batch dell'endpoint di aggiornamento, che ti 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 più elevato.

Aggiorna i prodotti in abbonamento

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

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

Ad esempio, se vuoi aggiornare solo una 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, eliminare i piani base o per eseguire la migrazione degli abbonati alle versioni più recenti dei prezzi dei piani base, utilizza l'endpoint monetization.subscriptions.basePlans.

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

Riconciliazione del catalogo

Sia che tu scelga di aggiornare il catalogo di Google Play ogni volta che cambia il catalogo del tuo backend 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 della configurazione delle tue app su Play. Ciò potrebbe essere dovuto a modifiche manuali di emergenza al catalogo 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 sul sistema di differenze

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

  • Comprendi 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 ciascun sistema e il modo in cui i diversi elementi di dati vengono mappati tra loro.
  • Definisci le regole di diff: una volta compresi i modelli di dati, devi definire le regole di diff. Queste regole determinano il modo in cui vengono confrontati i dati nei due sistemi. Ad esempio, potresti voler abbinare gli ID prodotto e confrontare gli attributi chiave dell'abbonamento e dei relativi piani base e offerte associati.
  • Implementa un algoritmo di diff: una volta definite le regole di diff, devi implementare l'algoritmo di diff. Questo algoritmo prenderà i dati dai 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 confronto 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 risolvere le differenze. A seconda di come aggiorni normalmente il tuo catalogo, potrebbe essere necessario aggiornare i dati nel tuo CMS o sul 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:

La ritiro di un prodotto potrebbe essere necessaria 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.