Certificado iOS e provisioning profile com Expo

Um certificado de desenvolvedor iOS prova quem assinou seu app. O provisioning profile, ou perfil de provisionamento, liga esse certificado a um app específico e diz onde ele tem permissão para rodar. Com Expo, você quase nunca precisa criá-los na mão: o EAS cria, armazena e renova tudo quando você roda um build.

Mesmo assim, vale entender o que cada arquivo faz. No dia em que um build se recusa a instalar ou um envio trava, é esse conhecimento que te economiza um dia inteiro. Este guia passa pelos quatro elementos, a validade de cada um, os limites da Apple e os erros típicos, com a solução para cada um.

Eu publico meus apps iOS com Expo e EAS, entre eles Solys e TradaZen. O caminho completo está em publicar um app iOS sem Mac. Aqui, a gente abre o capô da assinatura.

Por que a Apple exige uma assinatura

Um app iOS precisa ser assinado para ser instalado num iPhone ou enviado ao App Store Connect. A assinatura garante que o app vem de um desenvolvedor conhecido pela Apple e que ninguém o modificou desde então.

Para a App Store, tem um detalhe que tranquiliza. Segundo a nota técnica TN3161 da Apple, a App Store verifica se seu certificado de distribuição é válido no envio e depois assina o app de novo, que então não depende mais da data de expiração do seu certificado. Ou seja, seus certificados precisam estar válidos no momento do envio, não durante toda a vida do app.

Os quatro elementos que você precisa conhecer

A documentação do Expo sobre credenciais lista três para iOS: o certificado de distribuição, os perfis e a chave de notificações push. Eu adiciono o identificador do app, sem o qual nenhum perfil existe.

O certificado de distribuição

É a sua assinatura de desenvolvedor. A ajuda da Apple sobre certificados separa duas famílias:

• Apple Development serve para rodar seu app nos seus aparelhos durante o desenvolvimento. Ele pertence a uma pessoa.
• Apple Distribution serve para distribuir em aparelhos de teste definidos ou para enviar ao App Store Connect. Ele pertence ao time, e só o titular da conta ou um admin pode criá-lo.

O certificado de distribuição não é de nenhum app específico: o mesmo assina todos os seus apps. Ele vem com uma chave privada, e é ela que permite assinar. Segundo a TN3161, um certificado da Apple costuma valer um ano a partir da criação.

O identificador do app (App ID)

O App ID identifica seu app dentro de um perfil. Ele usa seu bundle identifier, por exemplo com.exemple.monapp (exemplo fictício). Segundo a ajuda da Apple, ele também carrega a lista de capacidades permitidas: notificações push, App Groups, Sign in with Apple…

Com Expo, é o campo ios.bundleIdentifier da sua configuração. Escolha de uma vez por todas: ele precisa ser idêntico em todo lugar, na sua configuração e no App Store Connect. O App ID não expira. E segundo a doc do Expo sobre capacidades iOS, o EAS sincroniza as capacidades dele com sua configuração a cada build.

O perfil de provisionamento

O perfil faz a ligação. Ele contém um App ID, um certificado e, dependendo do tipo, uma lista de aparelhos autorizados. Três tipos te interessam:

• Desenvolvimento: seu app de teste nos seus aparelhos registrados.
• Ad hoc: um build instalável numa lista específica de aparelhos, cada um identificado pelo UDID. É a "distribuição interna" do EAS.
• App Store: para o App Store Connect e o TestFlight. Ele não contém nenhuma lista de aparelhos, explica a nota TN3125.

Cada perfil tem uma data de expiração: no máximo um ano em geral segundo a Apple, 12 meses segundo o Expo.

A chave de notificações push (APNs)

A chave APNs autoriza seu servidor, ou o do Expo, a enviar notificações para o seu app. É um arquivo .p8 que só pode ser baixado uma vez: a Apple não guarda ele na sua conta. Uma mesma chave serve para todos os seus apps, e ela nunca expira.

A tabela resumo

Elemento	Serve para	Validade	Quem cuida com Expo
Certificado de distribuição	Assinar seus builds	Um ano em geral	EAS, depois do login
App ID	Identificar seu app	Não expira	Você, depois o EAS
Perfil App Store	Enviar para a Apple	Até 12 meses	EAS
Perfil ad hoc	Instalar nos seus iPhones	Até 12 meses	EAS e seus aparelhos
Chave push APNs	Enviar notificações	Não expira	EAS ou você
Perfil de conta gratuita	Testar pelo Xcode	7 dias	Xcode, não o EAS

"Você, depois o EAS": você escolhe o bundle identifier, o EAS cuida das capacidades. "EAS e seus aparelhos": você registra cada iPhone de teste, o EAS gera o perfil. A última linha é sobre a conta Apple gratuita: segundo a ajuda da Apple sobre contas, os perfis dela expiram 7 dias depois de criados.

Os limites da Apple que você precisa conhecer

• Certificados de distribuição: pouquíssimos por conta. A ajuda da Apple fala de um só por tipo de distribuição e por time, a tabela do Expo fala de um limite de 2. Guarde a regra: não crie um certificado novo a cada build ou em cada computador.
• Chaves APNs: no máximo 2 por conta, segundo o Expo.
• Perfis: sem limite, segundo o Expo.
• Aparelhos: até 100 por família de produtos e por ano de assinatura, segundo a ajuda da Apple sobre aparelhos. Desativar um aparelho não libera vaga. O contador volta a 100 no início do ano de assinatura seguinte, se você remover os aparelhos.

O que o EAS faz por você

Segundo a página do Expo sobre credenciais gerenciadas, seu primeiro build iOS oferece gerar o que estiver faltando. Você faz login na sua conta Apple Developer, o EAS cria o certificado de distribuição, o perfil e a chave push, e guarda tudo nos servidores dele. Os builds seguintes reaproveitam.

Três pontos úteis:

• Sua senha da Apple fica na sua máquina. A página de segurança do Expo diz que ela não é enviada aos servidores deles, e que as credenciais armazenadas são criptografadas.
• eas credentials mostra tudo: certificado, perfis, chave push. O comando também permite substituir ou remover.
• Apagar no EAS não apaga na Apple. Para liberar uma vaga, você precisa revogar no portal da Apple.

Você também pode manter o controle com credenciais locais: um arquivo credentials.json aponta para o seu certificado (.p12) e o seu perfil (.mobileprovision). O Expo pede para adicionar esses arquivos ao .gitignore. É a mesma regra das chaves de API de um app Expo: segredo nunca vai para o repositório.

Os erros típicos e como resolver

Perfil expirado

Um build ad hoc leva o perfil junto: quando ele expira, o app não abre mais nos seus iPhones de teste. Já na App Store, o Expo confirma que a expiração não tem nenhum efeito no app em produção. A solução: rode um novo build. O EAS gera um perfil novo, ou você faz isso com eas credentials. Depois, reinstale o novo build nos seus aparelhos.

Não confunda com o TestFlight: um build do TestFlight expira depois de 90 dias, seja qual for o seu certificado. Os detalhes estão em TestFlight para testar seu app de iPhone.

Certificado expirado ou revogado

A Apple é clara: se sua assinatura estiver válida, seus apps que já estão na App Store não são afetados. Por outro lado, você não consegue mais enviar builds assinados com esse certificado. Um build enviado mas ainda não submetido pode ser marcado como Invalid Binary se o certificado dele foi revogado. E os perfis que contêm um certificado revogado ficam inválidos.

A solução: crie um certificado novo pelo eas credentials ou no próximo build, e deixe o EAS refazer os perfis. E nunca revogue por reflexo um certificado que está funcionando.

Aparelho fora do perfil ad hoc

O link de instalação funciona para você, mas não no iPhone de um testador. Causa: a doc do Expo sobre distribuição interna explica que só os aparelhos presentes no perfil no momento do build podem instalar o app.

A solução:

1. Registre o aparelho com eas device:create.
2. Rode um novo build em modo interativo, logado na sua conta Apple, para o EAS atualizar o perfil. Ou assine de novo o build existente com eas build:resign, sem recompilar tudo.
3. Em integração contínua, o modo não interativo reaproveita o perfil sem atualizar a lista. Adicione a opção --refresh-ad-hoc-provisioning-profile.

Numa conta nova ou recém-renovada, a Apple pode levar de 24 a 72 horas para processar um aparelho novo. Então o primeiro build que inclui ele pode falhar: espere e rode de novo.

Limite de certificados atingido

A Apple se recusa a criar um certificado de distribuição novo. Muitas vezes, tem certificados antigos esquecidos: criados pelo Xcode em outro Mac ou por outro serviço de build. Reaproveite o certificado existente se você tiver o arquivo .p12 dele. Se não tiver, revogue o que não serve mais no portal da Apple. Uma revogação não afeta seus apps já publicados, mas invalida os perfis que continham esse certificado.

"Provisioning profile doesn't include signing certificate"

Essa mensagem do Xcode quer dizer que o perfil não contém o certificado cuja chave privada está na sua máquina. Causa típica: misturar a assinatura automática do Xcode com as credenciais do EAS. Escolha uma única fonte da verdade: builds EAS com credenciais gerenciadas, ou credenciais locais, mas não as duas.

Notificações cortadas depois de revogar a chave

Se você revogar sua chave APNs, o Expo avisa que todos os apps que usam ela param de receber notificações. Crie uma chave nova e envie com eas credentials. Os tokens Expo Push dos seus usuários não mudam.

Capacidade adicionada, perfil inválido

Ativar um serviço como notificações push ou App Groups deixa o perfil inválido: é preciso gerar de novo. Com o EAS, a sincronização das capacidades acontece a cada build. Se o perfil continuar sendo recusado, o eas credentials permite gerar um novo.

O que vem depois da assinatura

Um build assinado é só uma etapa. A página do app, as capturas de tela, a privacidade e o envio para revisão estão reunidos em publicar um aplicativo na App Store. Se você ainda não tem sua assinatura, comece pela conta de desenvolvedor Apple. E para entender por que eu recomendo Expo para iniciantes, leia React Native e Expo para um app mobile.

Se você está preparando sua primeira publicação

Antes do seu primeiro envio, faça o diagnóstico gratuito: ele te diz o que realmente está travando o seu projeto e te manda minha checklist contra rejeições da Apple.

Para construir o app, ligar as assinaturas e publicar sem brigar com a assinatura de código, o iOS & Android Kit segue o caminho em quatro etapas com o código inicial dos meus apps, no seu ritmo.

Perguntas frequentes

O que é um provisioning profile?

É o arquivo que autoriza seu app a rodar ou a ser enviado para a Apple. Ele liga um identificador de app, um certificado e, dependendo do tipo, uma lista de aparelhos. Um perfil App Store não contém nenhum aparelho, um perfil ad hoc lista alguns.

O certificado de desenvolvedor iOS é gratuito?

Ele não tem preço separado: o certificado de distribuição está incluído no Apple Developer Program, a 99 dólares por ano. Com uma conta Apple gratuita, o Xcode deixa você testar em no máximo 3 aparelhos, mas os perfis expiram depois de 7 dias e não dá para publicar.

Quanto tempo dura um certificado de distribuição da Apple?

Em geral um ano a partir da criação, segundo a Apple. Os perfis de provisionamento também duram no máximo 12 meses. Já a chave de notificações push nunca expira.

O que acontece se meu certificado de distribuição expirar?

Nada com seus apps que já estão na App Store, desde que sua assinatura esteja válida. Você só não consegue mais enviar um build novo assinado com esse certificado. Com o EAS, um certificado novo é criado no próximo build ou com eas credentials.

Preciso de um Mac para criar um certificado iOS?

Não, se você usar o EAS. Você faz login na sua conta Apple pela linha de comando, e o EAS gera o certificado e o perfil, no Windows ou no Linux. Sem o EAS, o método clássico passa pelo Xcode ou pelo Acesso às Chaves de um Mac.

Quantos aparelhos um perfil ad hoc pode ter?

Sua conta pode registrar até 100 iPhones por ano de assinatura, e o mesmo número para cada outra família de aparelhos. Um aparelho desativado continua contando. Para testar com mais gente, use o TestFlight.