Guia do repositório do React Native SDK

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 nativo e o SDK Android da Braze por trás de uma API JavaScript.

A inicialização é orientada por JavaScript: você configura a configuração nativa (push, logging, 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
• Mensagens no app: Interface padrão da Braze ou tratamento personalizado via inscrições e APIs de registro
• Content Cards: Interface de feed padrão, ou buscar cartões e criar 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 (consulte Configuração nativa)
• 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 modelo de 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, consulte 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 do 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 fornecidas com o pacote (src/index.d.ts no GitHub).

Chamar Braze.initialize novamente com credenciais diferentes encerra a instância atual e a recria, permitindo a reinicialização durante a sessão.

Configuração nativa

Fonte da verdade: 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 snippets a seguir são exemplos mínimos.

Android

• Adicione o plugin Kotlin do Gradle no seu build.gradle raiz se o seu template ainda não o incluir (as versões dependem da sua versão do React Native).
• Adicione um arquivo de recurso braze.xml em res/values com sua configuração. Ative a inicialização adiada para que o SDK aguarde o Braze.initialize() do JavaScript antes de iniciar. Outros valores de configuração (push, tempo limite da sessão, etc.) ainda são lidos desse arquivo e aplicados no momento da inicialização.
• Verifique se as permissões básicas, como INTERNET e ACCESS_NETWORK_STATE, estão no AndroidManifest.xml.
• Para push, conclua a integração do 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 do 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 a partir do 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 uma Braze.Configuration e permite definir propriedades de configuração nativa (registro de logs, push, sessões, etc.). A chave de API e o endpoint são fornecidos a partir do 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 ou definir delegates).

Nota

BrazeReactInitializer.configure é uma API pensada para Swift que substitui o método descontinuado 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 substituí-los na inicialização. A lista definitiva de chaves e tipos está no guia de integração do SDK para Android e em BrazeConfigurationProvider (cada propriedade Kotlin corresponde aos recursos documentados com_braze_*).

Entradas mais utilizadas:

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 no JavaScript. Detalhes completos: Braze.Configuration e tipos aninhados api, push, logger, location.

A ponte React Native define api.sdkFlavor / metadados do SDK específicos do React na inicialização; não substitua 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 associadas à mesma exportação.

Funcionalidades 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 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 de documentação do TypeScript e no app de exemplo.
• Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, ...) é exclusivo para Android de acordo com 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 encerramento de sessão 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 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 de usuário/sessão/cartão em cache, associação de token por push, etc.). Use para comportamento estilo encerramento de sessão quando você não deve deixar o estado da Braze do usuário anterior no dispositivo, além de fluxos de “excluir meus dados neste dispositivo”, redefinições de QA sem reinstalação 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 de SDK desativado); consulte a documentação nativa da Braze se você utilizar isso em produção.

disableSDK() — Interrompe a operação do SDK (sem coleta/encaminhamento conforme configurado). Use para alternadores de exclusão 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é o próximo lançamento do app; verifique na documentação do Braze Swift/iOS antes de depender de uma 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 função de 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 configurações manuais nativas 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 se você fizer a migração.
• Privacidade (iOS): métodos como updateTrackingPropertyAllowList oferecem suporte à configuração relacionada ao manifesto de privacidade; consulte o 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 exemplos de padrões).

Suporte a versões

Nota

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

A tabela a seguir lista as versões do React Native compatíveis por lançamento do plugin da Braze.

Respeite também os requisitos dos SDKs nativos:

• Informações sobre versões do SDK Android
• Informações sobre versões do SDK Swift

Plugin Braze Expo

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

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 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, as alterações de usuário e a 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 para os 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 não verboso 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 React Native da Braze 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 no 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.