@bro-sdk/web

Web SDK for Bro — open-source analytics & push notifications platform.

Install

npm install @bro-sdk/web

Quick Start

import { createBro } from "@bro-sdk/web";

const bro = createBro({
  apiKey: "bro_pk_xxxxxxxxxxxx",
});

// Track events
bro.track("purchase", { amount: 99.90, currency: "BRL" });

// Identify users
bro.identify("user-123", {
  name: "Augusto",
  email: "[email protected]",
});

Use anywhere with getBro()

Initialize once at the app entry point, then access from any file:

// components/checkout.ts
import { getBro } from "@bro-sdk/web";

const bro = getBro();
bro.track("checkout_started", { cart_size: 3 });

Features

• Auto page views — tracks navigation automatically (SPA-friendly, intercepts pushState + popstate)
• Event batching — queues events and sends in batches (20 events or every 5s)
• Session tracking — automatic 30-minute inactivity-based sessions
• User identity — anonymous IDs persisted in localStorage + identified users with traits
• Web Push — VAPID-based push notifications (no Firebase needed)
• Click tracking — optional automatic click tracking on links/buttons
• Offline resilience — failed batches are re-queued for retry
• Tiny footprint — ~6KB minified

Configuration

const bro = createBro({
  apiKey: "bro_pk_xxxxxxxxxxxx",  // Required — from the Bro dashboard
  autoPageView: true,              // Auto track page views (default: true)
  trackClicks: false,              // Auto track link/button clicks (default: false)
  webPush: true,                   // Enable Web Push setup (default: false)
  vapidPublicKey: "BEl62i...",     // VAPID public key (required if webPush: true)
  serviceWorkerPath: "/bro-sw.js", // Path to the service worker (default: "/bro-sw.js")
  debug: false,                    // Log events to console (default: false)
  flushInterval: 5000,             // ms between auto-flushes (default: 5000)
  flushSize: 20,                   // Max events per batch (default: 20)
  sessionTracking: true,           // Enable session tracking (default: true)
});

API

Analytics

bro.track(name, properties?)       // Track custom event
bro.identify(userId, traits?)      // Identify user
bro.page(name?, properties?)       // Track page view manually
bro.reset()                        // Clear identity (call on logout)
bro.flush()                        // Force-send queued events
bro.shutdown()                     // Stop the SDK and flush remaining events

Web Push

await bro.subscribeToPush()        // Request permission & subscribe
await bro.unsubscribeFromPush()    // Unsubscribe from push
await bro.getPushPermission()      // Check current permission ("granted" | "denied" | "default")

Web Push Setup

1. Generate VAPID keys

npx web-push generate-vapid-keys

Save the public and private keys. Add the private key to your Bro server's environment variables (VAPID_PRIVATE_KEY) and the public key to NEXT_PUBLIC_VAPID_PUBLIC_KEY.

2. Add the service worker

Copy bro-sw.js from this package to your project's public/ folder:

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

The service worker handles incoming push notifications and click-to-open behavior. It expects a JSON payload with:

{
  "title": "Notification title",
  "body": "Notification body text",
  "image": "https://example.com/image.png",
  "url": "https://example.com/target-page",
  "data": {}
}

3. Initialize with push enabled

import { createBro } from "@bro-sdk/web";

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

4. Subscribe users

Call subscribeToPush() when the user opts in (e.g. after clicking a "Enable notifications" button):

const subscription = await bro.subscribeToPush();

if (subscription) {
  console.log("Push enabled!");
} else {
  console.log("User denied or browser doesn't support push");
}

The SDK automatically registers the subscription with your Bro server. Push tokens are associated with the current user (or anonymous ID).

Frameworks

Next.js / React

// app/layout.tsx or _app.tsx
"use client";
import { createBro } from "@bro-sdk/web";

createBro({
  apiKey: "bro_pk_xxxxxxxxxxxx",
  autoPageView: true,
  webPush: true,
  vapidPublicKey: "your-vapid-public-key",
});

Vite / Plain JS

// main.ts
import { createBro } from "@bro-sdk/web";

createBro({
  apiKey: "bro_pk_xxxxxxxxxxxx",
});

License

MIT