KappS Base de conhecimento · Blog

App Store Links de compra externa em 2026

Blog Tutorial

A Diretriz 3.1.1 da App Review ainda exige que bens e serviços digitais vendidos dentro de um app App Store usem compra dentro do app — mas a lista de exceções cresceu de novo, e em 2026 há três formas diferentes de um app em conformidade enviar o cliente a uma página de pagamento própria. O texto atual da diretriz 3.1.1(a) diz claramente: os desenvolvedores podem solicitar entitlements para oferecer um link no app para um site que possuam ou pelo qual sejam responsáveis, e — a frase que mais importa para publicadores dos EUA — "Esses entitlements não são exigidos para que os desenvolvedores incluam botões, links externos ou outras chamadas para ação em seus apps na vitrine dos Estados Unidos." Em todas as outras vitrines, a mesma diretriz diz que os apps e seus metadados não podem incluir botões, links externos ou outras chamadas para ação que direcionem clientes a mecanismos de compra diferentes da compra dentro do app.

A versão em uma linha: a vitrine dos Estados Unidos não precisa de nenhum entitlement; o entitlement com.apple.developer.storekit.external-purchase-link cobre as vitrines iOS/iPadOS onde a Apple permite um link externo; e o novo entitlement de link de compra personalizado tem escopo regional, com Brasil e Japão entrando nos códigos de país da UE. ExternalPurchaseLink informa em tempo de execução se algo disso se aplica, eligibleURLs e open(url:) de fato abrem o link, e todo token retornado precisa ser reportado pela External Purchase Server API.

Etapa 1 — Descubra em qual das três rotas seu app está

A rota um é a vitrine dos EUA: os links externos são permitidos sem uma entitlement, e a diretriz diz isso explicitamente. A rota dois é com.apple.developer.storekit.external-purchase-link, também conhecida como entitlement StoreKit External Purchase Link — o próprio resumo da Apple é que ela "permite que apps elegíveis incluam um link que direciona quem usa o app a um site para fazer uma compra externa", e o contrato da entitlement limita esse link a informar as pessoas onde e como comprar itens dentro do app, incluindo o fato de que eles podem estar disponíveis por um preço comparativamente menor. A rota três é com.apple.developer.storekit.custom-purchase-link.allowed-regions: uma entitlement que "permite que um app elegível ofereça compras externas dentro do app ou em um site, em regiões específicas", e cujo valor não é um booleano, mas um array de códigos ISO-3166-1 de duas letras. Conforme documentado, as regiões permitidas para o link de compra personalizado incluem Brasil (br), Japão (jp) e os códigos dos países da UE — Áustria, Bélgica, Bulgária, Croácia, Chipre, Tchéquia, Dinamarca, Estônia, Finlândia, França, Alemanha, Grécia, Hungria, Irlanda, Itália, Letônia, Lituânia, Luxemburgo, Malta, Países Baixos, Polônia, Portugal, Romênia, Eslováquia, Eslovênia, Espanha e Suécia.

Antes de escrever qualquer código, liste as lojas em que você realmente publica. Um único link global que ignora o limite da loja é a forma mais comum de esse recurso virar uma rejeição.

Etapa 2 — Obtenha o direito no seu perfil de assinatura

Os entitlements são concedidos por conta de desenvolvedor, não por ficha do app na loja, e o Apple declara a limitação diretamente: os entitlements "are limited to use only in the iOS or iPadOS App Store in specific storefronts." Assim que a conta recebe o entitlement StoreKit External Purchase Link, você o adiciona ao seu app abrindo o arquivo .entitlements do projeto no Xcode, adicionando a chave com.apple.developer.storekit.external-purchase-link e definindo seu valor como true. Para a variante por região, a chave é com.apple.developer.storekit.custom-purchase-link.allowed-regions e o valor é um array dos códigos de país em minúsculas onde você pretende oferecer a funcionalidade — nas palavras do Apple, ele "must only include regions where Apple supports custom purchase link options."

Como um entitlement está vinculado ao perfil de provisionamento, a sequência prática é: solicitar, aguardar o recurso aparecer, regenerar os perfis, assinar novamente e então enviar. Uma compilação assinada com um perfil antigo simplesmente não conseguirá abrir o link, e a falha aparece em tempo de execução, não em tempo de compilação.

Etapa 3 — Configure as URLs de destino no Info.plist

Duas chaves de property list fazem o trabalho, e escolher a certa define qual API você chama. SKExternalPurchaseLink é um dicionário cujas chaves são códigos de país ISO 3166-1 alpha-2 em minúsculas — uma URL de destino por código de país. Apple lista os códigos válidos: os vinte e sete estados-membros da UE mais Islândia (is), Noruega (no) e Rússia (ru). SKExternalPurchaseMultiLink é a variante multi-link: o mesmo formato de dicionário, mas cada código de país aponta para um array de uma a cinco URLs de destino.

Toda URL de destino precisa atender a quatro condições, e a quarta é a que as pessoas esquecem: precisa usar o esquema HTTPS, formar uma URL absoluta válida, não conter parâmetros de consulta e ter 1.000 caracteres ASCII ou menos. Além disso, o Apple afirma que "A qualquer momento, as URLs de destino que você fornece na chave da lista de propriedades devem corresponder aos valores no binário do seu app que você envia para a revisão do app" — então as URLs fazem efetivamente parte da sua submissão para revisão, e alterá-las é um lançamento, não uma edição de configuração.

O MultiLink não está disponível para todos: você pode fornecer um ou mais links por código de país se o seu app se qualificar para o direito de Link de Compra Externa do StoreKit, conforme o Apple descreve; caso contrário, você fornece exatamente um link por código de país.

Etapa 4 — Condicione a interface com canOpen antes de desenhar qualquer coisa

canOpen é um booleano que responde “este app consegue abrir com sucesso o link de compra externa configurado na vitrine atual da App Store?”. A Apple documenta exatamente três condições que precisam ser todas verdadeiras: a vitrine atual permite compra externa e a pessoa é elegível para fazer compras externas; seu app configura o direito com.apple.developer.storekit.custom-purchase-link.allowed-regions ou com.apple.developer.storekit.external-purchase-link; e seu app configura um link para a vitrine atual. Qualquer outra situação resulta em false. Não é preciso verificar de novo, a menos que a vitrine da App Store mude, o que significa que você pode avaliar uma vez na inicialização e controlar a interface do seu paywall a partir do resultado. Quando for false, o fallback documentado é verificar canMakePayments e permanecer na compra dentro do app.

Etapa 5 — abra o link: open() ou open(url:)

Com um único link configurado, chame ExternalPurchaseLink.open(). Com a chave de múltiplos links, leia eligibleURLs — o array de links que o app configurou para a loja atual — e chame open(url:) com o que você escolher, em resposta a uma interação deliberada do usuário, como tocar em um botão. A Apple é explícita ao afirmar que eligibleURLs retorna nil em três situações: a loja não permite compra externa ou a pessoa não é elegível; o direito não está presente; ou nenhum link está configurado para a loja atual. Nil mais um SKExternalPurchaseLink configurado significa recorrer a canOpen; nil sem um significa recorrer a canMakePayments.

open(url:) é assíncrono e apresenta uma folha de continuação que permite à pessoa escolher se o app mostra o link de compra externa. Ele retorna antes de a folha ser apresentada e pode lançar um StoreKitError quando o direito não está presente, nenhum link está configurado para a vitrine, a vitrine não oferece suporte a compras externas, a pessoa não é elegível ou ocorre um erro de rede ou de sistema. Se a pessoa optar por continuar, o StoreKit abre sua URL no navegador padrão e acrescenta a ela um token de compra externa e o ID do bundle do app — esse token é a razão de existir a etapa de relatório.

Passo 6 — Reporte cada token pela API do Servidor de Compras Externas

A External Purchase Server API é uma API REST que você chama do seu próprio servidor para "reportar tokens de compra externa e as transações dos seus clientes relacionadas aos tokens". A instrução não é opcional e não se limita a vendas bem-sucedidas: reporte todos os tokens, incluindo os que não resultaram em transação. Concretamente, o Apple lista quatro casos que exigem um relatório cada — um token com itens de linha quando o cliente conclui uma ou mais transações; um token sem itens de linha quando o cliente não conclui nenhuma; um token não reconhecido, quando chega uma Notificação do Servidor do App Store para um token do qual você não tem registro; e tokens duplicados de ACQUISITION e SERVICES. A autorização usa JSON Web Tokens gerados a partir de chaves de API que você cria no App Store Connect.

Se você já usa o App Store Server Notifications V2, o pipeline de relatórios é o lugar natural para conectar: a notificação informa que existe um token, sua loja registra a transação e o relatório da External Purchase Server API fecha o ciclo.

Etapa 7 — Mantenha a fronteira da loja em vista

Tudo acima é delimitado por uma frase repetida na diretriz e no direito: os direitos são limitados ao iOS ou ao iPadOS App Store em vitrines específicas, e fora da vitrine dos Estados Unidos o app e seus metadados não podem incluir botões, links externos ou outras chamadas para ação que direcionem clientes a mecanismos de compra diferentes da compra dentro do app. Essa fronteira vale também para os metadados — uma captura de tela mostrando um checkout externo em uma vitrine onde links não são permitidos é um risco de rejeição, não uma escolha de marketing.

Armadilhas que merecem uma segunda leitura

  • Parâmetros de consulta são proibidos. Parâmetros de rastreamento na URL de destino violam as regras de URL documentadas; o token que o StoreKit acrescenta é o que carrega a atribuição.
  • O direito é uma capacidade de assinatura, não uma configuração de servidor. Adicionar a chave ao .entitlements sem a capacidade concedida gera um perfil que não consegue usá-la.
  • As URLs precisam corresponder ao binário o tempo todo. Criar uma nova URL de destino sem um lançamento é uma divergência que o Apple documenta como requisito, não como preferência.
  • Um link por país, a menos que você se qualifique para o MultiLink. Um array de cinco URLs em uma loja onde só um link é permitido é um problema na revisão.
  • Apps apenas nos EUA não precisam de nada. Se as suas fichas do app na loja são apenas para os EUA, a diretriz 3.1.1(a) já permite o link externo — não crie uma capacidade de perfil de que você não precisa.

Por onde começar

Anote sua lista de vitrines, marque cada uma como EUA, região de direito, região de link de compra personalizado ou nenhuma, e então implemente o portão uma única vez: verifique canOpen (ou eligibleURLs para múltiplos links), mostre o controle apenas quando ele retornar verdadeiro e deixe a compra dentro do app como caminho padrão para todos os demais. A gestão de tokens no seu servidor é a parte que decide se o recurso continua em conformidade após o lançamento.

Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.

Clique para escolher um arquivo · clique com o botão direito → Colar, ou pressione Ctrl/⌘+V para colar uma captura de tela

Você também pode arrastar um arquivo para esta caixa.

Respondemos ao e-mail que você fornecer. Seus dados ficam com KappS.

✔ Enviado

Recebemos sua mensagem e responderemos em até 24 horas.


← Voltar para editar