Guia do repositório do SDK React Native
Sobre o SDK React Native da Braze
O SDK React Native da Braze conecta seus apps iOS e Android à Braze: perfis de usuário, superfícies de envio de mensagens, análise de dados e Feature Flags. Ele encapsula o SDK Swift da Braze e o SDK Android da Braze nativos em uma API JavaScript.
A inicialização é feita via JavaScript: você define a configuração nativa (push, registro em log, delegates) nos recursos do Android e no AppDelegate do iOS. Depois, chama Braze.initialize(apiKey, endpoint) no JavaScript para iniciar o SDK. Assim, você tem controle total sobre quando o SDK é inicializado e com quais credenciais. Após a inicialização, chame outros métodos do SDK (por exemplo, changeUser, logCustomEvent) conforme necessário.
O que você pode fazer
- Gerenciamento de usuários: Identifique usuários e defina campos de perfil, atributos personalizados, aliases e grupos de inscrições
- Mensagens no app: Use a interface padrão da Braze ou faça um tratamento personalizado com inscrições e APIs de registro em log
- Content Cards: Use a interface de feed padrão ou busque os cartões e crie sua própria interface
- Banners: Banners HTML baseados em posicionamento, incluindo
BrazeBannerView - Notificações por push: Solicitações de permissão, registro de tokens e listeners de carga útil (consulte Notificações por push)
- Feature Flags: Atualize, leia propriedades e registre impressões
- Análise de dados: Eventos personalizados, compras e envio imediato de dados (flush)
- Controles do SDK: Ative ou desative o SDK, apague dados locais e use assinaturas de autenticação do SDK
Pré-requisitos
- Conta da Braze com chave de API do app e endpoint do SDK
- Ambiente de desenvolvimento React Native (configuração do ambiente React Native)
- iOS: Xcode, CocoaPods (
cd ios && pod install) - Android: Android Studio / Gradle; plugin Kotlin para Gradle, conforme exigido pelo seu modelo React Native
- Push (se usado): configuração do FCM (Android) e do APNs (iOS), de acordo com a documentação de push
Para saber onde encontrar as credenciais no dashboard, consulte a visão geral da integração.
Instalação
npm install @braze/react-native-sdk
# or:
# yarn add @braze/react-native-sdk
Início rápido
Esta seção mostra a configuração mínima necessária para inicializar o SDK React Native da Braze.
- Instale o pacote npm.
- Conclua a configuração nativa para Android e iOS (configuração, permissões e push, se necessário).
- Inicialize o SDK pelo JavaScript e comece a usá-lo:
import Braze from "@braze/react-native-sdk";
// Initialize the SDK — call early in your app lifecycle (e.g. in a useEffect).
// The API key and endpoint are passed from JavaScript; native configuration
// (push, logging, etc.) is applied automatically from your native setup.
Braze.initialize("<YOUR_API_KEY>", "<YOUR_SDK_ENDPOINT>");
Braze.changeUser("user-123");
Braze.logCustomEvent("button_clicked", { screen: "home" });
As tipagens do TypeScript vêm incluídas no pacote (src/index.d.ts no GitHub).
Chamar Braze.initialize novamente com credenciais diferentes encerra a instância atual e a recria, o que permite reinicializar o SDK no meio da sessão.
Configuração nativa
Fonte de verdade: As telas passo a passo, as alterações no Gradle/CocoaPods e a lista completa de chaves XML do Android estão no guia do desenvolvedor React Native da Braze. Os snippets abaixo são exemplos mínimos.
Android
- Adicione o plug-in Kotlin Gradle ao seu
build.gradleraiz, caso seu modelo ainda não o inclua. As versões dependem da sua versão do React Native. - Adicione um arquivo de recurso
braze.xmlemres/valuescom a sua configuração. Ative a inicialização postergada para que o SDK aguarde a chamadaBraze.initialize()do JavaScript antes de iniciar. Os outros valores de configuração (push, tempo limite da sessão etc.) continuam sendo lidos desse arquivo e aplicados no momento da inicialização. - Inclua as permissões básicas, como
INTERNETeACCESS_NETWORK_STATE, noAndroidManifest.xml. - Para push, conclua a integração com o FCM e configure o ID do remetente e as flags de registro específicas da Braze descritas na documentação.
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Enable delayed initialization so the SDK starts when
Braze.initialize() is called from JavaScript. -->
<bool name="com_braze_enable_delayed_initialization">true</bool>
<!-- Additional native configuration (applied at initialization time) -->
<bool name="com_braze_firebase_cloud_messaging_registration_enabled">true</bool>
<string translatable="false" name="com_braze_firebase_cloud_messaging_sender_id">YOUR_SENDER_ID</string>
</resources>

A chave de API e o endpoint não são mais definidos no braze.xml. Agora, eles são enviados pelo JavaScript via Braze.initialize(apiKey, endpoint).
iOS
cd ios && pod install
Use BrazeReactInitializer.configure no seu AppDelegate para registrar a configuração nativa. As closures que você fornecer ficam armazenadas e são aplicadas depois, quando Braze.initialize(apiKey, endpoint) é chamado pelo JavaScript.
import BrazeKit
import braze_react_native_sdk
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
static var braze: Braze? = nil
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
// Register native configuration for when JS calls Braze.initialize().
BrazeReactInitializer.configure { config in
config.logger.level = .info
config.push.automation = true
} postInitialization: { braze in
AppDelegate.braze = braze
}
// ... React Native setup
return true
}
}
- Closure
configure: recebe umBraze.Configuratione permite definir as propriedades da configuração nativa (registro em log, push, sessões etc.). A chave de API e o endpoint são fornecidos pelo JavaScript, então você não precisa defini-los aqui. - Closure
postInitialization(opcional): recebe a instância ativa deBrazeapós a criação, para configurações que exigem a instância (por exemplo, armazenar uma referência ou definir delegates).

BrazeReactInitializer.configure é uma API pensada primeiro para Swift que substitui o BrazeReactBridge.initBraze(_:), que foi descontinuado. Ela também resolve um problema de resolução de tipos do Swift com Braze.Configuration na ponte Objective-C.
Referência de configuração
No React Native, a configuração é nativa: o Android lê res/values/braze.xml, e o iOS usa closures registradas via BrazeReactInitializer.configure. Ambas são aplicadas quando Braze.initialize(apiKey, endpoint) é chamado a partir do JavaScript.
Android (braze.xml)
Os valores padrão ficam no XML. O BrazeConfig.Builder pode substituí-los na inicialização. A lista oficial de chaves e tipos está no guia de integração do SDK para Android e em BrazeConfigurationProvider (cada propriedade Kotlin corresponde a recursos com_braze_* documentados).
Entradas mais usadas:
| Chave | Tipo de recurso | Descrição |
|---|---|---|
com_braze_enable_delayed_initialization |
bool |
Obrigatória. Defina como true para que o SDK aguarde Braze.initialize() a partir do JavaScript. |
com_braze_api_key |
string |
Não é necessária ao usar Braze.initialize() a partir do JavaScript (as credenciais são passadas pelo JS). Só é obrigatória para a inicialização legada com prioridade nativa. |
com_braze_custom_endpoint |
string |
Não é necessária ao usar Braze.initialize() a partir do JavaScript. Só é obrigatória para a inicialização legada com prioridade nativa. |
com_braze_server_target |
string |
Seletor opcional de cluster ou ambiente (por exemplo, em algumas compilações internas ou de staging). Prefira com_braze_custom_endpoint em produção, a menos que sua integração com a Braze especifique outra coisa. |
com_braze_firebase_cloud_messaging_registration_enabled |
bool |
Quando true, a Braze faz o registro no FCM (configuração típica de push). |
com_braze_firebase_cloud_messaging_sender_id |
string |
ID de remetente do FCM quando o registro automático está ativado. |
com_braze_handle_push_deep_links_automatically |
bool |
Permite que a Braze abra deep links de push automaticamente. |
com_braze_trigger_action_minimum_time_interval_seconds |
integer |
Mínimo de segundos entre ações-gatilho de mensagens no app. |
| Outras | diversos | Chaves adicionais não mostradas aqui (tempo limite de sessão, geofences, local, padrões de notificação, listas de permissões de dispositivos, inicialização postergada, autenticação do SDK e mais). Consulte BrazeConfigurationProvider e o guia de integração do SDK para Android. |
iOS (Braze.Configuration)
Defina as propriedades de configuração nativas na closure configure passada para BrazeReactInitializer.configure. A closure recebe uma instância de Braze.Configuration. A chave de API e o endpoint são definidos automaticamente pela chamada Braze.initialize no JavaScript. Detalhes completos: Braze.Configuration e os tipos aninhados api, push, logger e location.
| Área | Membros (representativos) | Notas |
|---|---|---|
| Credenciais | api.key, api.endpoint |
Definidos automaticamente por Braze.initialize(apiKey, endpoint) no JavaScript. Não os defina na closure configure. |
| Registro de logs | logger.level |
O registro detalhado é para desenvolvimento. Reduza o ruído em produção. |
| Push | push.automation, push.appGroup, … |
A automação simplifica o registro. appGroup é necessário para Push Stories e extensões, quando usadas. |
| Mensagens no app | triggerMinimumTimeInterval |
Padrão de 30 segundos entre disparos. |
| Sessões | sessionTimeout |
Tempo de inatividade antes de uma nova sessão (consulte a documentação de sessões da Braze). |
| Privacidade e dados | api.trackingPropertyAllowList, devicePropertyAllowList, api.sdkAuthentication |
Alinhe com o manifesto de privacidade e com as configurações do produto de autenticação do SDK. |
| Rede | api.requestPolicy, api.flushInterval |
Política de novas tentativas de solicitação e frequência de envio. |
| Inscrição em push | optInWhenPushAuthorized |
Quando true, a inscrição pode passar para opt-in depois que o usuário autoriza as notificações. |
| Mensagens no app e mudanças de usuário | preventInAppMessageDisplayForDifferentUser |
Reduz mensagens no app exibidas para o usuário errado se o ID do usuário mudar. |
| Outros | forwardUniversalLinks, ephemeralEvents, useUUIDAsDeviceId, … |
Consulte a documentação do Swift para ver o comportamento completo. |
A ponte do React Native define o api.sdkFlavor e outros metadados do SDK específicos do React na inicialização. Não os substitua, a menos que a documentação da Braze instrua você a fazer isso.
API JavaScript / TypeScript
A exportação padrão do pacote é a classe Braze com métodos estáticos (por exemplo, Braze.changeUser, Braze.logPurchase). Constantes como Braze.Events, Braze.Genders e Braze.NotificationSubscriptionTypes estão vinculadas à mesma exportação.
Recursos principais
Gerenciamento de usuários
import Braze from "@braze/react-native-sdk";
Braze.changeUser("user-123");
Braze.setEmail("[email protected]");
Braze.setCustomUserAttribute("plan", "premium");
Braze.addAlias("external_id", "marketing_id");
Braze.addToSubscriptionGroup("NEWSLETTER_GROUP_UUID");
Autenticação do SDK opcional: passe uma assinatura como segundo argumento de changeUser ou chame Braze.setSdkAuthenticationSignature(signature) quando ela estiver ativada no dashboard.
Mensagens no app
- Com a interface padrão da Braze, siga a documentação de mensagens no app. Normalmente, você não precisa chamar
subscribeToInAppMessageapenas para mostrar a interface padrão. - Para um tratamento personalizado, faça a inscrição com
useBrazeUI: falsee registre as impressões e os cliques conforme necessário:
Braze.subscribeToInAppMessage(false, (event) => {
const msg = event.inAppMessage;
// Render your own UI from msg.message, msg.buttons, etc.
Braze.logInAppMessageImpression(msg);
});
Content Cards
const cards = await Braze.getCachedContentCards();
Braze.requestContentCardsRefresh();
Braze.launchContentCards(); // default Braze UI
Braze.logContentCardImpression(cardId);
Braze.logContentCardClicked(cardId);
Ouça as atualizações com Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, ...).
Banners
import Braze from "@braze/react-native-sdk";
Braze.requestBannersRefresh(["homepage_banner"]);
const banner = await Braze.getBanner("homepage_banner");
// Or use the native Banner view:
// <Braze.BrazeBannerView placementId="homepage_banner" />
Notificações por push
Braze.requestPushPermission({
alert: true,
badge: true,
sound: true,
});
// Token registration is usually handled natively; see docs for your setup.
Braze.registerPushToken(token);
getInitialPushPayload: use quando o app for aberto a partir de uma notificação para evitar condições de corrida com oLinkingdo RN. Ele exige configuração nativa em cada plataforma.- iOS, com as opções de inicialização do app delegate: chame
populateInitialPayloadFromLaunchOptions:emBrazeReactUtilsa partir deapplication:didFinishLaunchingWithOptions:. - iOS, com o ciclo de vida de cenas: chame
populateInitialPayloadFromNotificationResponse:emBrazeReactUtilsa partir descene:willConnectToSession:options:. - Android: chame
BrazeReactUtils.populateInitialPushPayloadFromIntenta partir deMainActivity.onCreate().
- iOS, com as opções de inicialização do app delegate: chame
Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, ...)é exclusivo do Android, de acordo com as tipagens públicas.
Feature Flags
const flag = await Braze.getFeatureFlag("new_checkout");
if (flag?.enabled) {
const rollout = flag.getNumberProperty("rollout_percentage") ?? 0;
}
Braze.refreshFeatureFlags();
Braze.logFeatureFlagImpression("new_checkout");
Análise de dados e compras
Braze.logCustomEvent("purchase_completed", { sku: "sku-1" });
Braze.logPurchase("sku-1", "29.99", "USD", 1, { source: "cart" });
Braze.requestImmediateDataFlush();
Nota: logPurchase recebe o preço como string (veja as tipagens).
Gerenciamento de dados e estado do SDK
changeUser apenas informa à Braze a qual ID de usuário atribuir as novas atividades. Ele não limpa os dados do SDK armazenados em cache no dispositivo. Não existe uma API de “logout” separada. Se você precisar de um logout tradicional (limpar o estado local da Braze para que o perfil, as mensagens e os tokens em cache do usuário anterior sejam removidos desta instalação), normalmente use wipeData(). Essa é uma redefinição local completa.
Braze.wipeData();
Braze.disableSDK();
Braze.enableSDK();
wipeData(): limpa os dados locais da Braze nesta instalação (estado de usuário, sessão e cartões em cache, associação do token por push etc.). Use para um comportamento semelhante a logout quando não puder deixar o estado da Braze do usuário anterior no dispositivo. Também serve para “excluir meus dados neste dispositivo”, redefinições de QA sem reinstalar o app ou fluxos rigorosos de privacidade. changeUser sozinho não faz essa limpeza. Ele apenas define qual ID de usuário recebe os novos eventos. No iOS, o comportamento pode ser diferente do Android (por exemplo, na interação com o estado de SDK desativado). Consulte a documentação nativa da Braze se for usar isso em produção.
disableSDK(): interrompe o funcionamento do SDK (sem coleta nem encaminhamento, conforme configurado). Use para opções de opt-out do usuário, modos restritos (conformidade, configurações para crianças) ou depuração sem remover a dependência.
enableSDK(): reativa o SDK depois de disableSDK(). No iOS, a reativação pode não ter efeito até a próxima inicialização do app. Verifique a documentação da Braze para Swift/iOS antes de contar com a reativação imediata.
Eventos
Inscreva-se com Braze.addListener(event, callback). A chamada retorna um objeto de inscrição; chame .remove() nele para parar de ouvir.
Configurando um listener:
import Braze from "@braze/react-native-sdk";
const subscription = Braze.addListener(
Braze.Events.CONTENT_CARDS_UPDATED,
(update) => {
console.log("Content cards:", update.cards);
}
);
Removendo o listener:
subscription.remove();
Em um componente React, armazene a inscrição e chame .remove() na sua limpeza (por exemplo, no retorno de um useEffect):
useEffect(() => {
const sub = Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, (update) => {
setCards(update.cards);
});
return () => sub.remove();
}, []);
| Constante do evento | Carga útil (resumo) |
|---|---|
Braze.Events.CONTENT_CARDS_UPDATED |
Content Cards mais recentes |
Braze.Events.BANNER_CARDS_UPDATED |
Banners mais recentes |
Braze.Events.FEATURE_FLAGS_UPDATED |
Array de Feature Flags |
Braze.Events.IN_APP_MESSAGE_RECEIVED |
Evento de mensagem no app |
Braze.Events.SDK_AUTHENTICATION_ERROR |
Detalhes do erro de autenticação do SDK |
Braze.Events.PUSH_NOTIFICATION_EVENT |
Carga útil do push (somente Android) |
Notas de integração
- Expo: use o plugin Braze Expo para evitar a configuração nativa manual sempre que possível.
- Nova arquitetura / Turbo Modules: compatíveis com as versões recentes do plugin. Se você fizer a migração, siga o guia do desenvolvedor e as configurações de exemplo de
AppDelegatee Gradle. - Privacidade (iOS): métodos como
updateTrackingPropertyAllowListoferecem suporte a configurações relacionadas ao manifesto de privacidade. Consulte o manifesto de privacidade do Swift.
- Jest: simule os módulos nativos do react-native ou o módulo Turbo da Braze. Os testes de unidade não são publicados neste repositório.
Suporte a versões

Este SDK foi testado com a versão 0.88.0 do React Native.
A tabela a seguir lista as versões do React Native compatíveis com cada versão do plugin da Braze.
| Plugin da Braze | React Native | Nova Arquitetura |
|---|---|---|
| 9.0.0+ | ≥ 0.71 | Sim |
| 6.0.0+ | ≥ 0.68 | Sim (≥ 0.70.0) |
| 2.0.0+ | ≥ 0.68 | Sim |
| ≤ 1.41.0 | ≤ 0.71 | Não |
Respeite também os requisitos dos SDKs nativos:
Plugin Braze Expo
Para fluxos de trabalho gerenciados pelo Expo, consulte o repositório do plugin Braze Expo.
App de exemplo
O BrazeProject neste repositório é um exemplo completo (gerenciamento de usuários, Content Cards, Feature Flags, banners etc.).
cd BrazeProject/
yarn install
npx react-native start
iOS (a partir de BrazeProject):
cd ios && pod install && cd ..
npx react-native run-ios
Use RCT_NEW_ARCH_ENABLED=0 pod install se precisar da arquitetura legada.
Android (a partir de BrazeProject):
npx react-native run-android
Depuração e solução de problemas
Ative o registro de logs da Braze na configuração nativa durante o desenvolvimento para que o SDK escreva no console do sistema (Xcode / Android Logcat). Isso ajuda a verificar a inicialização, as mudanças de usuário e a entrega de eventos.
- iOS — No closure
configurepassado paraBrazeReactInitializer.configure, definaconfig.logger.level = .debug(ou.info). Reduza ou desative em produção para que os logs não fiquem visíveis para os usuários. - Android — Use o recurso
com_braze_logger_initial_log_levelembraze.xmlou defina o equivalente emBrazeConfig.Builder(veja BrazeConfigurationProvider). Use um nível menos detalhado ou remova a substituição antes do lançamento.
Para uma solução de problemas mais aprofundada (comportamento de rede, sessão ou campanha), consulte o guia do desenvolvedor React Native da Braze e a documentação do SDK nativo (Swift · Android).
Recursos adicionais
- Guia do desenvolvedor da Braze: React Native
- Notificações por push: React Native
- Repositório no GitHub
- Pacote npm
Contato
Em caso de dúvidas, entre em contato com o suporte técnico da Braze para obter ajuda.
Para detalhes do repositório e projetos de exemplo, consulte https://github.com/braze-inc/braze-react-native-sdk.