Publicado em: 2026-07-31

Push no React Native com Sendrealm: Guia para Expo e Bare

A configuração de push no React Native costuma ser apresentada como instalação de SDK. O pacote JavaScript é a parte fácil. Um ambiente de produção também precisa de um app Android registrado no Firebase, um App ID iOS com push habilitado, credenciais dos provedores, capabilities nativas, permissão em runtime, identidade do dispositivo, um backend confiável para enviar e uma forma de diagnosticar o resultado.

A Sendrealm reúne essas peças no mesmo fluxo. O pacote @sendrealm/react-native atende apps React Native bare e projetos Expo capazes de incluir código nativo. Registro, vínculo de identidade, tags, eventos, deep links, canais Android e diagnósticos usam uma API JavaScript consistente, enquanto a Sendrealm conversa com FCM no Android e APNs no iOS.

Este guia cobre os dois caminhos, das credenciais até o primeiro envio pelo backend. Mantenha as páginas oficiais por perto, porque elas contêm os detalhes atuais de cada plataforma:

Escolha entre Expo e bare React Native

A escolha depende de quem controla os projetos nativos.

Use o caminho Expo quando o app trabalha com Expo prebuild, expo run, development builds do EAS ou builds de produção pelo EAS. O config plugin da Sendrealm aplica a configuração nativa durante o prebuild.

Use o caminho bare quando o repositório mantém diretamente android e ios. O autolinking instala o módulo, mas o time cuida do Firebase, capabilities no Xcode e callbacks do AppDelegate descritos abaixo.

Expo Go não é suportado. Push mobile exige código nativo Android e iOS, e o Expo Go não contém o módulo nativo da Sendrealm. Use development build, prebuild, expo run ou EAS. É uma escolha de build, não uma falha do SDK.

Na data deste artigo, a documentação bare exige React 18 ou superior e React Native 0.76 ou superior. Consulte os requisitos atuais ao integrar um aplicativo mais antigo.

Entenda as quatro credenciais antes de alterar o código

A configuração fica mais simples quando cada identificador tem uma única casa.

Sendrealm Push App ID

O Push App ID identifica o aplicativo dentro da Sendrealm. Ele é público e pertence à configuração do SDK mobile. Não é segredo e não autoriza envios pelo backend.

Sendrealm API key

A API key autoriza operações no servidor. Guarde-a no secret manager ou ambiente do backend. Nunca a inclua no bundle React Native, app.json, app.config.js, google-services.json ou variável mobile incorporada ao binário.

Arquivos Firebase para Android

Android precisa de dois JSONs diferentes:

google-services.json fica no projeto do app. Em React Native bare, use android/app/google-services.json. Em Expo, aponte o config plugin para o arquivo e deixe o prebuild copiá-lo.
O JSON privado da conta de serviço Firebase fica no dashboard da Sendrealm. Ele permite que a Sendrealm autentique envios no FCM HTTP v1.

Os arquivos não são intercambiáveis. Enviar google-services.json como credencial não oferece autorização FCM no servidor. Versionar a chave privada da conta de serviço no app expõe uma credencial de produção.

Valores APNs para iOS

A Sendrealm precisa da chave privada APNs .p8, Key ID, Apple Team ID, Bundle ID e ambiente APNs. Envie esses dados pelas configurações do provedor. A chave privada nunca fica no app.

O Apple App ID e o target no Xcode ou Expo devem usar o mesmo Bundle ID. Push Notifications precisa estar habilitado no App ID e no target que será compilado.

O guia de credenciais mobile apresenta os dois provedores passo a passo.

Etapa 1: crie o Push App na Sendrealm

Abra o dashboard, selecione o projeto correto e crie ou escolha o Push App desta aplicação. Separe desenvolvimento e produção com intenção. Se os ambientes usam package names ou Bundle IDs diferentes, configure exatamente a identidade que inicializará o SDK.

Copie o Push App ID público. Ele será usado na inicialização JavaScript.

Depois, envie as credenciais:

JSON da conta de serviço Firebase e package name exato para Android;
.p8, Key ID, Team ID, Bundle ID e ambiente correto para iOS.

Não comece por um grande envio. Primeiro prove que um dispositivo real de desenvolvimento consegue registrar e receber um teste.

Etapa 2A: instale em um app Expo

Instale pelo Expo para selecionar uma versão compatível:

npx expo install @sendrealm/react-native

Adicione o config plugin ao app.json ou app.config.js:

{
  "expo": {
    "android": {
      "package": "com.example.app"
    },
    "ios": {
      "bundleIdentifier": "com.example.app"
    },
    "plugins": [
      [
        "@sendrealm/react-native",
        {
          "android": {
            "googleServicesFile": "./google-services.json",
            "notificationIcon": "ic_stat_sendrealm",
            "notificationColor": "#111827"
          },
          "ios": {
            "apnsEnvironment": "sandbox",
            "enableBackgroundRemoteNotifications": true,
            "notificationServiceExtension": true
          }
        }
      ]
    ],
    "extra": {
      "sendrealmAppId": "YOUR_SENDREALM_APP_ID",
      "sendrealmPushEnvironment": "development",
      "sendrealmApnsEnvironment": "sandbox"
    }
  }
}

Habilite background remote notifications somente quando o app realmente processar pushes silenciosos. Habilite a Notification Service Extension quando houver imagens ricas. As duas opções alteram código nativo e exigem novo build.

notificationIcon deve apontar para um drawable Android. Ícones da barra de status normalmente usam arte simples e monocromática. Se o projeto gerado não tiver algo como res/drawable/ic_stat_sendrealm.xml, o Android não consegue usar o recurso solicitado.

Principalmente: nunca coloque a API key da Sendrealm, o JSON privado da conta Firebase ou o conteúdo do .p8 em Expo extra. A configuração Expo entra no cliente.

Compile o app nativo Expo

Para um build local:

npx expo prebuild --platform android
npx expo run:android

npx expo prebuild --platform ios
npx expo run:ios --device

Use --device no teste APNs. Um dispositivo iOS físico é o alvo confiável.

Para development builds no EAS:

npx eas build --profile development --platform android
npx eas build --profile development --platform ios

Quando as opções do plugin mudarem, rode prebuild novamente ou crie outro build EAS. Recarregar JavaScript não adiciona entitlement, service extension, plugin Gradle ou recurso nativo a um binário existente.

Etapa 2B: instale em React Native bare

Instale o pacote e reconstrua os dois apps:

npm install @sendrealm/react-native
npx react-native run-android
npx react-native run-ios

Se o projeto iOS usa CocoaPods diretamente:

cd ios
pod install

No Android:

Coloque google-services.json em android/app/google-services.json.
Aplique o plugin Gradle do Google Services se ainda não estiver presente.
Confirme que o package do Firebase corresponde exatamente ao applicationId, inclusive maiúsculas.
Teste em dispositivo ou emulador com Google Play services.

No iOS:

Habilite Push Notifications para o App ID no Apple Developer.
Adicione Push Notifications em Signing & Capabilities no Xcode.
Confirme que o Bundle ID corresponde à configuração da Sendrealm e da chave APNs.
Adicione Background Modes com Remote notifications somente quando necessário.
Adicione Notification Service Extension para imagens ricas.
Encaminhe os callbacks nativos.

O autolinking instala o SDK, mas o iOS bare deve encaminhar o token APNs para a Sendrealm. No AppDelegate.swift, configure o módulo e repasse o token:

import SendrealmReactNative

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
  SendrealmModule.configure()
  return true
}

func application(
  _ application: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
  SendrealmModule.didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
}

Mescle essas chamadas com a implementação atual do AppDelegate. Não substitua a inicialização existente do React Native nem outros delegates apenas para copiar este exemplo reduzido.

Se o app recebe notificações em background, encaminhe também esse callback conforme o setup iOS do SDK bare. Se o app atribui seu próprio UNUserNotificationCenter.current().delegate após configurar a Sendrealm, encaminhe as respostas para preservar eventos de clique e ação.

Etapa 3: inicialize uma vez no JavaScript

Expo e bare usam a mesma API:

import { useEffect } from 'react';
import Sendrealm from '@sendrealm/react-native';

export default function App() {
  useEffect(() => {
    void Sendrealm.initialize({
      appId: 'YOUR_SENDREALM_APP_ID',
      environment: 'development',
      autoRequestPermission: false,
      apnsEnvironment: 'sandbox'
    });
  }, []);

  return null;
}

Inicialize uma vez próximo à entrada do aplicativo. Evite componentes que montam novamente durante a navegação.

No Expo, leia a configuração pública por expo-constants:

import Constants from 'expo-constants';

const extra = Constants.expoConfig?.extra ?? {};

await Sendrealm.initialize({
  appId: extra.sendrealmAppId,
  environment: extra.sendrealmPushEnvironment ?? 'development',
  autoRequestPermission: false,
  apnsEnvironment: extra.sendrealmApnsEnvironment ?? 'sandbox'
});

Existem dois conceitos de ambiente:

environment: "development" é o ambiente do dispositivo na Sendrealm e separa registros de desenvolvimento dos alvos de produção.
apnsEnvironment: "sandbox" é o ambiente do token Apple em builds assinados para desenvolvimento.

Use APNs production no TestFlight, App Store e builds assinados para produção. Um token TestFlight não é sandbox. Misturar os valores pode gerar registro local bem-sucedido e rejeição do provedor no envio.

Etapa 4: peça permissão no momento certo

Mantenha autoRequestPermission: false na maioria dos produtos. Inicialize, explique o valor dentro do app e peça permissão após uma ação:

import Sendrealm from '@sendrealm/react-native';

async function enableNotifications() {
  const alreadyAllowed = await Sendrealm.hasNotificationPermission();

  if (alreadyAllowed) {
    return true;
  }

  return Sendrealm.requestPermission();
}

O iOS oferece oportunidades limitadas para o prompt do sistema. Android 13 ou superior também exige permissão em runtime. Pedir imediatamente na primeira tela, antes de explicar o benefício, costuma produzir uma recusa duradoura.

Relacione o pedido a uma função real: status de pedido, atividade importante da conta, novas mensagens, lembretes ou outra opção recém-habilitada.

Etapa 5: vincule o cliente autenticado

O SDK registra o dispositivo antes do login, mas segmentação por identidade exige vínculo:

await Sendrealm.login('user-123', '[email protected]');

Use o ID estável do produto como external ID. Ao sair da conta:

await Sendrealm.logout();

Depois do login, o backend pode usar external_ids, contatos, emails ou audiências sem manter outro mapa entre usuários e tokens brutos.

Tags e eventos enriquecem segmentação e automação:

await Sendrealm.addTags({
  plan: 'pro',
  onboardingComplete: true
});

await Sendrealm.trackEvent('checkout_started', {
  product_id: 'sku_123',
  price: 29
});

Use tags mobile para estado observado pelo app. Envie cobrança, conta, segurança, compliance e perfil verificado pelo backend. Um cliente modificado não deveria declarar que a conta é paga ou aprovada.

Etapa 6: trate aberturas e deep links

Escute interações enquanto o app está em execução:

const subscription = Sendrealm.addNotificationClickListener(event => {
  console.log(event.notificationId, event.launchUrl);
  // Encaminhe event.launchUrl ao roteador de deep links.
});

// No cleanup:
subscription.remove();

Leia a notificação que abriu o aplicativo encerrado:

const initialNotification = await Sendrealm.getInitialNotification();

if (initialNotification?.launchUrl) {
  // Navegue depois de autenticação e rotas estarem prontas.
}

Trate o launch URL como entrada de navegação, não como autorização. A tela de destino continua aplicando autenticação e controle de acesso normais.

Etapa 7: crie canais de notificação no Android

Canais controlam importância, som e vibração visíveis ao usuário. Crie categorias separadas apenas quando o comportamento for diferente:

await Sendrealm.createNotificationChannel({
  id: 'orders',
  name: 'Atualizações de pedidos',
  importance: 'high',
  soundName: 'order_update'
});

O Android memoriza o comportamento e o usuário pode alterá-lo. Se o produto precisar de uma mudança material, use outro ID em vez de assumir que uma atualização substituirá o canal existente.

Reserve alta importância para mensagens que realmente merecem interromper. A capacidade técnica de acordar o dispositivo não é uma justificativa de produto.

Etapa 8: envie por backend confiável

Instale o SDK de servidor em um backend, worker, API route ou fila:

npm install @sendrealm/sdk

Crie o cliente com uma variável secreta e envie ao external ID vinculado pelo SDK mobile:

import Sendrealm from '@sendrealm/sdk';

const client = new Sendrealm({
  apiKey: process.env.SENDREALM_API_KEY,
  maxRetries: 2
});

const result = await client.push.notifications.send({
  app_id: 'YOUR_SENDREALM_APP_ID',
  external_ids: ['user-123'],
  environment: 'development',
  notification: {
    title: 'Seu pedido foi enviado',
    body: 'Toque para acompanhar a entrega.',
    launch_url: 'myapp://orders/123'
  },
  data: {
    order_id: '123'
  }
});

console.log({
  total: result.total,
  sent: result.sent,
  failed: result.failed,
  queued: result.queued
});

Use exatamente um estilo de alvo por requisição: tokens, web_subscriptions, device_ids, contact_ids, external_ids, emails ou audiences. Misturar estilos torna o escopo ambíguo e é rejeitado.

Em produção, omita environment ou use production. Mantenha testes apontados explicitamente para registros de desenvolvimento.

A documentação da API de push detalha payloads, overrides, botões, localização, agendamento e segmentação.

Etapa 9: consulte diagnósticos antes de adivinhar

Quando o primeiro push não aparece, verifique o dispositivo antes de reescrever o backend:

const diagnostics = await Sendrealm.getSupportDiagnostics();
console.log(JSON.stringify(diagnostics, null, 2));

Confirme:

existência do device ID da Sendrealm;
presença do token nativo;
status esperado da permissão;
assinatura ativa, exceto se a pessoa recusou;
versão do SDK;
ambiente igual ao envio;
ambiente APNs esperado no iOS;
ausência de erro inesperado.

Depois revise os provedores. No Android, verifique projeto Firebase, package, google-services.json, conta de serviço, Google Play services e permissão do Android 13. No iOS, verifique dispositivo físico, Bundle ID, entitlement, Team ID, Key ID, .p8 e ambiente APNs.

Aceitação do provedor, status em fila ou contagem de envio não garante exibição. Conectividade, economia de energia, restrições do fabricante, canais, Focus do iOS, resumo de notificações, ajustes do usuário, throttling e tokens antigos influenciam o resultado. Push é best effort; estado importante também deve estar disponível quando o app abrir.

Checklist de produção

Antes de habilitar uma audiência real:

O Push App pertence ao projeto correto.
Desenvolvimento e produção estão separados.
Package Firebase corresponde ao applicationId ou package Expo.
google-services.json está no app, não como credencial do servidor.
O JSON privado da conta Firebase está na Sendrealm e fora do código mobile.
Bundle ID corresponde ao Apple Developer, Xcode ou Expo e Sendrealm.
Push Notifications está habilitado no App ID e no target.
Key ID, Team ID, .p8, Bundle ID e ambiente APNs correspondem.
Expo usa development build, prebuild ou EAS, não Expo Go.
O iOS bare encaminha registro de token e respostas.
A inicialização ocorre uma vez.
O pedido de permissão segue uma explicação.
Login e logout seguem a sessão autenticada.
Deep links aplicam autorização normal.
Canais Android refletem a importância da mensagem.
A API key existe somente no backend.
Um Android controlado e um iPhone físico receberam testes.
Diagnósticos e resultados do backend estão disponíveis para suporte.
O time entende que aceitação não garante exibição.

Uma API pequena para um caminho completo

A API cotidiana do React Native permanece compacta: inicializar, pedir permissão, vincular o cliente, adicionar contexto observado, escutar aberturas e consultar diagnósticos. A complexidade que não pode desaparecer—autorização Firebase, credenciais APNs, capabilities, ambientes de build e comportamento dos provedores—fica explícita em vez de escondida.

É isso que torna o setup administrável em Expo e bare. O time usa um SDK React Native e uma API de backend sem abrir mão dos controles nativos de Android e iOS.

Comece pelo caminho adequado:

Depois que um dispositivo real funcionar de ponta a ponta, segmentação por identidade, audiências, campanhas, automações e jornadas combinando email e push podem usar o mesmo projeto Sendrealm.