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

A inicialização é feita via JavaScript: você define a configuração nativa (push, registro de logs, delegates) nos recursos do Android e no AppDelegate do iOS. Depois, chama Braze.initialize(apiKey, endpoint) a partir do 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 o tratamento personalizado por meio de inscrições e APIs de registro
• 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 (veja as notas de plataforma em Configuração nativa)
• Feature Flags: Atualize, leia propriedades e registre impressões
• Análise de dados: Eventos personalizados, compras e envio imediato (flush)
• Controles do SDK: Ative ou desative o SDK, apague dados locais e use assinaturas da autenticação do SDK

Pré-requisitos

• Conta 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 Gradle conforme exigido pelo seu modelo React Native
• Push (se usado): configuração do FCM (Android) e do APNs (iOS) conforme a documentação de push

Para saber onde encontrar 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.
2. Conclua a configuração nativa para Android e iOS (configuração, permissões e 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 do TypeScript já 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. Isso permite a reinicialização no meio da sessão.

Configuração nativa

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

Android

• Adicione o plugin Kotlin Gradle no seu build.gradle raiz, caso o seu 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 postergada para que o SDK aguarde o Braze.initialize() do JavaScript antes de iniciar. Os outros valores de configuração (push, tempo limite de sessão etc.) continuam sendo lidos desse arquivo e aplicados no momento da inicialização.
• Garanta permissões básicas, como INTERNET e ACCESS_NETWORK_STATE, no AndroidManifest.xml.
• Para push, conclua a integração do FCM e configure o ID do remetente e as flags de 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. Os closures que você fornecer são armazenados e aplicados depois, 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 (registro em log, push, sessões etc.). A chave de API e o endpoint vêm do JavaScript, então você não os define aqui.
• Closure postInitialization (opcional): recebe a instância ativa da 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 primeiro para Swift que substitui o BrazeReactBridge.initBraze(_:), que está obsoleto. 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, e 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:

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. Para todos os detalhes, consulte Braze.Configuration e os tipos aninhados api, push, logger e location.

A ponte do React Native define o api.sdkFlavor e os 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 ficam anexadas a essa 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 esse recurso estiver ativado 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 só para mostrar a interface padrão.
• Para um tratamento personalizado, faça a inscrição com useBrazeUI: false e, em seguida, registre impressões e 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 for aberto a partir de uma notificação para evitar condições de corrida com o Linking do RN. Exige 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 do 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();

Observação: logPurchase recebe o preço como string (consulte as tipagens).

Gerenciamento de dados e estado do SDK

changeUser só informa à Braze a qual ID de usuário atribuir as novas atividades. Ele não limpa os dados do SDK 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 deve usar wipeData(). Isso faz uma redefinição local completa.

1
2
3

Braze.wipeData();
Braze.disableSDK();
Braze.enableSDK();

wipeData(): limpa os dados locais da Braze nesta instalação (estado em cache de usuário, sessão e cartões, associação do token por push etc.). Use para um comportamento semelhante a logout quando você 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 desativação pelo 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 entrar em vigor até a próxima inicialização do app. Verifique a documentação Swift/iOS da Braze antes de contar com uma reativação imediata.

Eventos

Assine 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 nativa manual sempre que possível.
• Nova Arquitetura / Turbo Modules: compatível com as versões recentes do plugin. Se você fizer a migração, siga o guia do desenvolvedor e os exemplos de configuração do AppDelegate e do Gradle.
• Privacidade (iOS): métodos como updateTrackingPropertyAllowList oferecem suporte a configurações relacionadas ao manifesto de privacidade. Consulte Manifesto de privacidade do Swift.

- Jest: simule os módulos nativos do react-native ou o módulo Turbo da Braze. Os testes unitários não são publicados neste repositório.

Suporte a versões

Nota

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

A tabela a seguir lista as versões do React Native compatíveis com cada versão do plugin da Braze.

Respeite também os requisitos dos SDKs nativos:

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

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, cartões de conteúdo, 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

Durante o desenvolvimento, ative o registro de logs da Braze na configuração nativa para que o SDK grave 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 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 não detalhado ou remova a substituição antes do lançamento.

Para uma solução de problemas mais aprofundada (comportamento de rede, sessão ou Campaign), consulte o guia do desenvolvedor do React Native da Braze e os documentos 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 obter detalhes do repositório e projetos de exemplo, consulte https://github.com/braze-inc/braze-react-native-sdk.