Processo de Criação, Configuração e Deploy de Nova Marca (Whitelabel) – App Mobile (Expo)

Documentação Oficial

Este guia descreve, de ponta a ponta, como iniciar, configurar e publicar uma nova marca (whitelabel) no aplicativo mobile baseado em Expo (React Native). Ele cobre a criação da estrutura por marca, configuração dos arquivos essenciais (whitelabel.json), serviços do Firebase, manipulação de assets, geração de credenciais, build e a submissão para as lojas.

Visão Geral

Guia objetivo para criar e publicar um novo brand do app (Expo/React Native).

Pacote/bundle padrão: empresa.bank.lw
Fluxo: criar brand → switch-brand → configurar credenciais → build → submissão
Firebase: utilizar apenas os arquivos de configuração da marca

Exemplo de convenção:

brand: NewBank

slug: newbank

pacote/bundle: empresa.bank.lw (ou um específico da marca, como com.newbank.app)

Pré-requisitos

Contas/credenciais:
- Conta Expo (expo.dev) com acesso ao projeto.
- Google Play Console (Android) e Apple Developer (iOS).
- Projeto Firebase dedicado para a nova marca, com acesso para baixar google-services.json e GoogleService-Info.plist.
Ferramentas locais:
- Node.js LTS (recomendado ≥ 20.x).
- Yarn (v1.22.21).
- EAS CLI instalado globalmente: npm i -g eas-cli.
- Git.
Arquivos e informações da marca:
- Assets da marca (ícone e splash).
- Nome do app, slug, cor primária, e os IDs de pacote/bundle.
Acesso e permissões:
- Permissões no repositório do app.
- Permissões para criar/gerenciar credenciais no EAS.

1. Estrutura de Pastas

A estrutura de arquivos para cada marca deve ser criada fora do diretório src, na pasta whitelabels.

root/
├─ android/
├─ assets/
├─ ios/
├─ whitelabels/
│  └─ brands/
│     ├─ newbank/
│     │  ├─ assets/
│     │  │  ├─ icon.png
│     │  │  └─ splash.png
│     │  ├─ whitelabel.json
│     │  ├─ google-services.json
│     │  └─ GoogleService-Info.plist
│     └─ ...
├─ scripts/
├─ whitelabel.json
└─ ...

2. Configurando Variáveis de Ambiente com EAS Environment Variables

Gerencie variáveis de ambiente no Expo usando os comandos EAS e seleção interativa de ambientes.

Usando eas env:push com arquivo:

Passo 1: Preparar o arquivo de variáveis

Certifique-se de que seu arquivo .env.local está configurado corretamente:

# Environment: staging/production
EXPO_PUBLIC_API_URL=https://api.staging.example.com
EXPO_PUBLIC_APP_KEY=your_staging_app_key_here
EXPO_PUBLIC_CASTLE_PUBLIC_KEY=pk_staging_castle_key_example
EXPO_PUBLIC_TOKEN_REGISTER=your_base64_staging_token_here
EXPO_PUBLIC_X_TOKEN=staging-uuid-token-example
EXPO_PUBLIC_X_TESTE=staging_test_value

Comandos para Configurar Variáveis

Enviar variáveis para ambiente específico

eas env:push

O terminal apresentará uma lista de ambientes disponíveis:

? Select an environment › ❯ preview(staging) production development

3. Arquivos por Brand

Crie ou edite os seguintes arquivos dentro da pasta da nova marca: whitelabels/brands/<slug>/.

3.1 `whitelabel.json` (do brand)

Caminho: whitelabels/brands/<slug>/app.json

Este arquivo define o nome, slug, id do projeto, url do eas update, bundle ios/android, cor de fundo da splash e a versão do aplicativo.

Modelo:

{
  "UPDATE_EXPO_URL": "https://u.expo.dev/5919895a-03d3-4512-8eee-be86ae8f6123",
  "EAS_PROJECT_ID": "5919895a-03d3-4512-8eee-be86ae8f6123",
  "APP_SLUG": "csbbenk",
  "APP_NAME": "csbbenk",
  "IOS_BUNDLE_ID": "csbbenk.wl",
  "ANDROID_PACKAGE": "csbbenk.bank.wl",
  "SPLASH_BG_COLOR": "#4133a6",
  "APP_VERSION": "1.8.1",
  "IOS_BUILD_NUMBER": "8",
  "ANDROID_VERSION_CODE": "32"
}

O que mudar por brand:

APP_NAME e APP_SLUG.
SPLASH_BG_COLOR.
APP_VERSION.
UPDATE_EXPO_URL.
EAS_PROJECT_ID.
IOS_BUNDLE_ID e ANDROID_PACKAGE (use um ID único por marca para evitar conflitos nas lojas).
Caminhos de assets e arquivos Firebase, se necessário.

3.2 Arquivos Firebase

Baixe os arquivos de configuração do projeto Firebase da marca e coloque-os na pasta whitelabels/brands/<slug>/.

google-services.json (Android)
GoogleService-Info.plist (iOS)

4. Configuração Inicial e Credenciais

Antes de iniciar, ative a configuração da marca desejada com o script switch-brand.

yarn switch-brand <slug>

Este comando copia os arquivos de whitelabels/brands/<slug>/ para a raiz do projeto, preparando o ambiente para o build.

Após ativar a marca, configure o projeto no EAS e gere as credenciais:

# 1. Vincule o projeto local a um projeto no Expo/EAS
npx eas init

# 2. Gere/sincronize as credenciais de iOS
npx eas credentials -p ios

# 3. Gere/sincronize as credenciais de Android
npx eas credentials -p android

Para as credenciais, o EAS irá perguntar se você deseja que ele gerencie os certificados (keystore para Android, provisioning profiles para iOS). A opção recomendada é deixar o EAS cuidar disso (“Let EAS handle it”).

5. Configurar o EAS Update

Conceitos Importantes

Branches (Ramificações)

O que são: Diferentes versões do seu app para desenvolvimento
Exemplos: production, staging, development
Uso: Separar versões estáveis de versões em teste

📺 Channels (Canais)

O que são: Canais de distribuição que apontam para branches
Relação: Um channel sempre aponta para um branch específico
Exemplo: Channel production → Branch main

🔢 Runtime Version

O que é: Versão do código nativo do app
Importante: Updates só funcionam entre mesma runtime version
Políticas:
- appVersion: Usa a versão do app (recomendado)
- nativeVersion: Usa version + buildNumber
- Valor fixo: Ex: "1.0.0"

Criar e Configurar Branches

# Criar branch para produção
eas branch:create production

# Criar branch para staging
eas branch:create staging

# Criar branch para desenvolvimento
eas branch:create development

# Listar todos os branches
eas branch:list

# Ver detalhes de um branch específico
eas branch:view production

# Deletar um branch (se necessário)
eas branch:delete nome-do-branch

Mapear Channels para Branches

# Criar branch staging/production/development
eas channel:create staging/production/development

# Mapear channel production para branch production
eas channel:edit production --branch production

# Mapear channel staging para branch staging
eas channel:edit staging --branch staging

# Mapear channel development para branch development
eas channel:edit development --branch development

# Ver todos os channels
eas channel:list

# Ver detalhes de um channel
eas channel:view production

# Criar um novo channel
eas channel:create nome-do-channel --branch nome-do-branch

Criar Builds com Channels

# Build para staging (usando scripts do package.json)
yarn run deploy-ios:staging
yarn run deploy-android:staging

# Ou diretamente com EAS
eas build --platform ios --profile staging
eas build --platform android --profile staging

# Build para production
eas build --platform ios --profile production
eas build --platform android --profile production

# Build para ambas plataformas
eas build --profile staging

Publicar Updates

# Publicar update para staging
eas update --branch staging --message "Fix: Correção no sistema de login"

# Publicar update para production
eas update --branch production --message "Release: v1.0.1 - Novas funcionalidades"

# Update com mais detalhes
eas update \\
  --branch staging \\
  --message "Feature: Sistema de notificações push" \\
  --platform android,ios

# Update apenas para uma plataforma
eas update --branch staging --message "Fix iOS specific" --platform ios

Usando Scripts do package.json

# Usando o script já configurado
yarn run update:staging "Mensagem do update"

Ver Updates Publicados

# Listar updates de um branch
eas update:list --branch staging

# Ver detalhes de um update específico
eas update:view [UPDATE_ID]

# Ver updates de todos os branches
eas update:list

6. Fluxo de Build e Submissão

O comando a seguir automatiza a limpeza, ativação da marca, preparação e o build para ambas as plataformas, com envio automático para as lojas.

# Ativa a marca desejada
yarn switch-brand <slug>

# Limpa artefatos de builds anteriores
yarn clear-platform

# Executa o build para Android e iOS, com perfil 'staging' e auto-submit
yarn deploy-ios:staging

pre-eas-build.js: Script de preparação que pode realizar ajustes finais antes do build.
yarn clear-platform: Remove pastas android e ios para evitar cache ou configurações de outra marca.
yarn deploy-ios:staging: Inicia o processo de build no EAS. A flag --auto-submit envia os artefatos (.aab e .ipa) para a Google Play Console e App Store Connect assim que o build termina.

Após o comando, monitore o status no dashboard do EAS.

7. Configuração Adicional para Contas Google Play Novas

Se a submissão para Android for para uma conta Google Play nova, é necessário criar e configurar uma chave de API de serviço. Siga o guia oficial do Expo para isso:

Creating a Google Service Account Key

O arquivo JSON gerado durante este processo deve ser anexado como Google Service Account Key no EAS Submit, localizado nas credenciais Android da plataforma Expo Dev.

Troubleshooting Rápido

Erro de pacote/bundle duplicado: Garanta que android.package e ios.bundleIdentifier são únicos para cada marca.
Firebase “App ID inválido”: Baixe novamente os arquivos google-services.json e GoogleService-Info.plist do console Firebase e confirme se estão nos locais corretos.
Falha de assinatura Android: Use eas credentials para que o EAS gerencie a keystore ou para associar a correta.
Build local difere do CI: Alinhe as versões de Node.js, Expo SDK e EAS CLI e, se necessário, limpe o cache com eas build --clear-cache.