Conheça as APIs App Store Server para compras dentro do app

Olá! Eu sou Riyaz. Sou engineer da equipe App Store Server. Vamos explorar as App Store Server APIs para compras dentro do app. Vou mostrar como as novidades ajudam a otimizar as responsabilidades do servidor do seu app. Começaremos analisando algumas responsabilidades cruciais do seu servidor. Nesta sessão, o foco serão três funções principais.

Primeiro, a gestão das compras dentro do app. Isso inclui associar transações às contas dos clientes para entregar conteúdo e serviços no seu app.

Depois, os pedidos de assinatura. Isso exige gerar uma assinatura para autorizar os pedidos do seu servidor à App Store.

Por fim, a participação no processo de decisões de reembolso. Ao compartilhar dados de uso das compras, seu servidor colabora nas decisões de reembolso da App Store. Essas são algumas das responsabilidades cruciais do servidor do app. Agora, vou mostrar como as novidades das App Store Server APIs otimizam essas responsabilidades. Temos muito o que falar, então vamos começar. Primeiro, vou apresentar as novidades nos identificadores de transação que melhoram a gestão de compras dentro do app. Depois, falaremos das melhorias na geração de assinaturas para simplificar pedidos ao servidor. Por fim, abordaremos os avanços que facilitam sua participação nos processos de reembolso.

Vamos analisar os detalhes, começando pela gestão das compras dentro do app. A gestão de compras dentro do app começa pelo tratamento correto das contas dos clientes no sistema.

Geralmente, você atribui um ID exclusivo para cada cliente no sistema, vinculando a conta às transações da App Store. Essa relação é essencial para entregar o conteúdo certo ou personalizar a experiência. A App Store fornece dados das compras dentro do app em três estruturas-chave: AppTransaction, JWSTransaction e JWSRenewalInfo.

Primeiro, vou me concentrar na JWSTransaction. Depois volto aos outros tipos.

Quando um cliente faz uma compra dentro do app, a App Store envia um objeto de transação assinado. No servidor, a JWSTransaction é essa transação, que pode ser verificada e decodificada pela App Store Server Library.

Aqui está um exemplo da signedTransactionInfo decodificada.

Os primeiros campos mostram dados importantes do app e tipo do produto no app. Depois falaremos dos metadados da compra, como quantidade, preço e moeda. Se houver uma oferta, a JWSTransaction inclui campos como offerType, offerIdentifier e offerDiscountType. Adicionamos o campo offerPeriod, que indica a duração da oferta no formato ISO 8601. Esse campo também aparece no JWSRenewalInfo, mostrando a duração da oferta na renovação da assinatura.

Depois, há os identificadores de transação. O transactionId é o ID exclusivo de uma transação, como compra dentro do app, restauração ou renovação da assinatura. No exemplo, ele representa o ID da transação da renovação de uma assinatura.

O originalTransactionId é o ID da compra original. Ele ajuda a identificar assinaturas de renovação automática, já que não muda nas renovações de assinatura.

Por fim, o appAccountToken, um UUID gerado no seu app via StoreKit ao fazer uma compra dentro do app. Esse campo liga a compra à conta do cliente no seu sistema. Agora o appAccountToken para renovações de assinatura está na JWSRenewalInfo. Assim, você associa facilmente as contas às últimas renovações de assinatura. Explico como isso funciona a seguir. Primeiro, gere um UUID no servidor e associe o valor à conta do cliente. Depois, passe esse valor ao app com o StoreKit. para definir o appAccountToken no momento da compra dentro do app. Recomendamos usar o mesmo valor do appAccountToken em todas as compras da conta de um cliente. O App Store Server retorna esse valor nas informações de transações e renovações da JWS. Antes, só era possível definir o appAccountToken em compras feitas no app. Mas clientes também compram fora do app, como ao resgatar códigos de oferta ou comprar itens promovidos na App Store. Para mais flexibilidade ao definir o appAccountToken nesses casos, temos um novo endpoint no servidor. Use o endpoint Set App Account Token para definir ou atualizar um appAccountToken em uma transação.

Você pode usar esse endpoint para todos os tipos de produtos. Isso inclui compras únicas, consumíveis, não consumíveis, assinaturas não renováveis e última compra de assinaturas de renovação automática. Para assinaturas de renovação automática, o appAccountToken definido nesse endpoint valerá para futuras renovações e upgrades.

O endpoint Set App Account Token é útil quando a compra ocorre fora do app, como ao resgatar um código de oferta. Antes, não era possível definir o campo appAccountToken em compras desse tipo, já que o StoreKit não estava envolvido. Além disso, você pode corrigir inconsistências ao associar o appAccountToken a contas de clientes, como quando a propriedade da conta muda no seu sistema. Veja agora como funciona esse endpoint, parte da App Store Server API.

Veja um exemplo de como usar o endpoint Set App Account Token. Forneça o TransactionId original no caminho. Esse valor identifica a compra única ou a assinatura que gostaria de vincular ao appAccountToken.

No corpo do pedido, defina o UUID desejado para o appAccountToken. O novo appAccountToken sobrescreve o valor do endpoint Set App Account Token anterior da transação. O appAccountToken, junto aos identificadores como transactionId e originalTransactionId, permitem associar contas de clientes a transações da App Store. Aqui está um resumo dos identificadores. A App Store fornece o transactionId e o originalTransactionId, e é você quem cria e associa o appAccountToken à transação da App Store. O transactionId identifica um evento de compra específico. O originalTransactionId ajuda a gerenciar o life cycle de assinaturas e status de renovação automática em um único grupo de assinaturas e para verificar o status delas. O appAccountToken é útil para associar as informações da conta de um cliente à compra dentro do app. Se o app for compatível com o Compartilhamento Familiar, o appAccountToken será usado nas transações compartilhadas. O transactionId e o originalTransactionId são incluídos no JWSTransaction e JWSRenewalInfo. O appAccountToken só estará disponível se você defini-lo em uma compra usando o StoreKit ou o novo endpoint Set App Account Token.

Quando um cliente baixa seu app, o AppTransaction fica disponível pelo StoreKit e mostra dados importantes sobre esse download. Como o transactionId, o originalTransactionId e o appAccountToken são específicos da compra dentro do app, não aparecem no objeto AppTransaction. Mas, às vezes, é preciso identificar o download do app, como para desbloquear conteúdo na instalação do app. Para ajudar no seu caso de uso, adicionamos o campo appTransactionId ao objeto AppTransaction. O appTransactionId é um identificador global exclusivo para cada Conta Apple e por app. Para o Compartilhamento Familiar, cada membro da família recebe um appTransactionId exclusivo. O appTransactionId é estático para cada app e Conta Apple, mesmo em reinstalações, reembolsos, novas compras ou mudanças no ambiente. O appTransactionId também é incluído em todas as compras dentro do app feitas pelo cliente no seu app. Isso amplia as possibilidades de assumir controle sobre todas as transações da App Store. Aqui explico como isso funciona. Veja como usar o appTransactionId para associar as contas dos clientes às transações da App Store. Quando o cliente baixar o app, associe a conta dele incluída no seu sistema ao appTransactionId no objeto AppTransaction. Uma maneira de obter o objeto AppTransaction no seu servidor é enviando essas informações do seu app. Quando um cliente faz uma compra dentro do app, o JWSTransaction e o JWSRenewalInfo usam o mesmo appTransactionId. Ou seja, basta associar uma vez e reutilizar em todos os objetos das transações. Como o appTransactionId está em todas as transações da App Store, é possível aplicar casos de uso valiosos, como identificar se compras de duas assinaturas diferentes pertencem à mesma conta de cliente. Por exemplo, se o seu app tem duas assinaturas: um boletim esportivo mensal e uma assinatura anual de jogos ao vivo. Como saber se a conta tem acesso às duas assinaturas?

Mesmo se a assinatura tiver um transactionId e um originalTransactionId diferentes, o appTransactionId é o mesmo. Você pode usar esse campo para ativar personalizações ao abrir o app, como restaurar compras dentro do app. Além disso, use o appTransactionId como o ID da transação nos endpoints populares da App Store Server API, como Get Transaction History, Get All Subscription Statuses, etc. Agora, temos um novo endpoint para obter o objeto AppTransaction usando o endpoint do servidor. Com o novo endpoint Get App Transaction Info, é possível buscar informações de download direto no servidor, sem depender do dispositivo. O objeto AppTransaction inclui dados importantes do download, como versão, plataforma e ambiente do app. Com isso, você entende melhor os impactos dos modelos de negócio no desempenho do app. Lembre-se, esse endpoint não retorna dados do dispositivo, como verificação. Para isso, continue usando o objeto AppTransaction obtido do seu app. Agora vou mostrar o endpoint, parte da App Store Server API.

Aqui está um exemplo do uso do endpoint Get App Transaction Info. Você pode usar qualquer identificador, como originalTransactionId, transactionId ou appTransactionId no caminho. A resposta traz o JWS signedAppTransactionInfo. Você pode usar a App Store Server Library para decodificar o signedAppTransactionInfo. O endpoint Get App Transaction Info ficará disponível ainda este ano. Agora vou comparar o appTransactionId com outros identificadores mostrados antes. A App Store gera o appTransactionId, assim como o transactionId e originalTransactionId.

O appTransactionId serve para identificar downloads de app e vincular compras subsequentes ao download. O appTransactionId é consistente em todos os objetos de transação da App Store. Se o seu app usa o Compartilhamento Familiar, use o appTransactionId para transações de familiares. Recomendamos usar o appTransactionId como identificador único para todas as necessidades. Isso facilita a gestão de compras dentro do app e as associações com as contas do cliente no servidor. Agora, vamos conferir melhorias importantes para assinatura de solicitações. O primeiro passo é criar uma string JWS, ou JSON Web Signature, no servidor. Depois, assine essas informações usando uma chave privada baixada do App Store Connect.

Em seguida, envie a string assinada para seu app com o StoreKit para chamar funções que exigem assinatura.

O StoreKit envia a assinatura para o App Store Server. Antes, o formato da assinatura dependia do cenário e da exigência do App Store Server. Agora, o formato JWS foi padronizado para todos os usos de assinatura. Assim, você pode usar esse formato em chamadas StoreKit que exigem assinatura, como ofertas promocionais. Agora, você pode assinar ofertas promocionais usando o formato JWS. Esse novo método é uma opção além da assinatura promocional anterior. Para dar mais flexibilidade em preços introdutórios, criamos uma nova assinatura JWS de preço introdutório. Esse recurso permite definir a elegibilidade personalizada por transação e usuário para ofertas introdutórias, controlando o número de ofertas para cada cliente que resgata na App Store. Você também pode enviar o JWS assinado em requisições in-app com a Advanced Commerce API. Para saber mais, consulte nossa documentação do Developer. Vou mostrar como criar a assinatura JWS de oferta promocional no servidor. Use a assinatura de oferta promocional com o StoreKit para reter assinantes ativos ou inativos em seu app. Veja o exemplo de criação de assinatura de oferta promocional com a App Store Server Library. Aqui, estou usando Java no exemplo. Primeiro, crio a PromotionalOfferV2SignatureCreator, informando private key, keyId, issuerId e bundleId. Você encontra key, keyId e issuerId no App Store Connect.

Esses valores são usados para assinar, impedindo que clientes resgatem ofertas sem consentimento do desenvolvedor.

Depois, informo o transactionId. Você pode usar qualquer identificador do cliente, inclusive o appTransactionId.

Use o transactionId para limitar a oferta a um cliente ou deixe o campo em branco.

Em seguida, informo productId e offerId. A oferta com esse ID foi configurada no App Store Connect.

Por fim, passo o productId, o offerId e o transactionId para a função createSignature. Note que a nova assinatura é mais simples, com menos entradas que antes. Você pode simplificar assinaturas em diferentes casos usando o formato de assinatura padrão JWS. Mesmo após oferecer uma oferta, clientes podem desistir e pedir reembolso por fatores fora do seu controle, como problemas de faturamento ou uma compra acidental. Agora, vou explicar como participar do processo de decisão de reembolso. Primeiro, vou falar sobre os benefícios. Vale a pena participar porque você conhece os hábitos de consumo dos seus clientes. Por exemplo, ao gerenciar produtos consumíveis, seu servidor já controla o saldo consumido. Isso contribui na satisfação do cliente quando há pedido de reembolso.

Quando um reembolso é pedido, a App Store envia uma notificação CONSUMPTION_REQUEST ao seu servidor. Para ajudar na decisão do reembolso, responda usando o endpoint Send Consumption Information.

É um prazer anunciar nosso novo e aprimorado Send Consumption Information V2.

Basicamente, o novo endpoint é mais simples de integrar, com menos campos obrigatórios que a versão anterior. Agora ele também suporta preferência de reembolso proporcional para representar o consumo parcial. Antes, só havia consumíveis e as assinaturas de renovação automática, agora ele cobre todos os produtos, incluindo não consumíveis e assinaturas não renováveis.

Se você usava a versão 1, saiba que ela foi descontinuada, mas ainda aceita requisições. Se nunca usou o endpoint Send Consumption Information, recomendamos começar pela V2 com a App Store Server Library. Agora, vou mostrar como usar o endpoint Send Consumption Information V2. Imagine que um cliente pediu reembolso de um consumível, e uma notificação CONSUMPTION_REQUEST foi enviada ao seu servidor. Veja como responder com o endpoint Send Consumption Information V2.

Informe o transactionId encontrado na notificação CONSUMPTION_REQUEST no caminho do endpoint.

O novo endpoint aceita cinco campos de entrada, contra doze na versão anterior. Desses cinco, três são obrigatórios e dois opcionais. Reduzimos os campos para facilitar a participação no processo de reembolso. Marque o customerConsented como "true" se o cliente autorizou o envio dos dados do consumo no pedido de reembolso para a App Store, incluindo os dados fornecidos no ConsumptionRequestV2. Se não houver consentimento, não responda à notificação CONSUMPTION_REQUEST. Se o campo for "false", o pedido será rejeitado. Use o sampleContentProvided para informar se algum conteúdo de amostra foi entregue antes da compra. Defina DELIVERED se o conteúdo foi entregue ao cliente. Em caso negativo, use o status UNDELIVERED adequado.

Você pode informar sua preferência de reembolso. Agora, é possível sugerir reembolso proporcional com GRANT_PRORATED, além de reembolso total ou nenhum valor. Se não quiser informar sua preferência, deixe esse campo em branco. O consumptionPercentage indica quanto do produto foi consumido, em milésimos.

Por exemplo, 25.000 representa 25% do consumo. O endpoint V2 deve ser disponibilizado até o fim do ano. Vamos falar da opção de reembolso proporcional do novo endpoint V2. Considere sugerir reembolso proporcional se o cliente consumiu parte do produto.

Informando o consumo, a App Store concede o valor apropriado de reembolso.

É preciso informar a consumptionPercentage ao indicar um reembolso proporcional para consumíveis, não consumíveis e assinaturas não renováveis. Assim, a App Store calcula corretamente o valor do reembolso. Para assinaturas de renovação automática, a App Store calcula o consumptionPercentage automaticamente pelo tempo restante. Os dados de consumo enviados ajudam a App Store a decidir conceder um reembolso total, ratear o reembolso ou recusá-lo completamente. Você é notificado da decisão por meio de uma notificação REFUND ou REFUND_DECLINED. Se receber REFUND_DECLINED, nenhuma ação é necessária. No entanto, você é responsável por agir ao receber uma notificação REFUND. Veja um exemplo de notificação REFUND. Agora, você pode conferir o valor do reembolso concedido pela App Store com o novo campo refundPercentage. Neste caso, 75% do valor foi reembolsado, assim você pode tomar as medidas para o produto consumido.

Lembre-se sempre de usar o App Store Connect como referência para fins financeiros. Você também pode verificar o tipo de revogação com o campo revocationType. Os valores possíveis: REFUNDFULL, REFUNDPRORATED ou FAMILY_REVOKE. Como é um reembolso de consumível, os valores são REFUNDFULL e REFUNDPRORATED. No reembolso total ou revogação familiar, revogue o acesso ao conteúdo imediatamente. Para REFUND_PRORATED, revogue a porcentagem reembolsada do conteúdo. Agora, veja como lidar com notificações de reembolso proporcional no servidor. Para consumíveis, não consumíveis ou assinaturas não renováveis, use o refundPercentage para calcular e revogar a parte proporcional do conteúdo. Por exemplo, se o cliente comprou moeda virtual, diminua o saldo com base no reembolso. Para assinaturas de renovação automática, trate o reembolso proporcional como um reembolso total. Verifique o status e tome a ação adequada. Espero que aproveite o novo endpoint V2 para facilitar sua ação em decisões de reembolso. Hoje vimos muita coisa! Vamos recapitular. Expliquei os diferentes identificadores de transação e apresentei o appTransactionId como identificador central. Depois, apresentei o padrão único do formato de assinatura JWS. Por fim, mostrei como participar facilmente dos processos de reembolso. Agora, algumas dicas finais. Se você já contribuiu com a App Store Server Library de código aberto, obrigado! Caso contrário, acesse nosso GitHub, veja como contribuir e apoiar a comunidade da App Store. Com novidades chegando, queremos ouvir você. Envie sugestões para a equipe do App Store Server pelo Feedback Assistant. Para saber mais sobre as atualizações do StoreKit, confira a sessão "Novidades do StoreKit e das compras dentro do app" da WWDC25. E confira também a sessão "Explorar as APIs do servidor da App Store para compras dentro do app" da WWDC24. Agradeço sua participação. Até a próxima!