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.

Si quieres vender productos en tu app a través del sistema de Facturación Google Play, debes configurar un catálogo con todos los productos que quieras que estén disponibles para que los usuarios los compren. Esto se puede hacer a través de Play Console, o puedes automatizar la administración de catálogos con la API de Google Play Developer. La automatización puede ayudar 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, aprenderás a usar la API de Play Developer para crear y administrar un catálogo de productos para tu app de Play. Consulta nuestra guía de Preparación para obtener instrucciones sobre cómo configurar la API de Google Play Developer para la integración de backend.

APIs de Catalog Management

Para leer sobre los diferentes tipos de productos que puedes vender con el sistema de Facturación Google Play, lee Información sobre los tipos de productos integrados en la aplicación y las consideraciones del 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 principales de productos:

  • 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, y administrar precios y disponibilidad. Según cómo administres las compras de productos únicos, modelarás productos consumibles (se pueden comprar las veces que desees) o derechos permanentes (el mismo usuario no puede realizarlos dos veces). Puedes decidir qué productos únicos se pueden consumir o no.

Productos de suscripción

El extremo monetization.subscriptions te ayuda a administrar los productos de suscripción desde tu backend de desarrollador. Por ejemplo, puedes crear, actualizar y borrar suscripciones, o 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 varios métodos por lotes que permiten recuperar o administrar hasta 100 entidades en la misma app, al mismo tiempo.

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

Actualiza la latencia de propagación en comparación con la capacidad de procesamiento

Después de que se completa una solicitud de creación o modificación de un producto, es posible que los cambios no sean visibles de inmediato para los usuarios finales en sus dispositivos debido a retrasos 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, por lo general, se reflejan en los dispositivos del usuario final en cuestión de minutos. Sin embargo, existe un límite por hora para la cantidad de solicitudes de modificación. Para los casos en los 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 las actualizaciones. Las actualizaciones tolerantes a la latencia tardarán hasta 24 horas en propagarse a los dispositivos del usuario final.

Configuración de la cuota

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 de 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 las suscripciones y los productos únicos, y para todas las solicitudes de modificación, incluidas las de creación, actualización, activación y eliminación. Las llamadas a métodos de modificación por lotes cuentan como una consulta para esta cuota, sin importar 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. Para los métodos por lotes, cada solicitud de modificación anidada se cuenta por separado para los fines 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 agota 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 la cuota 2 y 3 (ya que solo se refiere a los extremos de modificación).
  • Una solicitud get por lotes para recuperar hasta 100 artículos también consumirá 1 token de la cuota 1 y ningún token de la cuota 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 la 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 usan métodos de modificación únicos.
  • Una solicitud modification por lotes para 100 elementos tolerantes a la latencia consumirá 1 token de la cuota 1 y 1 token de la cuota 2. La configuración de la cuota debería permitirte tener un margen amplio para mantener actualizado tu catálogo. Sin embargo, si tu algoritmo no está al tanto de esta cuota y excede esta frecuencia, es posible que recibas un error por cada llamada adicional.
  • Una solicitud modification por lotes 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, podrás optimizar tus interacciones con la API y garantizar una experiencia de administración de catálogos fluida y eficiente.

Supervisa el 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, y esto podría afectar el uso en 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 la cuota para asegurarte de no exceder las cuotas de la API. Hay varias formas de supervisar el uso. Por ejemplo, puedes usar el panel de cuotas de las API de Google Cloud o cualquier otra herramienta de supervisión de API interna o de terceros que elijas.

Optimiza el uso de la cuota de la API

Optimizar el consumo de frecuencia es muy recomendable para minimizar la probabilidad de errores de API. Para implementar esto de manera eficaz, te recomendamos lo siguiente:

  • Elige la estrategia de administración de catálogos adecuada. Una vez que comprendas la cuota de API, debes elegir la estrategia correcta para que tu aplicación logre tus objetivos de administración de catálogos de forma eficiente.
  • Solo realice la cantidad mínima de llamadas que necesite 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 por hora de modificación de productos de 7,200 consultas. Es posible que desees compilar procesos de sincronización que requieran que realices una gran cantidad de modificaciones de productos en un período corto (por ejemplo, una creación inicial de catálogo). Si esperas que estos procesos superen el límite por hora, implementa esperas según sea necesario para ralentizar 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 verticalmente el uso de la API y los diversos extremos. Consulta la documentación de cuotas de la API de Google Play Developer para obtener detalles sobre cómo aumentar la cuota cuando te acerques al máximo de uso.
  • Programa procesos pesados estratégicamente. Intenta programar los procesos pesados de catálogo en torno a los picos de uso críticos. Por ejemplo, puedes evitar ejecutar una sincronización completa del catálogo durante los momentos de mayor cantidad de ventas de la semana.

Agrega lógica de manejo de errores de cuota

Sin importar qué tan eficientemente compiles tu lógica de administración de catálogos, debes hacer que sea resistente a los límites de cuota inesperados, ya que los extremos que se usan en módulos independientes de tu integración comparten la cuota diaria. Asegúrate de incluir errores de limitación de cuota en tu manejo de errores y de implementar las esperas adecuadas. Cada llamada realizada a las APIs de Google Play Developer generará una respuesta. Si se falla una llamada, recibirás una respuesta de falla que incluye un código de estado de respuesta HTTP y un objeto errors, que proporciona más detalles sobre el dominio del error y un mensaje de depuración. Por ejemplo, si superas tu límite diario, es posible que recibas 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. Asegurarse de que tu catálogo de Google Play esté siempre 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 la lógica de la presentación de ofertas.
  • Puedes verificar los diferentes precios y detalles del producto que los usuarios ven en todas las plataformas y asegurarte de que sean coherentes.
  • Tendrás los detalles del producto a mano en tu backend cuando proceses compras nuevas, sin necesidad de aumentar la latencia ni el riesgo de falla realizando llamadas adicionales a la API de Google Play Developer durante los flujos críticos para el 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 estructurar tu catálogo, deberás decidir cuál será 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 las que envías una batería 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 prácticos que otros, y es posible que tengas un conjunto de necesidades que requieran ambos, según la situación. A veces, es posible que quieras actualizar un producto en el momento en que te enteras de un cambio nuevo; por ejemplo, para procesar una actualización urgente de un producto (es decir, se debe corregir un precio incorrecto lo antes posible). En otras ocasiones, puedes usar una sincronización periódica en segundo plano para asegurarte de que tus catálogos de backend y Play sean siempre coherentes. Lee algunos casos de uso comunes en los que es posible que desees 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 se realicen cambios en el catálogo de productos de tu backend para minimizar las discrepancias.

Este tipo de actualizaciones es una buena opción en las siguientes situaciones:

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

Este enfoque es más sencillo de implementar y te permite mantener tu catálogo sincronizado con la ventana de discrepancia mínima.

Cuándo usar actualizaciones periódicas

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

  • No es necesario que te asegures de que tus productos se actualicen con un breve aviso.
  • Debes planificar actualizaciones masivas o procesos de conciliación.
  • Ya tienes un sistema de administración de contenido o catálogos para administrar 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 alcanzar la capacidad de procesamiento máxima.

Crea tu catálogo de productos

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

Cómo crear productos únicos

Para la creación inicial de un catálogo grande de productos únicos, te recomendamos que uses el método inappproducts.batchUpdate con el campo allowMissing establecido en true y el campo latencyTolerance establecido en PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Esto minimizará el tiempo que lleva 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. También 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 eliminar la necesidad de que la secuencia de comandos tenga estado y pueda reiniciarse desde cero en caso de que se produzca algún error.

Crea productos de suscripción

Para la creación inicial de un catálogo grande de suscripciones, 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. Esto minimizará el tiempo que lleva crear el catálogo dentro de los límites de cuota.

En el caso de los catálogos de suscripción más pequeños, la API de Play Developer proporciona el método monetization.subscriptions.create. También puedes crear suscripciones usando el método monetization.subscriptions.update 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). Al principio, estos planes básicos están inactivos. 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 a fin de 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 de manera eficiente tus productos existentes para garantizar que tus ofertas se alineen con los ajustes más recientes.

Cómo actualizar productos únicos

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

  • inappproducts.patch: El extremo de parche se usa para actualizar un recurso de forma parcial. Esto significa que puedes actualizar los 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 en su totalidad. Esto significa que deberás enviar el objeto de recurso completo 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 configurado como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para lograr una mayor capacidad de procesamiento.

Actualiza los productos de suscripción

Para actualizar suscripciones existentes, puedes usar el método monetization.subscriptions.patch. Este método incluye 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 único del producto de la suscripción.
  • regionsVersion: Es la versión de configuración de la región.

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

Por ejemplo, si solo deseas 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 configurado en PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para lograr una mayor capacidad de procesamiento.

Para activar, desactivar o borrar planes básicos, o migrar suscriptores a las versiones más recientes de precios del plan básico, 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 tu catálogo de Google Play cada vez que el catálogo de tu backend cambie 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é sincronizada con el catálogo en la configuración de tus apps en Play. Esto podría deberse a cambios manuales de emergencia en el catálogo en la consola, una interrupción en el sistema de administración de catálogos o tal vez si perdiste los datos más recientes.

Puedes compilar un proceso de conciliación del catálogo para evitar una ventana de discrepancia prolongada.

Consideración del sistema de diferencias

Recomendamos compilar un sistema de diferencias para detectar incoherencias y conciliar los dos sistemas. Estos son algunos aspectos que debes tener en cuenta cuando compilas 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 para desarrolladores y de 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 diferencias: Una vez que comprendas los modelos de datos, deberás definir las reglas de diferencias. Estas reglas determinarán cómo se comparan los datos de los dos sistemas. Por ejemplo, es posible que quieras hacer coincidir los IDs del producto y comparar atributos clave de la suscripción y sus planes básicos y ofertas asociados.
  • Implementa un algoritmo de diferencias:Una vez que hayas definido las reglas de diferencias, debes implementar el algoritmo correspondiente. 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.
  • Concilia diferencias: Una vez que hayas generado el informe de diferencias, debes resolverlas. Esto puede implicar la actualización de los datos en tu CMS o la actualización de los datos en Google Play mediante los extremos de administración de catálogos de la API para desarrolladores, según cómo sueles actualizar tu catálogo. Para conciliar productos no sincronizados, usa los extremos de actualización como se describe en la sección Actualizaciones de productos.

Baja del producto

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. Puede ser necesario dar de baja un producto en varias situaciones, como las siguientes:

  • Se creó por error.
  • Descontinuación de una función o un servicio

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

Baja de productos únicos

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

Baja de productos de suscripción

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.