capacitor-braze-plugin

Braze has no official Capacitor SDK — this plugin wraps the native Braze Android and iOS SDKs and exposes a core set of methods to the JS/TypeScript layer of any Ionic/Capacitor app.

This plugin does not handle Braze credentials or SDK initialization. There is no initialize() method — Braze API keys differ per platform, so configuring the native SDK (API key + endpoint) is exclusively the responsibility of your app's own native, declarative configuration (see Native configuration). Every method below rejects with a clear error if you call it before that native configuration is in place.

Installation

This package is not published to the npm registry — install it directly from GitHub:

npm install github:productminds/capacitor-braze-plugin
npx cap sync

Requirements

	Minimum version
Capacitor	8.0.0
Android (minSdk)	24
iOS (deployment target)	15.0

This plugin does not bundle any Braze credentials. Configure the native Braze SDK declaratively in your app before using any method below — see Native configuration.

Quick start

Assumes you've already completed the native configuration step for each platform you target.

import { Braze } from 'capacitor-braze-plugin';

// Identify the current user, e.g. right after login.
await Braze.changeUser({ externalId: 'user-1234' });

// Log a custom event.
await Braze.logCustomEvent({
  eventName: 'viewed_product',
  properties: { productId: 'sku-123', category: 'shoes' },
});

// Log a purchase.
await Braze.logPurchase({
  productId: 'sku-123',
  currency: 'USD',
  price: 19.99,
  quantity: 2,
  properties: { color: 'blue' },
});

// Set a custom attribute on the current user's profile.
await Braze.setCustomUserAttribute({ key: 'favorite_color', value: 'blue' });

User attributes & profile

Beyond setCustomUserAttribute, this plugin covers the rest of Braze's standard user-attribute surface: unsetting a custom attribute, adding to/removing from an array-typed custom attribute, and setting all 9 of Braze's reserved profile fields (email, firstName, lastName, country, language, homeCity, phoneNumber, gender, dateOfBirth) — as opposed to custom attributes, these are fields Braze itself recognizes.

// Remove a previously-set custom attribute.
await Braze.unsetCustomUserAttribute({ key: 'favorite_color' });

// Array-typed custom attributes: add/remove one value at a time, without
// touching the rest of the array. Only string values are supported.
await Braze.addToCustomUserAttributeArray({ key: 'favorite_teams', value: 'giants' });
await Braze.removeFromCustomUserAttributeArray({ key: 'favorite_teams', value: 'giants' });

// Set one or more reserved profile fields at once — only the fields you
// pass are updated, the rest are left untouched. At least one is required.
await Braze.setUserProfile({
  email: 'user@example.com',
  firstName: 'Ada',
  lastName: 'Lovelace',
  country: 'GB', // ISO 3166-1 alpha-2 code
  language: 'en', // ISO 639-1 code
  homeCity: 'London',
  phoneNumber: '+15555550100', // E.164 format
  gender: 'female', // see the accepted values below
  dateOfBirth: '1990-05-21', // ISO 8601 date ("YYYY-MM-DD")
});

Field formats and validation, per Braze's standard profile fields reference:

country — ISO 3166-1 alpha-2 (e.g. "US", "GB"). Not strictly validated by this plugin.
language — ISO 639-1 (e.g. "en", "es"). Not strictly validated by this plugin.
phoneNumber — expected in E.164 format (e.g. "+14155552671"). See the platform-specific validation note below.
dateOfBirth — an ISO 8601 date string ("YYYY-MM-DD") — an invalid or malformed date is rejected before either native SDK is called.
gender — one of 'male' | 'female' | 'other' | 'unknown' | 'not_applicable' | 'prefer_not_to_say'. An unrecognized value is rejected with a message listing the accepted values.

These are the concepts Braze's Android (com.braze.enums.Gender) and iOS (Braze.User.Gender) SDKs both support — the SDKs just spell the two multi-word cases differently natively (Android NOT_APPLICABLE/PREFER_NOT_TO_SAY, iOS notApplicable/preferNotToSay); this plugin's snake_case values are its own platform-neutral spelling, mapped to the right native case on each platform. Note: Braze's standard attributes reference only documents 5 gender values (M/F/O/N/P) — unknown has no corresponding letter code there. Both native SDKs define and accept unknown regardless (confirmed directly against each SDK's compiled interface), so it's included here, but unlike the other 5 it isn't confirmed as a value Braze's dashboard/backend surfaces the same way.

phoneNumber validation differs by platform. Braze validates the phone number format natively. On Android, BrazeUser.setPhoneNumber returns a Boolean success flag, so this plugin detects a rejected number and rejects the setUserProfile call, naming the field(s) Braze rejected. On iOS, BrazeKit's current (non-deprecated) Braze.User.set(phoneNumber:) returns Void — there is no native signal available to this plugin when Braze rejects a malformed number, so a setUserProfile call with an invalid phoneNumber still resolves successfully on iOS even though Braze silently drops the value.

eCommerce events

This plugin exposes Braze's 6 recommended eCommerce events — product_viewed, cart_updated, checkout_started, order_placed, order_cancelled, order_refunded — as 6 methods with a uniform, fully-typed API: every method takes a single typed options object and returns Promise<void>, the same shape as every other method in this plugin.

Underneath, the implementation differs per event, because Braze itself doesn't offer the same tooling for all 6:

logProductViewed, logCartUpdated, logCheckoutStarted, logOrderPlaced are backed by a native Braze SDK class on each platform (Android ProductViewedEvent/CartUpdatedEvent/CheckoutStartedEvent/OrderPlacedEvent, iOS Braze.Ecommerce.*). Those native classes validate the payload when they're constructed and reject with a clear error before anything is queued.
logOrderCancelled, logOrderRefunded have no native typed class on either platform — Braze's own guidance is to log these two manually via logCustomEvent. This plugin validates their payload natively (replicating the same non-blank/length and non-negative rules the typed classes above enforce, including reusing the native product line-item type for the products array) before dispatching via logCustomEvent with the event names "ecommerce.order_cancelled" / "ecommerce.order_refunded", so an invalid payload is still rejected immediately instead of being silently ingested. One difference: currency is only checked for a 3-letter format here, not against a real ISO 4217 code list the way the native SDK classes may do for the other 4 events.

From the calling code, that difference is invisible — both call shapes below are equally simple:

// Backed by a native Braze SDK class.
await Braze.logProductViewed({
  productId: 'sku-123',
  productName: 'Running Shoes',
  variantId: 'sku-123-blue-10',
  price: 89.99,
  currency: 'USD',
  source: 'product_detail_screen',
});

// No native class — validated here, then dispatched via logCustomEvent.
await Braze.logOrderRefunded({
  orderId: 'order-321',
  totalValue: 29.99, // partial refund: only the refunded amount
  currency: 'USD',
  source: 'support_screen',
  products: [
    { productId: 'sku-123', productName: 'Running Shoes', variantId: 'sku-123-blue-10', quantity: 1, price: 29.99 },
  ],
});

See the Braze eCommerce events guide for the full schema of each event, and the API section below for this plugin's exact option types.

API

changeUser(...)
logCustomEvent(...)
logPurchase(...)
setCustomUserAttribute(...)
unsetCustomUserAttribute(...)
addToCustomUserAttributeArray(...)
removeFromCustomUserAttributeArray(...)
setUserProfile(...)
logProductViewed(...)
logCartUpdated(...)
logCheckoutStarted(...)
logOrderPlaced(...)
logOrderCancelled(...)
logOrderRefunded(...)
Interfaces
Type Aliases

Capacitor plugin that wraps the core analytics and user identity APIs of the native Braze SDKs (Android and iOS).

This plugin does not configure the Braze SDK and does not accept API keys or endpoints — the host app must configure the native Braze SDK declaratively (Android string resources / iOS AppDelegate code) before calling any method here. See the README's "Native configuration" section for the exact steps. Every method below rejects with a clear error if the native SDK has not been configured yet.

This plugin intentionally covers a focused "core" surface — see the "Not covered by this plugin" section of the README for functionality (push notifications, manual session control, in-app messages, Content Cards) that is left to direct native SDK integration.

changeUser(...)

changeUser(options: ChangeUserOptions) => Promise<void>

Identifies the current user to Braze with an external (app-assigned) user ID, e.g. after login. Calling this with a different ID than the currently identified user starts a new user session and clears previously set user data on the client, per standard Braze SDK behavior.

Param	Type	Description
`options`	`ChangeUserOptions`	The external ID to identify the user with.

logCustomEvent(...)

logCustomEvent(options: LogCustomEventOptions) => Promise<void>

Logs a custom event to Braze, optionally with additional properties.

Param	Type	Description
`options`	`LogCustomEventOptions`	The event name and optional properties.

logPurchase(...)

logPurchase(options: LogPurchaseOptions) => Promise<void>

Logs a purchase event to Braze.

Param	Type	Description
`options`	`LogPurchaseOptions`	The purchase details.

setCustomUserAttribute(...)

setCustomUserAttribute(options: SetCustomUserAttributeOptions) => Promise<void>

Sets a custom attribute on the current user's Braze profile.

Param	Type	Description
`options`	`SetCustomUserAttributeOptions`	The attribute key and value.

unsetCustomUserAttribute(...)

unsetCustomUserAttribute(options: UnsetCustomUserAttributeOptions) => Promise<void>

Removes a custom attribute from the current user's Braze profile.

Param	Type	Description
`options`	`UnsetCustomUserAttributeOptions`	The attribute key to unset.

addToCustomUserAttributeArray(...)

addToCustomUserAttributeArray(options: ModifyCustomUserAttributeArrayOptions) => Promise<void>

Adds a value to an array-typed custom attribute on the current user's Braze profile, without affecting other values already in the array.

Param	Type	Description
`options`	`ModifyCustomUserAttributeArrayOptions`	The attribute key and the value to add.

removeFromCustomUserAttributeArray(...)

removeFromCustomUserAttributeArray(options: ModifyCustomUserAttributeArrayOptions) => Promise<void>

Removes a value from an array-typed custom attribute on the current user's Braze profile, without affecting other values already in the array.

Param	Type	Description
`options`	`ModifyCustomUserAttributeArrayOptions`	The attribute key and the value to remove.

setUserProfile(...)

setUserProfile(options: SetUserProfileOptions) => Promise<void>

Sets one or more of the current user's reserved Braze profile fields (as opposed to custom attributes). Only the fields present in options are updated — fields left out are not touched.

On Android, every field is validated natively by the Braze SDK itself (e.g. phoneNumber format) in addition to this plugin's own non-blank/format checks, and a field Braze rejects natively causes this method to reject too. On iOS, BrazeKit has no equivalent native validation feedback for these setters, so this method only guarantees this plugin's own checks passed — see the README for details.

Param	Type	Description
`options`	`SetUserProfileOptions`	The profile fields to set. At least one must be present.

logProductViewed(...)

logProductViewed(options: ProductViewedOptions) => Promise<void>

Logs Braze's recommended product_viewed eCommerce event.

Backed by a native Braze SDK class (Android ProductViewedEvent, iOS Braze.Ecommerce.ProductViewedEvent), which validates the payload before the event is queued.

Param	Type	Description
`options`	`ProductViewedOptions`	The product view details.

logCartUpdated(...)

logCartUpdated(options: CartUpdatedOptions) => Promise<void>

Logs Braze's recommended cart_updated eCommerce event.

Backed by a native Braze SDK class (Android CartUpdatedEvent, iOS Braze.Ecommerce.CartUpdatedEvent), which validates the payload before the event is queued.

Param	Type	Description
`options`	`CartUpdatedOptions`	The cart update details.

logCheckoutStarted(...)

logCheckoutStarted(options: CheckoutStartedOptions) => Promise<void>

Logs Braze's recommended checkout_started eCommerce event.

Backed by a native Braze SDK class (Android CheckoutStartedEvent, iOS Braze.Ecommerce.CheckoutStartedEvent), which validates the payload before the event is queued.

Param	Type	Description
`options`	`CheckoutStartedOptions`	The checkout details.

logOrderPlaced(...)

logOrderPlaced(options: OrderPlacedOptions) => Promise<void>

Logs Braze's recommended order_placed eCommerce event.

Backed by a native Braze SDK class (Android OrderPlacedEvent, iOS Braze.Ecommerce.OrderPlacedEvent), which validates the payload before the event is queued.

Param	Type	Description
`options`	`OrderPlacedOptions`	The order details.

logOrderCancelled(...)

logOrderCancelled(options: OrderCancelledOptions) => Promise<void>

Logs Braze's recommended order_cancelled eCommerce event.

Braze does not provide a native typed class for this event on either platform — this method validates the payload natively (replicating the same rules the typed classes above enforce) and dispatches it via logCustomEvent with the event name "ecommerce.order_cancelled", so that invalid payloads fail fast here instead of being silently ingested.

Param	Type	Description
`options`	`OrderCancelledOptions`	The cancellation details.

logOrderRefunded(...)

logOrderRefunded(options: OrderRefundedOptions) => Promise<void>

Logs Braze's recommended order_refunded eCommerce event.

Braze does not provide a native typed class for this event on either platform — this method validates the payload natively (replicating the same rules the typed classes above enforce) and dispatches it via logCustomEvent with the event name "ecommerce.order_refunded", so that invalid payloads fail fast here instead of being silently ingested.

Param	Type	Description
`options`	`OrderRefundedOptions`	The refund details.

Interfaces

ChangeUserOptions

Options for {@link BrazePlugin.changeUser}.

Prop	Type	Description
`externalId`	`string`	The external (app-assigned) user ID to associate with the current device, e.g. your backend's user ID once the user has logged in.

LogCustomEventOptions

Options for {@link BrazePlugin.logCustomEvent}.

Prop	Type	Description
`eventName`	`string`	The name of the custom event, as it will appear in the Braze dashboard.
`properties`	`Record<string, unknown>`	Optional key/value properties attached to the event. Values must be JSON-serializable (string, number, boolean, or null); nested objects and arrays are not supported by the native Braze SDKs.

LogPurchaseOptions

Options for {@link BrazePlugin.logPurchase}.

Prop	Type	Description
`productId`	`string`	The identifier for the purchased product (e.g. a SKU).
`currency`	`string`	The ISO 4217 currency code for the purchase (e.g. `"USD"`).
`price`	`number`	The price of a single unit of the product, in the given currency.
`quantity`	`number`	The number of units purchased.
`properties`	`Record<string, unknown>`	Optional key/value properties attached to the purchase event. Values must be JSON-serializable (string, number, boolean, or null); nested objects and arrays are not supported by the native Braze SDKs.

SetCustomUserAttributeOptions

Options for {@link BrazePlugin.setCustomUserAttribute}.

Prop	Type	Description
`key`	`string`	The name of the custom attribute, as it will appear in the Braze dashboard.
`value`	`string \| number \| boolean`	The value to set for the attribute. Arrays and objects are not supported by this method; use {@link BrazePlugin.addToCustomUserAttributeArray} / {@link BrazePlugin.removeFromCustomUserAttributeArray} for array-typed custom attributes.

UnsetCustomUserAttributeOptions

Options for {@link BrazePlugin.unsetCustomUserAttribute}.

Prop	Type	Description
`key`	`string`	The name of the custom attribute to unset.

ModifyCustomUserAttributeArrayOptions

Options for {@link BrazePlugin.addToCustomUserAttributeArray} and {@link BrazePlugin.removeFromCustomUserAttributeArray}.

Prop	Type	Description
`key`	`string`	The name of the array-typed custom attribute.
`value`	`string`	The string value to add to or remove from the array. Only string array values are supported by this method.

SetUserProfileOptions

Options for {@link BrazePlugin.setUserProfile}.

At least one field must be present.

Prop	Type	Description
`email`	`string`	The user's email address.
`firstName`	`string`	The user's first name.
`lastName`	`string`	The user's last name.
`country`	`string`	The user's country, as an ISO 3166-1 alpha-2 code (e.g. `"US"`, `"GB"`). Not strictly validated by this plugin — passed through to the native SDK as-is.
`language`	`string`	The user's language, as an ISO 639-1 code (e.g. `"en"`, `"es"`). Not strictly validated by this plugin — passed through to the native SDK as-is.
`homeCity`	`string`	The user's home city.
`phoneNumber`	`string`	The user's phone number, expected in E.164 format (e.g. `"+14155552671"`). Braze applies its own native-side format validation and may silently reject a malformed number — see the README for how this plugin surfaces (or, on iOS, can't surface) that rejection.
`gender`	`UserGender`	The user's gender.
`dateOfBirth`	`string`	The user's date of birth, as an ISO 8601 date string (`"YYYY-MM-DD"`), e.g. `"1990-05-21"`.

ProductViewedOptions

Options for {@link BrazePlugin.logProductViewed}.

Prop	Type	Description
`productId`	`string`	The identifier for the viewed product (e.g. a SKU).
`productName`	`string`	The display name of the viewed product.
`variantId`	`string`	The identifier for the specific variant of the product being viewed.
`imageUrl`	`string`	A URL for an image of the product.
`productUrl`	`string`	A URL to the product's page.
`price`	`number`	The price of the product, in the given currency.
`currency`	`string`	The ISO 4217 currency code for the price (e.g. `"USD"`).
`source`	`string`	A label identifying where this view occurred in your app (e.g. a screen or feature name).
`type`	`('price_drop' \| 'back_in_stock')[]`	Optional tags describing why this product is being surfaced.
`metadata`	`Record<string, string \| number \| boolean>`	Optional key/value properties attached to the event.

CartUpdatedOptions

Options for {@link BrazePlugin.logCartUpdated}.

Prop	Type	Description
`cartId`	`string`	The identifier for the shopping cart.
`action`	`CartUpdatedAction`	How the cart changed. Defaults to `"replace"`.
`totalValue`	`number`	The cart's total value after this update. Required when `action` is omitted or `"replace"`; optional when `action` is `"add"` or `"remove"`.
`subtotalValue`	`number`	The cart's subtotal value (before tax/shipping), if available.
`tax`	`number`	The tax amount applied to the cart, if available.
`shipping`	`number`	The shipping cost applied to the cart, if available.
`currency`	`string`	The ISO 4217 currency code for the monetary values (e.g. `"USD"`).
`products`	`EcommerceProduct[]`	The product line items in the cart. Must contain at least one item.
`source`	`string`	A label identifying where this update occurred in your app.
`metadata`	`Record<string, string \| number \| boolean>`	Optional key/value properties attached to the event.

EcommerceProduct

A single product line item, used by the eCommerce events that carry a product list ({@link BrazePlugin.logCartUpdated}, {@link BrazePlugin.logCheckoutStarted}, {@link BrazePlugin.logOrderPlaced}, {@link BrazePlugin.logOrderCancelled}, {@link BrazePlugin.logOrderRefunded}).

Prop	Type	Description
`productId`	`string`	The identifier for the product (e.g. a SKU).
`productName`	`string`	The display name of the product.
`variantId`	`string`	The identifier for the specific variant of the product (e.g. size/color).
`imageUrl`	`string`	A URL for an image of the product.
`productUrl`	`string`	A URL to the product's page.
`quantity`	`number`	The number of units of this product in the line item. Must be a non-negative integer.
`price`	`number`	The price of a single unit of the product.
`metadata`	`Record<string, string \| number \| boolean>`	Optional key/value properties attached to this line item.

CheckoutStartedOptions

Options for {@link BrazePlugin.logCheckoutStarted}.

Prop	Type	Description
`checkoutId`	`string`	The identifier for this checkout.
`cartId`	`string`	The identifier for the shopping cart that started checkout, if available.
`totalValue`	`number`	The checkout's total value.
`subtotalValue`	`number`	The checkout's subtotal value (before tax/shipping), if available.
`tax`	`number`	The tax amount applied to the checkout, if available.
`shipping`	`number`	The shipping cost applied to the checkout, if available.
`currency`	`string`	The ISO 4217 currency code for the monetary values (e.g. `"USD"`).
`products`	`EcommerceProduct[]`	The product line items being checked out. Must contain at least one item.
`source`	`string`	A label identifying where checkout started in your app.
`metadata`	`Record<string, string \| number \| boolean>`	Optional key/value properties attached to the event. Braze recognizes the `checkout_url` metadata key for a link back to the checkout.

OrderPlacedOptions

Options for {@link BrazePlugin.logOrderPlaced}.

Prop	Type	Description
`orderId`	`string`	The identifier for the placed order.
`cartId`	`string`	The identifier for the shopping cart the order was placed from, if available.
`totalValue`	`number`	The order's total value.
`subtotalValue`	`number`	The order's subtotal value (before tax/shipping), if available.
`tax`	`number`	The tax amount applied to the order, if available.
`shipping`	`number`	The shipping cost applied to the order, if available.
`currency`	`string`	The ISO 4217 currency code for the monetary values (e.g. `"USD"`).
`totalDiscounts`	`number`	The total monetary amount discounted on this order, if any.
`discounts`	`OrderDiscount[]`	The individual discounts applied to this order, if any.
`products`	`EcommerceProduct[]`	The product line items in the order. Must contain at least one item.
`source`	`string`	A label identifying where the order was placed in your app.
`metadata`	`Record<string, string \| number \| boolean>`	Optional key/value properties attached to the event. Braze recognizes the `order_status_url` metadata key for a link to order status.

OrderDiscount

A single order-level discount entry, used by {@link BrazePlugin.logOrderPlaced}, {@link BrazePlugin.logOrderCancelled}, and {@link BrazePlugin.logOrderRefunded}.

Prop	Type	Description
`code`	`string`	The discount code applied to the order.
`amount`	`number`	The monetary amount discounted.
`type`	`string`	The type of discount (e.g. `"percentage"`, `"fixed"`).

OrderCancelledOptions

Options for {@link BrazePlugin.logOrderCancelled}.

Prop	Type	Description
`orderId`	`string`	The identifier for the cancelled order.
`totalValue`	`number`	The order's total value. Must be non-negative.
`subtotalValue`	`number`	The order's subtotal value (before tax/shipping), if available.
`tax`	`number`	The tax amount applied to the order, if available.
`shipping`	`number`	The shipping cost applied to the order, if available.
`currency`	`string`	The ISO 4217 currency code for the monetary values (e.g. `"USD"`).
`totalDiscounts`	`number`	The total monetary amount discounted on this order, if any.
`discounts`	`OrderDiscount[]`	The individual discounts applied to this order, if any.
`cancelReason`	`string`	The reason the order was cancelled.
`products`	`EcommerceProduct[]`	The product line items in the cancelled order. Must contain at least one item.
`source`	`string`	A label identifying where the cancellation was initiated in your app.
`metadata`	`Record<string, string \| number \| boolean>`	Optional key/value properties attached to the event. Braze recognizes the `order_status_url` metadata key for a link to order status.

OrderRefundedOptions

Options for {@link BrazePlugin.logOrderRefunded}.

Prop	Type	Description
`orderId`	`string`	The identifier for the refunded order.
`totalValue`	`number`	The refunded amount. Must be non-negative. For partial refunds, send only the amount that was refunded, not the original order total.
`currency`	`string`	The ISO 4217 currency code for the monetary values (e.g. `"USD"`).
`totalDiscounts`	`number`	The total monetary amount discounted on this order, if any.
`discounts`	`OrderDiscount[]`	The individual discounts applied to this order, if any.
`products`	`EcommerceProduct[]`	The product line items in the refunded order. Must contain at least one item.
`source`	`string`	A label identifying where the refund was initiated in your app.
`metadata`	`Record<string, string \| number \| boolean>`	Optional key/value properties attached to the event. Braze recognizes the `order_status_url` metadata key for a link to order status.

Type Aliases

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

UserGender

The current user's gender, for {@link SetUserProfileOptions.gender}.

This is the intersection of the values Braze's Android (com.braze.enums.Gender) and iOS (Braze.User.Gender) SDKs support — both SDKs recognize the same 6 concepts, just under different native identifiers (e.g. Android's NOT_APPLICABLE / iOS's notApplicable); this plugin maps this single snake_case value to the right native enum case on each platform, so no value here is platform-specific.

Note: Braze's public standard-attributes reference (https://www.braze.com/docs/user_guide/data/activation/attributes/standard_attributes#profile-fields) only documents 5 gender values (M/F/O/N/P) — unknown has no corresponding letter code there. Both native SDKs define and accept it regardless (confirmed directly against each SDK's compiled interface), so it's included here, but it isn't confirmed as a value Braze's dashboard/backend surfaces the same way as the other 5.

CartUpdatedAction

The action that changed a shopping cart, for {@link BrazePlugin.logCartUpdated}.

'add' | 'remove' | 'replace'

Native configuration

Braze API keys are different per platform, and this plugin never accepts one from JS — configuring the native SDK (API key + endpoint) is entirely your app's responsibility, done natively and declaratively, once per platform, before any method on this plugin is called. There is no runtime/JS initialization path.

Android

Declare your API key and endpoint as string resources — Braze reads these directly from res/values/, not from AndroidManifest.xml. Create (or edit) android/app/src/main/res/values/braze.xml in your app:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="com_braze_api_key" translatable="false">YOUR-ANDROID-API-KEY</string>
    <string name="com_braze_custom_endpoint" translatable="false">YOUR-BRAZE-ENDPOINT</string>
</resources>

That's it — no Kotlin/Java code, no Application subclass, no manifest changes required. The Braze Android SDK reads these resources the first time it's used. See the Braze Android SDK integration guide for the full list of optional configuration keys.

iOS

BrazeKit has no manifest/plist-based configuration — it must be configured in Swift code, once, before this plugin is used. The module name you import for this plugin depends on how your app integrates it — Capacitor 8 uses SPM by default, so that's the primary path below; CocoaPods is documented as the alternative.

Add BrazeKit as a direct dependency of your iOS app (not just of this plugin), then configure it in your app's AppDelegate and assign the instance to this plugin's BrazeBridge.sharedInstance before application(_:didFinishLaunchingWithOptions:) returns.

Swift Package Manager (default for Capacitor 8)

In Xcode: File → Add Package Dependencies… → https://github.com/braze-inc/braze-swift-sdk.
AppDelegate.swift — import this plugin's SPM target, BrazePlugin:

import UIKit
import Capacitor
import BrazeKit
import BrazePlugin

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let configuration = Braze.Configuration(
            apiKey: "YOUR-IOS-API-KEY",
            endpoint: "YOUR-BRAZE-ENDPOINT"
        )
        BrazeBridge.sharedInstance = Braze(configuration: configuration)
        return true
    }
}

CocoaPods (alternative)

Add to your app's Podfile (BrazeKit ships a static xcframework, so use_frameworks! needs static linkage):

use_frameworks! :linkage => :static

target 'App' do
  pod 'CapacitorBrazePlugin', :path => '../../node_modules/capacitor-braze-plugin'
  pod 'BrazeKit'
end

AppDelegate.swift — import this plugin's CocoaPods module, CapacitorBrazePlugin (not BrazePlugin — that name only resolves under SPM):

import UIKit
import Capacitor
import BrazeKit
import CapacitorBrazePlugin

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let configuration = Braze.Configuration(
            apiKey: "YOUR-IOS-API-KEY",
            endpoint: "YOUR-BRAZE-ENDPOINT"
        )
        BrazeBridge.sharedInstance = Braze(configuration: configuration)
        return true
    }
}

Both snippets configure the exact same BrazeBridge.sharedInstance — only the import line differs. See the Braze Swift SDK setup guide for the full list of optional Braze.Configuration options.

No additional runtime permissions are required by this plugin beyond what the native Braze SDKs declare in their own manifests/frameworks.

Not covered by this plugin

This plugin covers a focused core surface only. The following are explicitly out of scope and are not implemented, not stubbed, and not planned for a future version of this core API — integrate the native Braze SDK directly in your app for these:

Push notifications (device token registration, notification payload handling)
Manual session control (openSession() / closeSession())
In-app messages
Content Cards

Two of these are a single line of native code to enable — for the rest, see the Braze developer docs.

Session tracking (Android) — in your app's Application.onCreate():

registerActivityLifecycleCallbacks(BrazeActivityLifecycleCallbackListener())

This also automatically handles open/close session and in-app message event subscription — no separate step needed for Android in-app messages.

In-app messages (iOS) — in AppDelegate, right after setting BrazeBridge.sharedInstance:

BrazeBridge.sharedInstance?.inAppMessagePresenter = BrazeInAppMessageUI()

Requires adding the BrazeUI package/pod (alongside BrazeKit) and import BrazeUI. See the Braze in-app messages guide.

Updating the native Braze SDK version

Android: the Braze SDK version is declared in android/build.gradle as the brazeAndroidSdkVersion property (implementation "com.braze:android-sdk-ui:$brazeAndroidSdkVersion"). Bump that value, or override brazeAndroidSdkVersion from your app's root build.gradle. See the Braze Android SDK releases for changelogs.
iOS: the Braze SDK version is declared in Package.swift (for SPM-based Capacitor apps) and in CapacitorBrazePlugin.podspec (for CocoaPods-based apps), as the braze-swift-sdk / BrazeKit dependency version. Bump both to keep them in sync. See the Braze Swift SDK releases for changelogs.

Contributing

Contributions are welcome — see CONTRIBUTING.md for how to set up the project locally and submit changes.

License

MIT © Minders

Name		Name	Last commit message	Last commit date
.github		.github
android		android
ios		ios
src		src
.eslintignore		.eslintignore
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CapacitorBrazePlugin.podspec		CapacitorBrazePlugin.podspec
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
rollup.config.mjs		rollup.config.mjs
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

capacitor-braze-plugin

Installation

Requirements

Quick start

User attributes & profile

eCommerce events

API

changeUser(...)

logCustomEvent(...)

logPurchase(...)

setCustomUserAttribute(...)

unsetCustomUserAttribute(...)

addToCustomUserAttributeArray(...)

removeFromCustomUserAttributeArray(...)

setUserProfile(...)

logProductViewed(...)

logCartUpdated(...)

logCheckoutStarted(...)

logOrderPlaced(...)

logOrderCancelled(...)

logOrderRefunded(...)

Interfaces

ChangeUserOptions

LogCustomEventOptions

LogPurchaseOptions

SetCustomUserAttributeOptions

UnsetCustomUserAttributeOptions

ModifyCustomUserAttributeArrayOptions

SetUserProfileOptions

ProductViewedOptions

CartUpdatedOptions

EcommerceProduct

CheckoutStartedOptions

OrderPlacedOptions

OrderDiscount

OrderCancelledOptions

OrderRefundedOptions

Type Aliases

Record

UserGender

CartUpdatedAction

Native configuration

Android

iOS

Swift Package Manager (default for Capacitor 8)

CocoaPods (alternative)

Not covered by this plugin

Updating the native Braze SDK version

Contributing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages