Guia do repositório do React Native SDK

Sobre o Braze React Native SDK

O Braze React Native SDK 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 os SDKs nativos Braze Swift SDK e Braze Android SDK por trás de uma API JavaScript.

A inicialização é orientada por JavaScript: você configura a configuração nativa (push, registro de logs, delegates) nos recursos do Android e no AppDelegate do iOS, e então chama Braze.initialize(apiKey, endpoint) a partir do JavaScript para iniciar o SDK. Isso dá a você 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: Identificar usuários, definir campos de perfil, atributos personalizados, aliases e grupos de inscrições
• In-App Messages: Interface padrão da Braze ou tratamento personalizado via inscrições e APIs de registro
• Content Cards: Interface de feed padrão, ou busque 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 token, listeners de carga útil (veja Notificações por push)
• Feature Flags: Atualizar, ler propriedades, registrar impressões
• Análise de dados: Eventos personalizados, compras, envio imediato
• Controles do SDK: Ativar/desativar o SDK, limpar dados locais, assinaturas de autenticação do SDK

Pré-requisitos

• Conta na Braze com chave de API do app e endpoint de 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 Gradle conforme exigido pelo seu template React Native
• Push (se utilizado): configuração do FCM (Android) e APNs (iOS) conforme a documentação de push

Para localizar as credenciais no dashboard, siga a visão geral da integração.

Instalação

1
2
3
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.

1. Instale o pacote npm (consulte Instalação).
2. Conclua a configuração nativa para Android e iOS (configuração, permissões, push se necessário).
3. Inicialize o SDK a partir do JavaScript e comece a usá-lo:

1
2
3
4
5
6
7
8
9
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 TypeScript são incluídas no pacote (src/index.d.ts no GitHub).

Chamar Braze.initialize novamente com credenciais diferentes destrói a instância atual e a recria, suportando reinicialização no meio da sessão.

Configuração nativa

Fonte oficial: Telas passo a passo, alterações no Gradle/CocoaPods e a lista completa de chaves XML do Android estão no guia do desenvolvedor Braze React Native. Os trechos a seguir são exemplos mínimos.

Android

• Adicione o plugin Kotlin Gradle no seu build.gradle raiz, caso o modelo ainda não o inclua (as versões dependem da sua versão do React Native).
• Adicione um arquivo de recurso braze.xml em res/values com a sua configuração. Ative a inicialização atrasada para que o SDK aguarde a chamada Braze.initialize() do JavaScript antes de iniciar. Outros valores de configuração (push, tempo limite de sessão etc.) ainda são lidos neste arquivo e aplicados no momento da inicialização.
• Verifique se as permissões básicas, como INTERNET e ACCESS_NETWORK_STATE, estão declaradas no AndroidManifest.xml.
• Para push, conclua a integração com o FCM e quaisquer flags de ID de remetente / registro específicas da Braze descritas na documentação.

1
2
3
4
5
6
7
8
9
10
<?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>

Nota

A chave de API e o endpoint não são mais definidos no braze.xml — eles são passados pelo JavaScript via Braze.initialize(apiKey, endpoint).

iOS

1
cd ios && pod install

Use BrazeReactInitializer.configure no seu AppDelegate para registrar a configuração nativa. As closures que você fornece são armazenadas e aplicadas posteriormente quando Braze.initialize(apiKey, endpoint) é chamado pelo JavaScript.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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 um Braze.Configuration e permite definir propriedades de configuração nativa (log, push, sessões etc.). A chave de API e o endpoint são fornecidos pelo JavaScript — você não os define aqui.
• Closure postInitialization (opcional): recebe a instância ativa de Braze após a criação, para configurações que exigem a instância (por exemplo, armazenar uma referência, definir delegates).

Nota

BrazeReactInitializer.configure é uma API voltada para Swift que substitui a deprecated BrazeReactBridge.initBraze(_:). Ela também resolve um problema de resolução de tipo Swift com Braze.Configuration na bridge 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 em XML; BrazeConfig.Builder pode sobrescrevê-los na inicialização. A lista oficial de chaves e tipos está no guia de integração do SDK Android e em BrazeConfigurationProvider (cada propriedade Kotlin corresponde aos recursos documentados com_braze_*).

Entradas mais usadas:

iOS (Braze.Configuration)

Defina as propriedades de configuração nativa 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 a partir da chamada Braze.initialize do JavaScript. Detalhes completos: Braze.Configuration e tipos aninhados api, push, logger, location.

O bridge do React Native define api.sdkFlavor / metadados do SDK específicos do React na inicialização; não sobrescreva esses valores a menos que a documentação da Braze instrua você a fazê-lo.

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

1
2
3
4
5
6
7
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 para changeUser, ou chame Braze.setSdkAuthenticationSignature(signature) quando habilitado 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 subscribeToInAppMessage apenas para exibir a interface padrão.
• Para tratamento personalizado, inscreva-se com useBrazeUI: false e registre impressões/cliques conforme necessário:

1
2
3
4
5
Braze.subscribeToInAppMessage(false, (event) => {
  const msg = event.inAppMessage;
  // Render your own UI from msg.message, msg.buttons, etc.
  Braze.logInAppMessageImpression(msg);
});

Content Cards

1
2
3
4
5
6
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

1
2
3
4
5
6
7
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

1
2
3
4
5
6
7
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 é aberto a partir de uma notificação para evitar condições de corrida do RN Linking; requer hooks nativos (BrazeReactUtils no iOS, BrazeReactUtils.populateInitialPushPayloadFromIntent no Android) conforme descrito nos comentários da documentação TypeScript e no app de exemplo.
• Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, ...) é exclusivo para Android conforme as tipagens públicas.

Feature Flags

1
2
3
4
5
6
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

1
2
3
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 (consulte as tipagens).

Gerenciamento de dados e estado do SDK

changeUser apenas informa à Braze qual ID de usuário deve receber a atribuição de novas atividades. Ele não limpa os dados do SDK armazenados em cache no dispositivo. Não existe uma API separada de “logout”: se você precisa de um processo tradicional de encerramento de sessão (limpar o estado local da Braze para que o perfil em cache, as mensagens e os tokens do usuário anterior sejam removidos desta instalação), normalmente você usa wipeData(). Isso é uma redefinição local completa.

1
2
3
Braze.wipeData();
Braze.disableSDK();
Braze.enableSDK();

wipeData() — Limpa os dados locais da Braze para esta instalação (estado em cache de usuário/sessão/cartão, associação de token por push, etc.). Use para comportamento de encerramento de sessão quando você não deve deixar o estado da Braze do usuário anterior no dispositivo, além de “excluir meus dados neste dispositivo”, redefinições de QA sem reinstalar ou fluxos rigorosos de privacidade. changeUser sozinho não realiza essa limpeza — ele apenas define qual ID de usuário recebe novos eventos. No iOS, o comportamento pode diferir do Android (por exemplo, interação com o estado do SDK desabilitado); consulte a documentação nativa da Braze se você usar isso em produção.

disableSDK() — Interrompe a operação do SDK (sem coleta/encaminhamento conforme configurado). Use para alternadores de opt-out do usuário, modos restritos (conformidade, configurações infantis) ou depuração sem remover a dependência.

enableSDK() — Reativa o SDK após disableSDK(). No iOS, a reativação pode não ser aplicada até a próxima inicialização do app; verifique na documentação do Braze Swift/iOS antes de depender da 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:

1
2
3
4
5
6
7
8
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:

1
subscription.remove();

Em um componente React, armazene a inscrição e chame .remove() na sua limpeza (por exemplo, no retorno de um useEffect):

1
2
3
4
5
6
useEffect(() => {
  const sub = Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, (update) => {
    setCards(update.cards);
  });
  return () => sub.remove();
}, []);

Notas de integração

• Expo: use o plugin Braze Expo para evitar a configuração manual nativa sempre que possível.
• New Architecture / Turbo Modules: compatível com versões recentes do plugin; siga o guia do desenvolvedor e as configurações de exemplo do AppDelegate / Gradle caso você migre.
• Privacidade (iOS): métodos como updateTrackingPropertyAllowList oferecem suporte à configuração relacionada ao manifesto de privacidade; consulte Manifesto de privacidade do Swift.
• Jest: faça mock dos módulos nativos do react-native ou do Turbo module da Braze (consulte __tests__/jest.setup.js neste repositório para ver exemplos de padrões).

Suporte de versão

Nota

Este SDK foi testado com a versão 0.85.3 do React Native.

A tabela a seguir lista as versões do React Native suportadas por versão do plugin da Braze.

Respeite também os requisitos do SDK nativo:

• Informações de versão do Android SDK
• Informações de versão do Swift SDK

Plugin Expo da Braze

Para fluxos de trabalho gerenciados pelo Expo, consulte o repositório do plugin Expo da Braze.

App de exemplo

BrazeProject neste repositório é um exemplo completo (gerenciamento de usuários, Content Cards, Feature Flags, banners, etc.).

1
2
3
cd BrazeProject/
yarn install
npx react-native start

iOS (a partir de BrazeProject):

1
2
cd ios && pod install && cd ..
npx react-native run-ios

Use RCT_NEW_ARCH_ENABLED=0 pod install se você precisar da arquitetura legada.

Android (a partir de BrazeProject):

1
npx react-native run-android

Depuração e solução de problemas

Ative o registro de log 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, mudanças de usuário e entrega de eventos.

• iOS — No closure configure passado para BrazeReactInitializer.configure, defina config.logger.level = .debug (ou .info). Reduza ou desative em produção para que os logs não fiquem visíveis aos usuários.
• Android — Use o recurso com_braze_logger_initial_log_level em braze.xml ou defina o equivalente em BrazeConfig.Builder (consulte BrazeConfigurationProvider). Use um nível menos detalhado ou remova a substituição antes do lançamento.

Para uma solução de problemas mais aprofundada (rede, sessão ou comportamento de Campaign), consulte o guia do desenvolvedor Braze para React Native e a documentação dos SDKs nativos (Swift · Android).

Recursos adicionais

• Guia do desenvolvedor da Braze — React Native
• Notificações por push — React Native
• Repositório GitHub
• Pacote npm

Contato

Para dúvidas, entre em contato com o suporte técnico da Braze para obter assistência.

Para detalhes do repositório e projetos de exemplo, consulte https://github.com/braze-inc/braze-react-native-sdk.