Sumérgete en las App Store Server API para realizar compras dentro de la app

Hola, soy Riyaz, ingeniero del equipo del servidor del App Store. En esta sesión, hablaré de las API del servidor del App Store para compras dentro de la app. Mostraré cómo las últimas actualizaciones están diseñadas para simplificar y mejorar las responsabilidades del servidor de tu app. Veamos algunas de las responsabilidades clave del servidor de tu app. En esta sesión, me centraré en tres responsabilidades fundamentales.

Primero, administrar compras dentro de la app. Esta tarea implica asociar datos de transacciones con cuentas de clientes para que la app pueda brindar contenido y servicios sin problemas.

Segundo, firmar solicitudes. Esto requiere generar una firma para autorizar las solicitudes del servidor al App Store.

Tercero, participar en el proceso de decisión de reembolso. Al compartir datos de consumo relacionados con las compras, el servidor puede ayudar al App Store a tomar decisiones fundamentadas. Estas son algunas de las responsabilidades fundamentales que administra el servidor de tu app. Ahora, explicaré cómo las nuevas actualizaciones de la API del servidor del App Store mejorarán estas responsabilidades. Hay mucho de lo que hablar, así que comencemos. Primero, presentaré actualizaciones de los ID de transacciones que te ayudarán a administrar las compras dentro de la app. Luego, analizaré las mejoras para generar firmas y simplificar las solicitudes de firma en el servidor. Por último, mencionaré las mejoras que simplifican tu participación en los procesos de reembolso.

Comencemos con la administración de compras dentro de la app. La administración de compras dentro de la app comienza con el manejo eficaz de las cuentas de clientes en tu sistema.

Normalmente, asignarías un ID de cuenta único en el sistema a cada cliente para establecer un vínculo claro entre su cuenta y las transacciones del App Store. Esta asociación es crucial para ofrecer el contenido adecuado o personalizar la experiencia del usuario. El App Store proporciona datos de compras dentro de la app mediante tres estructuras de datos clave: AppTransaction, JWSTransaction y JWSRenewalInfo.

Primero, me centraré en JWSTransaction. Volveré a los otros tipos más adelante.

Cuando un cliente hace una compra dentro de la app, el App Store proporciona un objeto de transacción firmado. En el servidor, JWSTransaction representa esta transacción firmada, que puedes verificar y decodificar de forma efectiva con la biblioteca del servidor del App Store.

Este es un ejemplo de signedTransactionInfo decodificado.

Los primeros campos contienen información importante de la app y el tipo de producto dentro de la app. Luego, se muestran los metadatos sobre la compra, como la cantidad, el precio y la moneda. Si un cliente canjea una oferta, JWSTransaction incluye campos para offerType, offerIdentifier y offerDiscountType. Recientemente agregamos un nuevo campo offerPeriod, que indica la duración de la oferta canjeada usando el formato ISO 8601. También se incluye en JWSRenewalInfo para informar la duración de la oferta que se aplica a la hora de renovar la suscripción.

Luego, están los ID de transacciones. transactionId es un ID único para una transacción, como una compra dentro de la app, una restauración o una renovación de suscripción. En este ejemplo, representa el ID de transacción de la renovación de la suscripción.

originalTransactionId es el ID de transacción de la compra original. Te ayuda a identificar con precisión las suscripciones con renovación automática, ya que no varía con las renovaciones.

Por último, appAccountToken es un UUID que configuras en tu app usando StoreKit cuando un cliente hace una compra dentro de la app. Este campo te permite asociar la compra con la cuenta del cliente en el sistema. Para facilitar la obtención de appAccountToken para las renovaciones de suscripción, incluimos este campo en JWSRenewalInfo. Te ayudará a asociar sin problemas las cuentas de clientes con sus transacciones de renovación de suscripción más recientes. Ahora, explicaré cómo funciona. Primero, genera un UUID en tu servidor y asocia este valor con la cuenta de cliente. Luego, el servidor pasa este valor a tu app creada con StoreKit para configurar el appAccountToken en el momento de hacer la compra dentro de la app. Recomendamos usar el mismo valor appAccountToken para todas las compras dentro de la app realizadas por una cuenta de cliente determinada. El servidor del App Store devuelve el mismo valor appAccountToken en la información de transacción y renovación de JWS. Antes, podías configurar appAccountToken durante las compras que se hacían en la app. Pero los clientes también pueden hacer compras fuera de la app, como cuando canjean códigos de oferta o hacen compras promocionadas en el App Store. Para brindarte más flexibilidad para configurar appAccountToken, hay un nuevo punto final del servidor. Usa el punto final Set App Account Token para establecer un nuevo appAccountToken o actualizar uno existente para una transacción. Puedes usar este punto final para todos los tipos de producto. Esto incluye compras únicas anteriores, como consumibles, no consumibles y suscripciones no renovables, y la última compra de cada suscripción con renovación automática. En el caso de suscripciones con renovación automática, el appAccountToken que configures mediante este punto final se trasladará a futuras renovaciones, incluidos cambios por suscripciones superiores o inferiores.

El punto final Set App Account Token es útil cuando un cliente completa una transacción fuera de tu app, como canjear un código de oferta. Antes, no había forma de configurar el campo appAccountToken para este tipo de compras, ya que StoreKit no estaba involucrado. Además, puedes corregir inconsistencias en la asociación de appAccountToken con cuentas de clientes, como cuando cambia la propiedad de la cuenta en tu sistema. Ahora, te mostraré el punto final, que es parte de la API del servidor del App Store.

Este es un ejemplo de uso del punto final Set App Account Token. Indica el TransactionId original en la ruta. Este valor identifica la transacción de compra única o la suscripción para la que deseas configurar el appAccountToken.

En el cuerpo de la solicitud, establece un valor UUID para appAccountToken. El appAccountToken que proporciones con el punto final Set App Account Token anula cualquier appAccountToken anterior configurado para esa transacción. El appAccountToken, junto con otros ID de transacciones, como transactionId y originalTransactionId, brindan una forma de asociar las cuentas de clientes con las transacciones del App Store. Esta es una breve descripción de los ID. El App Store es la fuente de transactionId y originalTransactionId. Tú debes generar y asociar appAccountToken con una transacción del App Store. El transactionId es útil para identificar una compra específica. originalTransactionId es ideal para administrar el ciclo de vida de las suscripciones con renovación automática en un grupo de suscripciones y verificar el estado de la suscripción. El appAccountToken es útil para asociar la información de la cuenta de un cliente con su compra dentro de la app. Si tu app admite Compartir en Familia, appAccountToken no está disponible para transacciones compartidas en familia. transactionId y originalTransactionId están presentes en JWSTransaction y JWSRenewalInfo. El appAccountToken solo está disponible si lo configuras para una compra mediante StoreKit o el nuevo punto final Set App Account Token.

Cuando un cliente descarga tu app, el objeto AppTransaction está disponible a través de StoreKit y representa información importante sobre la descarga de la app. Como transactionId, originalTransactionId y appAccountToken son específicos de una compra dentro de la app, no se incluyen en el objeto AppTransaction. Pero a veces es importante identificar de forma única la descarga de una app, por ejemplo, para desbloquear contenido durante la instalación. Agregamos un nuevo campo llamado appTransactionId al objeto AppTransaction para ayudarte con este caso de uso. appTransactionId es un ID único global para cada cuenta de Apple por app. Para Compartir en Familia, cada familiar obtiene un appTransactionId único. Por diseño, appTransactionId es estático para una cuenta de Apple y una app determinadas, en caso de nuevas descargas, reembolsos, recompras o cambios en la tienda. El appTransactionId también se incluye con cualquier compra dentro de la app realizada por el cliente dentro de tu app. Esto te brinda mayor flexibilidad para asociar las cuentas de clientes a todas las transacciones del App Store. Ahora, explicaré cómo funciona. Esta es una forma de usar appTransactionId para asociar las cuentas de clientes con las transacciones del App Store. Primero, cuando un cliente descarga tu app, asocia la cuenta de cliente en tu sistema con el appTransactionId presente en el objeto AppTransaction. Para obtener el objeto AppTransaction en tu servidor, envía esta información desde la app. Cuando un cliente hace una compra dentro de la app, JWSTransaction y JWSRenewalInfo incluyen el mismo appTransactionId. De este modo, puedes asociarlo una vez y reutilizarlo en todos los objetos de transacción del App Store. Como appTransactionId está presente en todos los objetos de transacción del App Store, ofrece algunos casos de uso valiosos para tu app, como identificar si dos compras de suscripciones diferentes pertenecen a la misma cuenta de cliente. Por ejemplo, supongamos que tu app admite dos productos de suscripción: un boletín deportivo que se paga mensualmente y una suscripción anual de temporada para ver partidos en vivo. ¿Cómo puedo determinar si una cuenta de cliente tiene acceso a ambas suscripciones?

Si bien cada suscripción tiene un transactionId y un originalTransactionId diferentes, comparten el mismo appTransactionId. Puedes usar este campo para activar personalizaciones dentro de la app al inicio, como restaurar compras dentro de la app. Además, puedes usar appTransactionId como ID de transacción para los puntos finales de la API del servidor del App Store, como Get Transaction History, Get All Subscription Statuses y más. Hoy, hablaré de un nuevo punto final para obtener el objeto AppTransaction usando un punto final del servidor. Con el nuevo punto final Get App Transaction Info, por primera vez, puedes obtener información de descarga de la app directamente en el servidor, sin el dispositivo. Puedes usar el objeto AppTransaction para comprobar información importante de descarga de la app, como la versión de la app, la plataforma y el entorno. Con esto, puedes comprender cómo funciona tu app con los cambios del modelo de negocio. Este punto final no devuelve detalles relacionados con el dispositivo, como la verificación del dispositivo. Para estos fines, continúa usando el objeto AppTransaction que se obtuvo de tu app. Ahora, te mostraré el punto final, que es una parte de la API del servidor del App Store.

Este es un ejemplo de uso del punto final Get App Transaction Info. Puedes indicar cualquier ID de transacción, como originalTransactionId, transactionId o appTransactionId, en la ruta. La respuesta contiene signedAppTransactionInfo de JWS. Puedes usar la biblioteca del servidor del App Store para decodificar signedAppTransactionInfo. El punto final Get App Transaction Info estará disponible a finales de este año. Ahora, compararé appTransactionId con otros ID de transacciones que ya mostré. El App Store genera appTransactionId, al igual que transactionId y originalTransactionId.

Puedes usar appTransactionId para identificar de forma única las descargas de apps y asociar las compras posteriores del cliente con esa descarga. appTransactionId es consistente en todos los objetos de transacción del App Store. Puedes usar appTransactionId para transacciones compartidas en familia, si tu app admite Compartir en Familia. Usa appTransactionId, ya que brinda una solución de identificación integral para todas tus necesidades. Simplifica la administración de compras dentro de la app y su asociación con las cuentas de clientes en tu servidor. Ahora, veamos algunas mejoras clave que realizamos para firmar solicitudes. El primer paso es crear una cadena JWS, abreviatura de JSON Web Signature, en tu servidor. Luego, firma esta información usando una clave privada que descargas desde App Store Connect.

Envía esta cadena de firma a tu app creada con StoreKit para llamar a funciones que requieren una firma.

Luego, StoreKit envía la cadena firmada al servidor del App Store. Antes, en función del caso de uso, firmabas con diferentes formatos según lo requería el servidor del App Store. Ahora, unificamos las solicitudes de firma en todos los casos para usar el formato de firma JWS. Ahora puedes usar este formato en las llamadas de StoreKit que lo requieran, incluidas funciones como la generación de firmas de ofertas promocionales. Puedes firmar ofertas promocionales usando el formato de firma JWS. Este nuevo método de firma es una alternativa a la anterior firma de oferta promocional. Para brindar más flexibilidad, presentamos una nueva firma de ofertas para nuevos suscriptores de JWS. Esta función permite establecer una elegibilidad personalizada para dichas ofertas por transacción y usuario, y tener más control sobre la cantidad de ofertas que un cliente canjea con el App Store. También puedes enviar solicitudes JWS firmadas en la app con la API Advanced Commerce. Para saber más, consulta la documentación para desarrolladores. Ahora te mostraré cómo crear la firma de oferta promocional de JWS en tu servidor. Usa la firma de oferta promocional con StoreKit para retener a suscriptores existentes o inactivos en tu app. Este es un ejemplo de creación de una firma de oferta promocional usando la biblioteca del servidor del App Store. Uso Java para este ejemplo. Primero, ejemplifico la clase PromotionalOfferV2SignatureCreator con una clave privada, keyId, issuerId y bundleId para mi app. Puedes encontrar key, keyId y issuerId en App Store Connect.

Estos valores se usan para firmar, lo que evita que los clientes canjeen ofertas promocionales sin el consentimiento del desarrollador.

A continuación, especifico transactionId. Aquí, puedes proporcionar cualquier ID de transacción del cliente, incluido appTransactionId.

Proporciona transactionId, si quieres limitar la oferta a un cliente específico, si no, puedes omitir este campo.

Luego, proporciono un productId y un offerId. Preconfiguré la oferta representada por este ID en App Store Connect.

Por último, paso productId, offerId y transactionId a la función createSignature. La nueva firma es más simple que la versión anterior, ya que tiene menos entradas. Puedes simplificar las solicitudes de firma en varios casos de uso con el formato de firma unificado de JWS. Incluso después de publicar una oferta, a veces los clientes cancelan el servicio y solicitan un reembolso por cuestiones que están fuera de tu control, como un problema de facturación o una compra accidental. Para esos casos, te mostraré cómo participar en el proceso de decisión de reembolso. Primero, mencionaré algunos beneficios. Debes considerar participar en las decisiones de reembolso porque conoces el consumo de productos de los clientes. Por ejemplo, al ofrecer productos consumibles en tu app, administras los saldos de consumibles de los clientes en tu servidor. Esto puede ayudar a mejorar la satisfacción del cliente después de la solicitud de reembolso.

Cuando un cliente solicita un reembolso, el App Store envía una notificación CONSUMPTION_REQUEST a tu servidor. Para ayudar al proceso de toma de decisiones de reembolso, puedes responder a esta notificación usando el punto final Send Consumption Information.

Hay un nuevo y mejorado punto final Send Consumption Information V2.

En esencia, es más sencillo de integrar, ya que redujimos significativamente la cantidad de entradas en comparación con la versión anterior. También admite la preferencia de reembolso prorrateado para representar mejor el consumo parcial de un producto, cuando corresponda. Si bien la versión anterior solo admitía consumibles y suscripciones con renovación automática, ahora ampliamos la compatibilidad a todos los tipos de productos, incluidos los no consumibles y las suscripciones no renovables.

Si ya usaste el punto final V1, ten en cuenta que ahora está obsoleto, pero seguirá aceptando solicitudes. Si no lo usaste, te recomendamos utilizar el último punto final V2 con la biblioteca del servidor del App Store. Ahora te mostraré cómo usar el punto final Send Consumption Information V2. Supongamos que un cliente solicitó un reembolso por una compra consumible y se envió una notificación CONSUMPTION_REQUEST a tu servidor. Este es un ejemplo de cómo responder a la notificación con el punto final Send Consumption Information V2.

Indica el transactionId en la ruta que hay en la notificación CONSUMPTION_REQUEST.

El nuevo punto final admite un total de cinco campos de entrada, en comparación con los doce de la versión anterior. De los cinco campos de entrada, hay tres campos obligatorios y dos opcionales. Redujimos significativamente los campos para simplificar tu participación en las decisiones de reembolso. Establece el campo customerConsented en verdadero si el cliente dio su consentimiento para enviar al App Store los datos relacionados con su solicitud de reembolso, incluidos todos los que proporciones en el cuerpo ConsumptionRequestV2. Si el cliente no dio su consentimiento, no respondas a la notificación CONSUMPTION_REQUEST. Si se llama al punto final con el campo establecido como falso, se rechaza la solicitud. Usa sampleContentProvided para indicar si proporcionaste un contenido de muestra antes de que se comprara el producto. Usa DELIVERED como deliveryStatus si entregaste correctamente el contenido al cliente. De lo contrario, usa un estado UNDELIVERED apropiado.

Opcionalmente, puedes indicar tu preferencia para el reembolso. Ahora puedes indicar una preferencia de reembolso prorrateado usando el valor GRANT_PRORATED, además del reembolso total o ningún reembolso ya admitido. Si no quieres indicar una preferencia, no configures este campo. consumptionPercentage indica el consumo del producto en milipercent.

Aquí, un valor de 25,000 representa el 25% del consumo del producto consumible. El punto final Send Consumption Information V2 estará disponible a finales de este año. Ahora, analicemos la nueva opción de reembolso prorrateado proporcionada por el último punto final V2. Considera indicar una preferencia de reembolso prorrateado cuando el cliente puede consumir parcialmente el producto.

La preferencia de reembolso prorrateado permite especificar el consumo, lo que ayuda al App Store a otorgar un monto de reembolso adecuado.

Debes especificar consumptionPercentage cuando indiques una preferencia para los tipos de productos de suscripción consumibles, no consumibles y no renovables. Esto es para que el App Store pueda otorgar con precisión el reembolso apropiado. Ten en cuenta que el App Store calcula el consumptionPercentage de suscripciones con renovación automática, usando el tiempo restante de la suscripción. Los datos de consumo que envíes ayudan al App Store a decidir si otorgar un reembolso completo, prorratear el reembolso o rechazarlo por completo. Se te informará la decisión mediante una notificación REFUND o REFUND_DECLINED. Si recibes una notificación REFUND_DECLINED, no debes hacer nada. Sin embargo, debes tomar las medidas pertinentes cuando recibas una notificación REFUND. Este es un ejemplo de una notificación REFUND. Ahora puedes saber cuánto del reembolso te otorgó el App Store usando el nuevo campo refundPercentage. En este caso, se otorgó un reembolso del 75% para que puedas tomar las medidas pertinentes respecto del producto consumido.

Al usar este campo, recuerda que App Store Connect es tu fuente de información veraz para fines contables y financieros. También puedes comprender el tipo de revocación usando el nuevo campo revocationType. Este campo podría ser REFUND_FULL, REFUND_PRORATED o FAMILY_REVOKE. Como se trata de un reembolso consumible, los posibles valores son REFUND_FULL y REFUND_PRORATED. En caso de un reembolso completo o revocación familiar, revocas inmediatamente el acceso al contenido en tu servidor. Para REFUND_PRORATED, revoca el porcentaje reembolsado del contenido. Ahora te mostraré cómo manejar una notificación de reembolso con reembolso prorrateado en tu servidor. En el caso de un producto de suscripción consumible, no consumible o no renovable, usa el campo refundPercentage para calcular y revocar la cantidad proporcional de contenido de la cuenta del cliente. Por ejemplo, si el cliente compró una moneda virtual, es posible que quieras reducir su saldo en el monto reembolsado. Para las suscripciones con renovación automática, gestiona los reembolsos prorrateados de la misma forma que gestionas los completos. Verifica el estado actual de la suscripción y toma las medidas pertinentes. Espero que uses el nuevo punto final Send Consumption Information V2 para participar en el proceso de decisión de reembolso, ya que ahora es más fácil y eficaz. ¡Hablamos de mucho hoy! Hagamos un breve resumen. Te mostré varios ID de transacciones y presenté appTransactionId como un ID de transacción único. Luego, exploré el formato unificado de firma de JWS. Por último, te mostré lo fácil que es participar en las decisiones de reembolso. Antes de terminar, mencionaré algunos pasos útiles a seguir. Si ya contribuiste a la biblioteca del servidor del App Store de código abierto, ¡gracias! De lo contrario, visita nuestra página de GitHub para saber cómo contribuir y apoyar a la comunidad del App Store. A medida que incorporemos nuevas funciones, queremos conocer tu opinión. Envía solicitudes de funciones y comentarios al equipo del servidor del App Store con Feedback Assistant. Para saber más sobre las actualizaciones que hicimos en StoreKit, consulta la sesión “What's new in StoreKit and In-App Purchase” de la WWDC25. Además, consulta la sesión “Explore App Store server APIs for In-App Purchase” de la WWDC24 para saber más sobre el servidor del App Store. Gracias por participar hoy, ¡nos vemos la próxima!