Integrate Bro into your app.

SDKs for Web and React Native. Analytics, user identification, and push notifications — all in one platform.

Getting Started Web SDK React Native SDK Web Push Mobile Push Transactional Push API Reference

Quickstart

Getting Started

Install the SDK for your platform:

Terminal

# Web (React, Next.js, Vite, etc.)
npm install @bro-sdk/web

# React Native
npm install @bro-sdk/react-native

You will need two values from the Bro dashboard:

API Key

Settings → App → API Key

bro_pk_xxxxxxxxxxxx

VAPID Public Key

Settings → App → VAPID Public Key

Required for web push only

Web

Web SDK

Initialize

Call createBro() once at app startup. It returns a singleton — use getBro() to access it from anywhere.

app.tsx

import { createBro } from '@bro-sdk/web'

const bro = createBro({
  apiKey: 'bro_pk_xxxxxxxxxxxx',
  autoPageView: true,    // automatic page views
  trackClicks: true,     // automatic click tracking
})

Track Events

anywhere.ts

bro.track('purchase', {
  amount: 99.90,
  currency: 'BRL'
})

Identify Users

after-login.ts

bro.identify('user-123', {
  name: 'Augusto',
  plan: 'pro'
})

Use Anywhere

Access the same instance from any file with getBro():

other-file.ts

import { getBro } from '@bro-sdk/web'

const bro = getBro()

Mobile

React Native SDK

Initialize

The React Native SDK uses an async initializer. Call it once at app startup (e.g. in App.tsx).

App.tsx

import { createBro } from '@bro-sdk/react-native'

await createBro({
  apiKey: 'bro_pk_xxxxxxxxxxxx',
  appVersion: '1.0.0'
})

Screen Tracking

ProductScreen.tsx

import { getBro } from '@bro-sdk/react-native'

const bro = getBro()
bro.screen('ProductScreen')

track() and identify() work the same as the Web SDK.

Push Notifications

Web Push

Web push requires three steps. All three are required — skipping any one will result in push not working.

Common mistake: initializing with webPush: true but forgetting to call subscribeToPush(). The init only registers the service worker — you must explicitly call subscribeToPush() to prompt the user and register the token.

1Copy the service worker

Copy bro-sw.js from the SDK package to your project's public/ folder. This file must be served at the root of your domain (e.g. https://yoursite.com/bro-sw.js).

Terminal

cp node_modules/@bro-sdk/web/bro-sw.js public/bro-sw.js

The service worker handles receiving and displaying push notifications in the background. Without it, the browser can't show notifications.

2Initialize with push enabled

Pass webPush: true and your VAPID public key to createBro().

app.tsx

import { createBro } from '@bro-sdk/web'

const bro = createBro({
  apiKey: 'bro_pk_xxxxxxxxxxxx',
  webPush: true,
  vapidPublicKey: 'your-vapid-public-key'
})

This step only registers the service worker and checks for existing subscriptions. It does not prompt the user for notification permission.

3Subscribe to push

Call subscribeToPush() to actually register the browser. This is what prompts the user for permission, creates the push subscription, and registers the token with the Bro backend.

app.tsx

const subscription = await bro.subscribeToPush()

if (subscription) {
  // Push enabled — token registered with Bro
} else {
  // User denied or browser doesn't support push
}

Common patterns

Subscribe on page load:

app.tsx

const bro = createBro({
  apiKey: 'bro_pk_xxxxxxxxxxxx',
  webPush: true,
  vapidPublicKey: 'your-vapid-public-key'
})

bro.subscribeToPush()

Subscribe on button click:

component.tsx

async function enableNotifications() {
  const bro = getBro()
  const sub = await bro.subscribeToPush()
  if (sub) showToast('Notifications enabled!')
}

Other push methods

push-utils.ts

// Check permission status
const permission = await bro.getPushPermission()
// 'granted' | 'denied' | 'default'

// Unsubscribe
await bro.unsubscribeFromPush()

Push Notifications

Mobile Push (React Native)

For React Native, use Firebase Cloud Messaging (FCM) tokens. FCM tokens work for both Android and iOS.

push-setup.ts

import messaging from '@react-native-firebase/messaging'
import { getBro } from '@bro-sdk/react-native'

// Get FCM token
const token = await messaging().getToken()

// Register with Bro
const bro = getBro()
await bro.registerPushToken(token)

// Unregister on logout
await bro.unregisterPushToken(token)

Push Notifications

Transactional Push (Server)

Send a push to a single user from your backend — order shipped, password reset, daily reminder, etc. Authenticate with your app's Secret Key (bro_sk_*) in the x-bro-secret header. Bro figures out which devices the user has registered (web, FCM, APNS) and dispatches to all of them.

Use the Secret Key, not the API Key. The API Key (bro_pk_*) ships in your browser bundle and is public — anyone can read it. The Secret Key is server-only. Find it in Settings → App → Secret Key. If it has ever been exposed in client code, rotate it.

Endpoint

HTTP

POST https://bro.linhares.sc/api/v1/push/transactional

Example

Terminal

curl -X POST https://bro.linhares.sc/api/v1/push/transactional \
  -H "Content-Type: application/json" \
  -H "x-bro-secret: bro_sk_xxxxxxxxxxxx" \
  -d '{
    "userId": "user-123",
    "title": "Your order has shipped",
    "body": "Tracking #BR-9182 — arriving Friday",
    "url": "https://yoursite.com/orders/9182"
  }'

Body

Field	Type	Description
userId	string	Required if anonymousId is not set. The identified user.
anonymousId	string	Required if userId is not set. The pre-login id.
title	string	Required. Max 200 chars.
body	string	Required. Max 1000 chars.
url	string	Optional. URL to open when the notification is tapped.
image	string	Optional. URL of an image to show in the notification.

Response

200 OK

{
  "success": true,
  "stats": { "sent": 2, "delivered": 2, "failed": 0 }
}

Returns 404 if the user has no active push tokens registered, 401 for an invalid or missing key, 429 if you are rate limited.

Reference

API Reference

@bro-sdk/web

Method	Description
createBro(config)	Initialize SDK (singleton)
getBro()	Get existing instance
track(event, props?)	Track custom event
identify(userId, traits?)	Identify user
subscribeToPush()	Subscribe to web push
unsubscribeFromPush()	Unsubscribe from web push
getPushPermission()	Get notification permission status
flush()	Flush event queue immediately

@bro-sdk/react-native

Method	Description
createBro(config)	Initialize SDK (async, singleton)
getBro()	Get existing instance
track(event, props?)	Track custom event
screen(name, props?)	Track screen view
identify(userId, traits?)	Identify user
registerPushToken(token)	Register FCM/APNS token
unregisterPushToken(token)	Unregister push token
flush()	Flush event queue immediately