Administra tu catálogo de productos

En esta guía, se explica cómo usar la API de Google Play Developer para crear y administrar un catálogo de productos para tu app de Play.

Para vender productos en tu app a través del sistema de facturación de Google Play, debes configurar un catálogo con todos los productos que deseas que tus usuarios puedan comprar. Esto se puede hacer a través de Play Console, o bien puedes automatizar la administración del catálogo con la API de Google Play Developer. La automatización puede ayudarte a garantizar que tu catálogo esté siempre actualizado y a escalar a catálogos grandes en los que la coordinación manual no es práctica. En esta guía, verás cómo usar la API de Play Developer para crear y administrar un catálogo de productos para tu app de Play. Revisa nuestra guía de preparación para obtener instrucciones sobre cómo configurar la API de Google Play Developer para tu integración de backend.

APIs de Catalog Management

Para obtener información sobre los diferentes tipos de productos que puedes vender con el sistema de Facturación Google Play, consulta Información sobre los tipos de productos integrados en la aplicación y consideraciones sobre el catálogo. Google ofrece dos conjuntos principales de APIs para la administración de catálogos en Play, que corresponden a las dos categorías de productos principales:

• Productos únicos
• Productos de suscripción

Productos únicos

El extremo inappproducts te permite administrar productos únicos desde tu backend. Esto incluye crear, actualizar y borrar productos, así como administrar los precios y la disponibilidad. Según la forma en que administres las compras de productos únicos, modelarás productos consumibles (se pueden comprar tantas veces como se desee) o derechos permanentes (el mismo usuario no puede realizar la compra dos veces). Puedes decidir qué productos únicos deben ser consumibles o no.

Productos de suscripción

El extremo monetization.subscriptions te ayuda a administrar productos de suscripción desde tu backend de desarrollador. Puedes crear, actualizar y borrar suscripciones, o bien controlar su disponibilidad y precios regionales. Además del extremo monetization.subscriptions, también proporcionamos monetization.subscriptions.basePlans y monetization.subscriptions.basePlans.offers para administrar, respectivamente, los planes básicos y las ofertas de las suscripciones.

Métodos por lotes

Los extremos inappproducts y monetization.subscriptions proporcionan una serie de métodos por lotes que permiten recuperar o administrar hasta 100 entidades en la misma app al mismo tiempo.

Cuando se usan con la tolerancia a latencia habilitada, los métodos por lotes admiten una mayor productividad y son particularmente útiles para los desarrolladores de catálogos grandes para la creación inicial de catálogos o la conciliación de catálogos.

Latencia de propagación en comparación con la capacidad de procesamiento

Una vez que se completa una solicitud de creación o modificación de un producto, es posible que los usuarios finales no vean los cambios de inmediato en sus dispositivos debido a demoras en el procesamiento de la red o del backend. De forma predeterminada, todas las solicitudes de modificación de productos son sensibles a la latencia. Esto significa que están optimizados para una propagación rápida a través de sistemas de backend, que suelen reflejarse en los dispositivos del usuario final en cuestión de minutos. Sin embargo, hay un límite por hora en la cantidad de solicitudes de modificación. En los casos en que necesites crear o actualizar muchos productos (por ejemplo, durante la creación inicial de un catálogo grande), puedes usar métodos por lotes con el campo latencyTolerance configurado como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Esto aumentará significativamente la capacidad de procesamiento de actualizaciones. Las actualizaciones tolerantes a la latencia tardarán hasta 24 horas en propagarse a los dispositivos del usuario final.

Configuración de cuotas

Existen varios límites de cuota que debes tener en cuenta cuando usas la API de Play Developer para administrar tu catálogo de productos:

1. Las APIs de Google Play Developer tienen un límite predeterminado de 200,000 consultas por día. Este límite de cuota se aplica a la agregación del uso en todos los extremos, incluidas las APIs de administración de catálogos.
2. Los extremos de modificación de productos también aplican un límite de 7,200 consultas por hora. Este es un límite único para los productos únicos y las suscripciones, así como para todas las solicitudes de modificación, incluidas las de creación, actualización, activación y eliminación. Las llamadas al método de modificación por lotes se cuentan como una consulta para esta cuota, independientemente de la cantidad de solicitudes individuales incluidas o su sensibilidad de latencia.
3. Las modificaciones sensibles a la latencia también tienen un límite de 7,200 modificaciones por hora. En el caso de los métodos por lotes, cada solicitud de modificación anidada se cuenta por separado para el propósito de esta cuota. Esta cuota tiene implicaciones prácticas solo para los usuarios de la API por lotes que realizan actualizaciones sensibles a la latencia, ya que, en otros casos, la cuota 2 se agotará antes o al mismo tiempo que esta cuota.

A continuación, se muestran varios ejemplos ilustrativos para comprender el uso de la cuota de diferentes solicitudes:

• Una sola solicitud get para recuperar un elemento consumirá 1 token de la cuota 1 y ningún token de las cuotas 2 y 3 (ya que solo se relacionan con los extremos de modificación).
• Una solicitud get por lotes para recuperar hasta 100 elementos también consumirá 1 token de la cuota 1 y no tokens de las cuotas 2 y 3.
• Una sola solicitud modification para un artículo consumirá 1 token de la cuota 1 y 1 token de la cuota 2. Si la solicitud es sensible a la latencia, también consumirá 1 token de cuota 3. Debido a que la cuota C tiene el mismo límite que la cuota 2, no tiene implicaciones prácticas para los usuarios que solo usan métodos de modificación únicos.
• Una solicitud de lote modification para 100 elementos tolerantes a la latencia consumirá 1 token de la cuota 1 y 1 token de la cuota 2. Esta configuración de cuota debería permitir un margen amplio para mantener tu catálogo actualizado, pero si tu algoritmo no está al tanto de esta cuota y supera esta tasa, es posible que recibas un error por cada llamada adicional.
• Una solicitud de lote modification para 100 elementos sensibles a la latencia consumirá 1 token de la cuota 1, 1 token de la cuota 2 y 100 tokens de la cuota 3.

Recomendaciones de uso de la API de Catalog Management

Si cumples con estos lineamientos, optimizas tus interacciones con la API, lo que garantiza una experiencia de administración de catálogos fluida y eficiente.

Supervisa tu uso

Debes tener en cuenta los procesos de uso intensivo. Por ejemplo, al comienzo de la integración, es más probable que los extremos de administración de catálogos consuman más cuota para crear tu catálogo inicial completo, lo que podría afectar el uso de producción de otros extremos, como la API de estado de compra, si estás cerca del límite de uso general. Debes supervisar el consumo de tu cuota para asegurarte de que no superes las cuotas de la API. Existen varias formas de supervisar el uso. Por ejemplo, puedes usar el panel de cuotas de las APIs de Google Cloud o cualquier otra herramienta de supervisión de APIs interna o externa que elijas.

Optimiza el uso de la cuota de la API

Se recomienda optimizar el consumo de tarifas para minimizar la probabilidad de errores de API. Para implementar esta función de manera eficaz, te recomendamos que hagas lo siguiente:

• Elige la estrategia de administración de catálogos adecuada. Una vez que comprendas la cuota de la API, debes elegir la estrategia correcta para que tu aplicación logre sus objetivos de administración de catálogos de manera eficiente.
• Realiza solo la cantidad mínima de llamadas que necesites para reflejar los cambios.
• No envíes llamadas de modificación redundantes o innecesarias a las APIs. Es posible que esto requiera que mantengas un registro de cambios en tu catálogo de backend.
• No superes el límite de 7,200 consultas por hora para la modificación de productos. Te recomendamos que crees procesos de sincronización que requieran que realices una gran cantidad de modificaciones de productos en un período breve (por ejemplo, la creación de un catálogo inicial). Si esperas que estos procesos superen el límite por hora, implementa las esperas necesarias para reducir el uso a un nivel seguro. Considera usar métodos por lotes con actualizaciones tolerantes a la latencia para lograr una mayor capacidad de procesamiento.
• Prepárate de forma proactiva para escalar. A medida que tu aplicación crece, es posible que debas escalar el uso de la API y los diversos extremos. Lee la documentación de cuotas de la API de Google Play Developer para obtener detalles sobre cómo aumentar tu cuota cuando te acerques al uso máximo.
• Programa de forma estratégica los procesos pesados. Intenta programar tus procesos de catálogo pesados alrededor de los picos de uso críticos. Por ejemplo, puedes evitar ejecutar una sincronización de catálogo completa durante los períodos de ventas más importantes de la semana.

Agrega lógica de manejo de errores de cuota

Independientemente de la eficiencia con la que crees tu lógica de administración de catálogos, debes asegurarte de que sea resistente a límites de cuota inesperados, ya que los extremos que se usan en los módulos independientes de tu integración comparten la cuota diaria. Asegúrate de incluir errores de limitación de cuota en el manejo de errores y de implementar las esperas adecuadas. Cada llamada a las APIs de Google Play Developer generará una respuesta. En el caso de que falle una llamada, recibirás una respuesta de error que incluye un código de estado de respuesta HTTP y un objeto errors, que proporciona más detalles sobre el dominio de error y un mensaje de depuración. Por ejemplo, si superas tu límite diario, es posible que encuentres un error similar al siguiente:

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

Implementación de la administración de catálogos

Los desarrolladores usan los extremos de publicación de productos de la API de Google Play Developer para mantener su catálogo sincronizado entre su backend y Google Play. Asegurarte de que el catálogo de Google Play siempre esté actualizado con la información más reciente del catálogo de tu backend tiene ventajas para crear una mejor experiencia del usuario. Por ejemplo:

• Podrás consultar la lista completa de ofertas disponibles y administrar las etiquetas de ofertas y planes básicos para influir en tu propia elegibilidad y lógica de publicación de ofertas.
• Puedes verificar los diferentes precios y detalles de los productos que los usuarios ven en todas las plataformas y asegurarte de que sean coherentes.
• Tendrás los detalles de los productos a mano en tu backend cuando proceses compras nuevas, sin necesidad de aumentar la latencia y el riesgo de fallas realizando llamadas adicionales a la API de Google Play Developer durante los flujos críticos del usuario.

Existen ciertos límites y consideraciones que debes tener en cuenta cuando crees tu catálogo de productos en Google Play. Una vez que comprendas estos límites y sepas cómo deseas estructurar tu catálogo, es hora de decidir tu estrategia de sincronización.

Estrategias de sincronización de catálogos

Los extremos de publicación de la API de Google Play Developer te permiten actualizar tu catálogo a medida que se producen cambios. En ocasiones, es posible que debas adoptar un enfoque de actualizaciones periódicas, en el que envíes una serie de cambios en el mismo proceso. Cada enfoque requiere diferentes opciones de diseño. Cada estrategia de sincronización se adaptará mejor a algunos casos de uso que a otros, y es posible que tengas un conjunto de necesidades que requiera ambas, según la situación. A veces, es posible que desees actualizar un producto en cuanto tengas conocimiento de un cambio nuevo, por ejemplo, para procesar una actualización urgente (es decir, un precio incorrecto que se debe corregir lo antes posible). En otras ocasiones, puedes usar una sincronización en segundo plano periódica para asegurarte de que el backend y los catálogos de Play siempre sean coherentes. Lee algunos casos de uso frecuentes en los que podrías implementar estas diferentes estrategias de administración de catálogos.

Cuándo enviar actualizaciones a medida que cambia tu catálogo local

Lo ideal es que las actualizaciones se realicen en cuanto haya algún cambio en el catálogo de productos de tu backend para minimizar las discrepancias.

Este tipo de actualizaciones es una buena opción en los siguientes casos:

• Debes asegurarte de que tus productos siempre estén actualizados.
• Debes hacer algunos cambios en tus productos todos los días.
• Debes actualizar los productos que ya están en producción y se están vendiendo.

Este enfoque es más fácil de implementar y te permite mantener tu catálogo sincronizado con la ventana de discrepancia de importe más baja.

Cuándo usar actualizaciones periódicas

Las actualizaciones periódicas se ejecutan de forma asíncrona a la edición de productos en tu backend y son una buena opción en los siguientes casos:

• No tienes que asegurarte de que tus productos se actualicen con poco tiempo de anticipación.
• Debes planificar actualizaciones masivas o procesos de conciliación.
• Ya tienes un sistema de administración de contenido o catálogos para controlar tus productos digitales y que actualiza tu catálogo constantemente.

En el caso de catálogos grandes, considera usar métodos por lotes con actualizaciones tolerantes a la latencia para lograr la máxima capacidad de procesamiento.

Crea tu catálogo de productos

Si tienes un catálogo grande para subir a Google Play, te recomendamos que automatices la carga inicial. Este tipo de proceso intensivo funciona mejor si se sigue una estrategia periódica combinada con métodos por lotes tolerantes a la latencia.

Crea productos únicos

Para la creación inicial de un catálogo grande de productos únicos, te recomendamos usar el método inappproducts.batchUpdate con el campo allowMissing configurado en true y el campo latencyTolerance configurado en PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. De esta manera, se minimizará el tiempo que se tarda en crear el catálogo dentro de los límites de cuota.

Para catálogos más pequeños, puedes usar el método inapp_products.insert. Como alternativa, puedes usar el método inappproducts.update con el parámetro allowMissing, como se describe en la sección Actualizaciones de productos. Este enfoque tiene el beneficio de quitar la necesidad de que la secuencia de comandos tenga estado y se pueda reiniciar desde cero si algo sale mal.

Crea productos de suscripción

Para la creación inicial de un catálogo grande de suscripción, te recomendamos que uses el método monetization.subscriptions.batchUpdate con el campo allowMissing establecido en true y el campo latencyTolerance establecido en PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. De esta manera, se minimizará el tiempo que se tarda en crear el catálogo dentro de los límites de cuota.

En el caso de los catálogos de suscripciones más pequeños, la API de Play Developer proporciona el método monetization.subscriptions.create. Como alternativa, puedes crear suscripciones con el método monetization.subscriptions.patch con el parámetro allowMissing, como se describe en la sección Actualizaciones de productos.

Todos los métodos anteriores crean suscripciones junto con sus planes básicos (proporcionados dentro del objeto Subscription). Estos planes básicos son inactivos inicialmente. Para administrar el estado de los planes básicos, puedes usar el extremo monetization.subscriptions.basePlans, incluida la activación de un plan básico para que esté disponible para la compra. Además, el extremo monetization.subscriptions.basePlans.offers te permite crear y administrar ofertas.

Actualizaciones de productos

Los siguientes métodos te permiten modificar tus productos existentes de manera eficiente, lo que garantiza que tus ofertas se alineen con tus ajustes más recientes.

Actualiza productos únicos

Existen tres métodos disponibles para ayudarte a actualizar los productos únicos existentes.

• inappproducts.patch: El extremo de parches se usa para actualizar un recurso de forma parcial. Esto significa que puedes actualizar campos específicos que especifiques en el cuerpo de la solicitud. Por lo general, el extremo de parche se usa cuando solo necesitas actualizar algunos campos de un recurso.
• inappproducts.update: El extremo de actualización se usa para actualizar un recurso por completo. Esto significa que deberás enviar todo el objeto de recurso en el cuerpo de la solicitud. Por lo general, el extremo de actualización se usa cuando necesitas actualizar todos los campos de un recurso. Cuando el parámetro allowMissing se establece en true y el ID del producto proporcionado aún no existe, el extremo insertará el producto en lugar de fallar.
• inappproducts.batchUpdate: Esta es una versión por lotes del extremo de actualización, que te permite modificar varios productos con una sola consulta. Úsalo junto con el campo latencyTolerance establecido en PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para lograr una mayor capacidad de procesamiento.

Actualiza los productos de suscripción

Para actualizar las suscripciones existentes, puedes usar el método monetization.subscriptions.patch. Este método toma los siguientes parámetros obligatorios:

• packageName: Es el nombre del paquete de la app a la que pertenece la suscripción.
• productId: Es el ID de producto único de la suscripción.
• regionsVersion: La versión de configuración de la región

A menos que crees una suscripción nueva con el parámetro allowMissing, debes proporcionar el parámetro updateMask. Este parámetro es una lista de campos separados por comas que deseas actualizar.

Por ejemplo, si solo quieres actualizar una ficha de un producto de suscripción, debes especificar el campo listings en el parámetro updateMask.

Puedes usar monetization.subscriptions.batchUpdate para actualizar varias suscripciones al mismo tiempo. Úsalo junto con el campo latencyTolerance establecido en PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para lograr una mayor productividad.

Para activar, desactivar o borrar planes básicos, o migrar suscriptores a las versiones de precios de planes básicos más recientes, usa el extremo monetization.subscriptions.basePlans.

Además, puedes actualizar las ofertas de tus planes básicos con el método monetization.subscriptions.basePlans.offers.patch.

Conciliación de catálogos

Ya sea que elijas actualizar el catálogo de Google Play cada vez que cambie el catálogo de tu backend o de forma periódica, si tienes un sistema de administración de catálogos o una base de datos fuera del catálogo de Google Play, es posible que haya situaciones en las que no esté sincronizado con el catálogo de la configuración de tus apps en Play. Esto puede deberse a cambios manuales de emergencia en el catálogo de Play Console, a una interrupción en el sistema de administración de catálogos o a que perdiste los datos más recientes.

Puedes crear un proceso de conciliación de catálogos para evitar un período de discrepancia prolongado.

Consideración del sistema de diferencias

Recomendamos crear un sistema de diferencias para detectar inconsistencias y conciliar los dos sistemas. Estos son algunos aspectos que debes tener en cuenta cuando crees un sistema de diferencias para mantener tus catálogos sincronizados:

• Comprende los modelos de datos: El primer paso es comprender los modelos de datos del CMS del desarrollador y la API de Google Play Developer. Esto incluye conocer los diferentes tipos de datos que se almacenan en cada sistema y cómo se asignan los diferentes elementos de datos entre sí.
• Define las reglas de diferencia: Una vez que comprendas los modelos de datos, debes definir las reglas de diferencia. Estas reglas determinarán cómo se comparan los datos de los dos sistemas. Por ejemplo, puedes hacer coincidir los IDs de producto y comparar los atributos clave de la suscripción y sus ofertas y planes básicos asociados.
• Implementa un algoritmo de diferencia: Una vez que hayas definido las reglas de diferencia, debes implementar el algoritmo de diferencia. Este algoritmo tomará los datos de los dos sistemas y los comparará según las reglas que hayas definido. Para obtener los datos del catálogo de Google Play, puedes usar los métodos inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list y monetization.subscriptions.batchGet.
• Genera informes de diferencias: El algoritmo de diferencias generará un informe de diferencias. En este informe, se mostrarán las diferencias entre ambos sistemas.
• Reconciliar las diferencias: Una vez que hayas generado el informe de diferencias, debes resolverlas. Esto puede implicar actualizar los datos en tu CMS o actualizar los datos del lado de Google Play con los extremos de administración de catálogos de la API para desarrolladores, según la forma en que normalmente actualices tu catálogo. Para conciliar los productos que no están sincronizados, usa los extremos de actualización como se describe en la sección Actualizaciones de productos.

Obsolescencia de productos

La API de Google Play Developer ofrece varios métodos para ayudar a los desarrolladores a dar de baja sus productos: inappproducts.delete y inappproducts.batchDelete para productos únicos y monetization.subscriptions.delete para suscripciones. Es posible que sea necesario dar de baja un producto en varias situaciones, como las siguientes:

• Creación por error.
• Cuando se descontinua una función o un servicio

Te recomendamos que incorpores la baja de productos a tu estrategia de administración de catálogos.

Productos únicos obsoletos

Para borrar productos únicos con la API de Google Play Developer, debes usar el método inappproducts.delete o inappproducts.batchDelete.

Productos de suscripción obsoletos

Puedes borrar suscripciones con el método monetization.subscriptions.delete. No se puede quitar una suscripción una vez que se activó al menos un plan básico.