@luminpdf/browser-braze

A TypeScript wrapper around the Braze Web SDK that provides a simplified, type-safe interface for integrating Braze analytics into your web applications.

Features

• Singleton Pattern: Ensures a single instance across your application
• Type-Safe: Full TypeScript support with proper type definitions
• Auto-enrichment: Automatically adds common browser attributes to events
• Simple API: Clean, intuitive methods for common Braze operations

Installation

npm install @luminpdf/browser-braze
# or
yarn add @luminpdf/browser-braze
# or
pnpm add @luminpdf/browser-braze

Basic Usage

import { BrazeClient } from "@luminpdf/browser-braze";

// Use the static factory method to get the singleton instance
const brazeClient = BrazeClient.create({
  apiKey: "YOUR_API_KEY",
  options: {
    baseUrl: "YOUR_SDK_ENDPOINT",
    enableLogging: true,
    // other Braze initialization options
  },
});

// Set user information
brazeClient.setUserInfo({
  id: "user-123",
  email: "[email protected]",
  name: "John Doe",
});

// Send an event
await brazeClient.sendEvent({
  eventName: "button_clicked",
  attributes: {
    button_name: "signup",
    page: "homepage",
  },
});

Note: Calling BrazeClient.create() multiple times will always return the same singleton instance, ensuring consistent configuration across your application.

Advanced Usage

Send Events

// Send event with immediate data flush (default behavior)
await brazeClient.sendEvent({
  eventName: "button_clicked",
  attributes: {
    button_name: "signup",
    page: "homepage",
  },
});

// Send event without immediate flush (useful for batching)
await brazeClient.sendEvent({
  eventName: "page_viewed",
  attributes: {
    page: "dashboard",
  },
  flushAll: true, // skip immediate flush
});

Manage Client Attributes

Set custom attributes that will be included with all events:

// Set client attributes
brazeClient.setClientAttributes({
  app_version: "1.2.3",
  environment: "production",
});

// Get current client attributes
const attributes = brazeClient.getClientAttributes();
console.log(attributes);

Resetting the Instance (Testing Only)

For testing purposes, you can reset the singleton instance:

// Reset the singleton (typically only used in tests)
BrazeClient.resetInstance();

// Now you can create a new instance with different config
const newClient = BrazeClient.create({
  /* different config */
});

API Reference

Static Methods

BrazeClient.create(config: BrazeClientConfig): BrazeClient

Returns the singleton instance of BrazeClient. Subsequent calls return the same instance.

BrazeClient.resetInstance(): void

Resets the singleton instance. Useful for testing purposes only.

Instance Methods

sendEvent(params): Promise<boolean>

Sends a custom event to Braze with optional attributes.

Parameters:

• eventName (string) - Name of the event
• attributes (TAttributes) - Custom attributes for the event
• flushAll (boolean, optional) - If true, skips immediate data flush. Default is false, which triggers an immediate flush after logging the event.

Returns: Promise that resolves to true on success

setUserInfo(user: BrazeUser): void

Sets the current user information in Braze.

Parameters:

• user (object)
  • id (string) - Unique user identifier
  • email (string) - User's email address
  • name (string) - User's name

setClientAttributes(attributes: Record<string, unknown>): void

Sets custom attributes that will be automatically included with all events.

getClientAttributes(): Record<string, unknown>

Returns a copy of the current client attributes.

getCommonAttributesForClient(): Record<string, unknown>

Returns common attributes including both client attributes and browser attributes.

getConfig(): Readonly<BrazeClientConfig>

Returns the current configuration.

isClientConfigured(): boolean

Returns whether the client has been configured.

Configuration Options

BrazeClientConfig

| Option | Type | Description | | --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | apiKey | string | Your Braze API key | | options | InitializationOptions | Braze initialization options (see Braze documentation) |

Types

BrazeUser

interface BrazeUser {
  id: string;
  email: string;
  name: string;
}

BrazeClientConfig

interface BrazeClientConfig {
  apiKey: string;
  options: InitializationOptions;
}

Dependencies

• @braze/web-sdk - Official Braze Web SDK
• @luminpdf/signing-miscellaneous - Utility functions for common attributes
• lodash - Utility library

License

ISC