capacitor-braze

Capacitor 6+ plugin wrapping the official Braze SDKs for Android, iOS, and Web. 0.0.x — not yet published to npm; consume via git for now.

Disclaimer

This is an independent, personal open-source project by Bryce Aspinwall. It is NOT made by, affiliated with, endorsed by, or supported by Braze, Inc. "Braze" is a trademark of Braze, Inc.; the name appears here only to describe what this plugin wraps. For first-party SDKs and official support, go to braze.com or the braze-inc GitHub organization.

This plugin is a thin Capacitor bridge layer around Braze's own public SDKs (which do all the real work). It is MIT-licensed, built on the side as a portfolio + personal-use project, and offered as-is. Issues and PRs are welcome but support is best-effort.

A community-maintained Capacitor plugin that exposes the Braze customer engagement SDKs to Capacitor apps with a single TypeScript API across iOS, Android, and Web.

Why this exists

Braze ships first-party SDKs for native Android, iOS, Web, React Native, Flutter, Cordova, Expo, Unity, Xamarin, and Roku — but not Capacitor. Today's options for Capacitor teams are: ship the Cordova SDK via Capacitor's compat layer (broken push handoff in Capacitor 6+, deprecated upgrade path), use only the Web SDK (lose native push and in-app messages), roll a custom bridge (2–3 weeks of native work), or skip Braze. This plugin makes it npm install + ~10 lines.

See PLAN.md for the full strategic case, including why not the Cordova plugin.

Status

| Surface | State | |---|---| | TypeScript API | 35 methods + addListener / removeAllListeners for 2 events | | iOS bridge (BrazeKit 14.1.0) | Compiles green on every PR via the verify-ios CI job; PrivacyInfo.xcprivacy shipped via podspec resource_bundles | | Android bridge (com.braze:android-sdk-ui 42.2.0) | Compiles green on every PR via the verify-android CI job | | Web bridge (@braze/web-sdk ^6.0.0) | Builds green; 75 behavioral + 17 serializer = 92 tests in ~2.4s; 37/37 surface methods directly covered, every validation branch dedicated-tested per docs/TEST-COVERAGE-AUDIT.md; one method (registerPushToken) is platform-divergent and throws on web by design (per C03) | | Developer testbed (example/) | Every plugin method has a button; clicking invokes + logs | | Reference app (demo/) | React 19 + Tailwind 4 + TanStack Router; restaurant ordering + e-commerce flows; iOS + Android Capacitor projects committed | | MDC design contracts | C01-C11 codify the patterns; CI gates enforce them | | Test coverage audit | docs/TEST-COVERAGE-AUDIT.md tracks the 33/37 directly-covered methods + remaining gaps with unblock plans | | Branch protection | Applied via gh CLI: 8 required CI checks (strict), no force pushes, no deletions, signed commits required, admin bypass for hotfixes | | Smoke-tested against real Braze | ❌ Not yet the next milestone (templates pre-staged in docs/smoke-tests/) | | Published to npm | ❌ Not yet waiting on the smoke test |

See SDK_SURFACE.md §2 for the version roadmap and what's still unshipped (in-app message listener, banners, push permission helpers).

Quick start

# Until 0.1.0 hits npm, consume via git:
npm install bma342/capacitor-braze @braze/web-sdk

iOS requires two Podfile edits before cap sync will succeed (BrazeKit 14.x pins minimum deployment target to iOS 15 and requires static linkage):

# ios/App/Podfile
platform :ios, '15.0'                         # was '13.0' in the Capacitor default
use_frameworks! :linkage => :static           # was 'use_frameworks!' alone

Verified on a fresh cap init 2026-05-20: skipping these produces a CocoaPods "required a higher minimum deployment target" error. Full rationale in MDC C10. Android requires no consumer-side edits.

npx cap sync

import { Braze } from 'capacitor-braze';

await Braze.initialize({
  apiKey: 'YOUR-SDK-API-KEY',
  endpoint: 'sdk.iad-03.braze.com',
  enableSdkAuthentication: true,
});

await Braze.changeUser({
  userId: 'user_123',
  sdkAuthSignature: '<jwt-from-your-backend>',
});

await Braze.logCustomEvent({ name: 'app_opened' });

Which API key do I use? SDK key (public, embedded in app), not REST key (secret, server-only). See SECURITY.md §1.

Don't forget the iOS Podfile setup — Braze SDK 14.x requires platform :ios, '15.0' + use_frameworks! :linkage => :static. The plugin documents this in C10; skipping it produces a confusing CocoaPods error.

API reference

• echo(...)
• initialize(...)
• changeUser(...)
• getUserId()
• setSdkAuthenticationSignature(...)
• setEmail(...)
• setPhoneNumber(...)
• setFirstName(...)
• setLastName(...)
• setLanguage(...)
• setCountry(...)
• setCustomUserAttribute(...)
• addToSubscriptionGroup(...)
• removeFromSubscriptionGroup(...)
• addAlias(...)
• getDeviceId()
• setDateOfBirth(...)
• setGender(...)
• setHomeCity(...)
• logCustomEvent(...)
• logPurchase(...)
• getFeatureFlag(...)
• getAllFeatureFlags()
• refreshFeatureFlags()
• logFeatureFlagImpression(...)
• getContentCards()
• requestContentCardsRefresh()
• logContentCardClick(...)
• logContentCardImpression(...)
• registerPushToken(...)
• addListener('featureFlagsUpdated', ...)
• addListener('contentCardsUpdated', ...)
• addListener('inAppMessageReceived', ...)
• addListener('sdkAuthError', ...)
• removeAllListeners()
• wipeData()
• disableSDK()
• enableSDK()
• isDisabled()
• requestImmediateDataFlush()
• Interfaces
• Type Aliases

echo(...)

echo(options: BrazeEchoOptions) => Promise<BrazeEchoResult>

Round-trips a value through the native bridge. Useful as a sanity check that the plugin installed correctly on the current platform. Not a Braze SDK method.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | BrazeEchoOptions |

Returns: Promise<BrazeEchoResult>

initialize(...)

initialize(options: BrazeInitializeOptions) => Promise<void>

Initialize the Braze SDK. Must be called before any other Braze method except {@link BrazePlugin.echo} and the init-independent privacy/lifecycle methods ({@link BrazePlugin.wipeData}, {@link BrazePlugin.disableSDK}, {@link BrazePlugin.enableSDK}, {@link BrazePlugin.isDisabled}).

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | BrazeInitializeOptions |

changeUser(...)

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

Identifies the current user. Pass an sdkAuthSignature if SDK Authentication is enabled (see SECURITY.md §2).

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | BrazeChangeUserOptions |

getUserId()

getUserId() => Promise<BrazeGetUserIdResult>

Returns the current external user ID, or null if the user is anonymous.

Returns: Promise<BrazeGetUserIdResult>

setSdkAuthenticationSignature(...)

setSdkAuthenticationSignature(options: BrazeSetSdkAuthenticationSignatureOptions) => Promise<void>

Rotates the SDK Authentication signature without re-running changeUser. Use after the previous signature expires (typically every 12-24h depending on your backend's JWT lifetime) or after receiving an SDK Auth error from the Braze backend.

Calling this without enableSdkAuthentication: true at init time is a no-op in the SDK — the signature is stored but never sent.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------------------------- | | options | BrazeSetSdkAuthenticationSignatureOptions |

setEmail(...)

setEmail(options: BrazeSetEmailOptions) => Promise<void>

Sets the current user's email.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | BrazeSetEmailOptions |

setPhoneNumber(...)

setPhoneNumber(options: BrazeSetPhoneNumberOptions) => Promise<void>

Sets the current user's phone number. E.164 format recommended.

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | BrazeSetPhoneNumberOptions |

setFirstName(...)

setFirstName(options: BrazeSetFirstNameOptions) => Promise<void>

Sets the current user's first name.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | BrazeSetFirstNameOptions |

setLastName(...)

setLastName(options: BrazeSetLastNameOptions) => Promise<void>

Sets the current user's last name.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | BrazeSetLastNameOptions |

setLanguage(...)

setLanguage(options: BrazeSetLanguageOptions) => Promise<void>

Sets the current user's language. Use ISO 639-1 codes.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | BrazeSetLanguageOptions |

setCountry(...)

setCountry(options: BrazeSetCountryOptions) => Promise<void>

Sets the current user's country. Use ISO 3166-1 alpha-2 codes.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | BrazeSetCountryOptions |

setCustomUserAttribute(...)

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

Sets a custom user attribute. The native bridge dispatches based on the inferred type of value (string / number / boolean → matching Braze SDK overload).

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------- | | options | BrazeSetCustomUserAttributeOptions |

addToSubscriptionGroup(...)

addToSubscriptionGroup(options: BrazeSubscriptionGroupOptions) => Promise<void>

Adds the current user to an email or SMS subscription group.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | BrazeSubscriptionGroupOptions |

removeFromSubscriptionGroup(...)

removeFromSubscriptionGroup(options: BrazeSubscriptionGroupOptions) => Promise<void>

Removes the current user from a subscription group.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | BrazeSubscriptionGroupOptions |

addAlias(...)

addAlias(options: BrazeAddAliasOptions) => Promise<void>

Adds an alias for the current user. (alias, label) pairs are unique across users — if another user already owns the pair, the alias is rejected by the Braze backend.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | BrazeAddAliasOptions |

getDeviceId()

getDeviceId() => Promise<BrazeGetDeviceIdResult>

Returns the Braze SDK device identifier for the current install. Useful for debugging and for sending the device ID to your backend for targeted server-side messaging.

Requires {@link BrazePlugin.initialize} to have been called. The accessor is instance-bound on iOS (braze.deviceId) and Android (Braze.getInstance(context).deviceId); only Web exposes a true static. To keep the contract uniform across platforms (see C03 / C07) the plugin gates this method behind the init guard on all three.

Returns: Promise<BrazeGetDeviceIdResult>

setDateOfBirth(...)

setDateOfBirth(options: BrazeSetDateOfBirthOptions) => Promise<void>

Sets the current user's date of birth. month is 1-indexed (January = 1) to match the Web SDK contract and to avoid the Java Calendar.MONTH 0-indexed surprise. The Android bridge maps month to the Braze Month enum internally.

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | BrazeSetDateOfBirthOptions |

setGender(...)

setGender(options: BrazeSetGenderOptions) => Promise<void>

Sets the current user's gender. Accepts the string values listed in {@link BrazeGender}; bridges map them to the matching native enum value.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | BrazeSetGenderOptions |

setHomeCity(...)

setHomeCity(options: BrazeSetHomeCityOptions) => Promise<void>

Sets the current user's home city. Pass null to clear.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | BrazeSetHomeCityOptions |

logCustomEvent(...)

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

Logs a custom event for the current user.

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | BrazeLogCustomEventOptions |

logPurchase(...)

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

Logs a purchase. Required for Braze's revenue analytics. currency is required on this contract even though the Web SDK accepts it optionally, because revenue rolls up incorrectly when some events lack currency.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | BrazeLogPurchaseOptions |

getFeatureFlag(...)

getFeatureFlag(options: BrazeGetFeatureFlagOptions) => Promise<BrazeGetFeatureFlagResult>

Returns a single feature flag by identifier, or null if no flag with that id exists for the current user. Reads from the SDK's local cache; call {@link BrazePlugin.refreshFeatureFlags} to force a fetch.

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | BrazeGetFeatureFlagOptions |

Returns: Promise<BrazeGetFeatureFlagResult>

getAllFeatureFlags()

getAllFeatureFlags() => Promise<BrazeGetAllFeatureFlagsResult>

Returns all feature flags currently cached for the user.

Returns: Promise<BrazeGetAllFeatureFlagsResult>

refreshFeatureFlags()

refreshFeatureFlags() => Promise<void>

Requests an immediate refresh of feature flags from the Braze backend. Fire-and-forget: the returned promise resolves once the refresh has been dispatched, not once new flags arrive. Re-read with {@link BrazePlugin.getAllFeatureFlags} after a short delay; the subscribe-to-updates listener API will land in a later version.

logFeatureFlagImpression(...)

logFeatureFlagImpression(options: BrazeLogFeatureFlagImpressionOptions) => Promise<void>

Logs an impression for a feature flag. Per Braze, limited to one impression per session per flag id.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------------------- | | options | BrazeLogFeatureFlagImpressionOptions |

getContentCards()

getContentCards() => Promise<BrazeGetContentCardsResult>

Returns all content cards currently cached for the user. Reads from the SDK's local cache; call {@link BrazePlugin.requestContentCardsRefresh} to force a fetch.

Returns: Promise<BrazeGetContentCardsResult>

requestContentCardsRefresh()

requestContentCardsRefresh() => Promise<void>

Requests an immediate refresh of content cards from the Braze backend. Fire-and-forget: the returned promise resolves once the refresh has been dispatched, not once new cards arrive. Use the 'contentCardsUpdated' listener to react to fresh cards, or re-read via {@link BrazePlugin.getContentCards} after a short delay.

logContentCardClick(...)

logContentCardClick(options: BrazeLogContentCardClickOptions) => Promise<void>

Logs a click event for a content card. Call when the user taps a card in your UI. Per Braze: only call when bypassing Braze's built-in display module; the SDK's built-in renderer logs clicks automatically.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------- | | options | BrazeLogContentCardClickOptions |

logContentCardImpression(...)

logContentCardImpression(options: BrazeLogContentCardImpressionOptions) => Promise<void>

Logs an impression for a content card. Call when a card scrolls into view in your UI. Per Braze: only call when bypassing Braze's built-in display module.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------------------- | | options | BrazeLogContentCardImpressionOptions |

registerPushToken(...)

registerPushToken(options: BrazeRegisterPushTokenOptions) => Promise<void>

Hands a push registration token to the Braze SDK so the user can receive Braze-orchestrated push notifications. Native-only — the canonical wiring is:

1. Consumer installs @capacitor/push-notifications alongside this plugin.
2. Consumer calls PushNotifications.requestPermissions() and then PushNotifications.register().
3. In the registration listener, consumer forwards the token here via Braze.registerPushToken({ token: event.value }).

Platform behavior:

• iOS: hex-decodes the APNs token and hands it to braze.notifications.register(deviceToken:).
• Android: assigns to Braze.getInstance(context).registeredPushToken (the SDK's setter for manual FCM token handoff).
• Web: throws — Web Push uses VAPID + Service Worker subscriptions, with no token to register manually. See plugin MDC C03 for the divergence policy.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | BrazeRegisterPushTokenOptions |

addListener('featureFlagsUpdated', ...)

addListener(eventName: 'featureFlagsUpdated', listenerFunc: (event: BrazeFeatureFlagsUpdatedEvent) => void) => Promise<PluginListenerHandle>

Subscribes to feature flag updates. Fires whenever the Braze SDK refreshes its feature flag cache — either automatically on session open, manually via {@link BrazePlugin.refreshFeatureFlags}, or after a server-driven sync. Initial state is not replayed when the listener attaches; if you need the current snapshot, call {@link BrazePlugin.getAllFeatureFlags} once after addListener.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------------------- | | eventName | 'featureFlagsUpdated' | | listenerFunc | (event: BrazeFeatureFlagsUpdatedEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('contentCardsUpdated', ...)

addListener(eventName: 'contentCardsUpdated', listenerFunc: (event: BrazeContentCardsUpdatedEvent) => void) => Promise<PluginListenerHandle>

Subscribes to content card updates. Fires whenever the Braze SDK refreshes its content card cache — either on session open, after {@link BrazePlugin.requestContentCardsRefresh}, or after a server-driven sync. Initial state is not replayed when the listener attaches; call {@link BrazePlugin.getContentCards} once after addListener if you need the current snapshot.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------------------- | | eventName | 'contentCardsUpdated' | | listenerFunc | (event: BrazeContentCardsUpdatedEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('inAppMessageReceived', ...)

addListener(eventName: 'inAppMessageReceived', listenerFunc: (event: BrazeInAppMessageReceivedEvent) => void) => Promise<PluginListenerHandle>

Subscribes to in-app message trigger events. Fires once per IAM immediately before the SDK's default presenter would display it. The plugin always returns the SDK's DISPLAY_NOW choice after notifying — listener implementations cannot block display, but they can read the message for analytics, control variants in A/B tests, or react with custom presentation logic. Listener registration after initialize is required; listeners added before initialize is called are silently inert until the underlying native subscription is set up.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------------------------- | | eventName | 'inAppMessageReceived' | | listenerFunc | (event: BrazeInAppMessageReceivedEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('sdkAuthError', ...)

addListener(eventName: 'sdkAuthError', listenerFunc: (event: BrazeSdkAuthErrorEvent) => void) => Promise<PluginListenerHandle>

Subscribes to SDK Authentication error events. Fires when Braze's backend rejects a request signed with the consumer's sdkAuthSignature (expired JWT, rotated-out signing key, mismatched user id). The standard response is to fetch a fresh signature from the consumer's backend and push it back into the SDK via {@link BrazePlugin.setSdkAuthenticationSignature}.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------------- | | eventName | 'sdkAuthError' | | listenerFunc | (event: BrazeSdkAuthErrorEvent) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Removes all listeners registered via {@link BrazePlugin.addListener}. Underlying native subscriptions stay alive (managed by the plugin) so adding a listener again after removeAllListeners works without an initialize cycle.

wipeData()

wipeData() => Promise<void>

Destructive. Removes all locally stored Braze SDK data on the device, including the device ID and any queued unsent events.

Typical use: GDPR Article 17 right-to-be-forgotten flow, or on user logout. After wiping, you almost always also want to:

1. Call your backend's Braze REST /users/delete to remove server-side profile data.
2. Revoke the user's SDK Authentication signature.

See SECURITY.md §10 for the complete privacy flow.

Init-independent: safe to call before {@link BrazePlugin.initialize}.

disableSDK()

disableSDK() => Promise<void>

Halts all data collection by the Braze SDK. No further events or attributes are sent to Braze until {@link BrazePlugin.enableSDK} is called.

Typical use: user revokes marketing consent under GDPR/CCPA without fully wiping their data.

Init-independent: safe to call before {@link BrazePlugin.initialize}.

enableSDK()

enableSDK() => Promise<void>

Re-enables the Braze SDK after a {@link BrazePlugin.disableSDK} call. No-op if the SDK was not previously disabled.

Init-independent on Web and Android (both expose a class-level Braze.enableSdk static). On iOS, BrazeKit 14.x removed the class-level form — re-enabling requires an initialized Braze instance, so this method rejects with the standard init-required error if called pre-init on iOS. See docs/mdcs/C07-INIT-INDEPENDENT-METHODS.md.

isDisabled()

isDisabled() => Promise<BrazeIsDisabledResult>

Returns whether the SDK is currently disabled.

Init-independent on Web and Android. On iOS BrazeKit 14.x there is no class-level isDisabled static; this method returns { disabled: false } pre-init on iOS (uninitialized != disabled, by convention) and reads !braze.enabled post-init. See docs/mdcs/C07-INIT-INDEPENDENT-METHODS.md.

Returns: Promise<BrazeIsDisabledResult>

requestImmediateDataFlush()

requestImmediateDataFlush() => Promise<void>

Forces an immediate flush of any queued events to Braze. Normally Braze batches network requests; this bypasses batching.

Useful for: (1) Layer 4 smoke testing where you want events to appear in the dashboard immediately, (2) edge cases where app may be killed before the next batch.

Requires {@link BrazePlugin.initialize} to have been called.

Interfaces

BrazeEchoResult

| Prop | Type | Description | | ----------- | ------------------- | -------------------------------------------------------------------- | | value | string | The same value passed in, returned by the native bridge unchanged. |

BrazeEchoOptions

| Prop | Type | Description | | ----------- | ------------------- | --------------------------------------------------------- | | value | string | Arbitrary string round-tripped through the native bridge. |

BrazeInitializeOptions

Options passed to {@link BrazePlugin.initialize}.

apiKey is a public Braze SDK API key (the kind embedded in your app). Never pass a REST API key here — they are different things. See SECURITY.md §1.

| Prop | Type | Description | | ----------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | string | Braze SDK API key (public). | | endpoint | string | Braze SDK endpoint, e.g. sdk.iad-03.braze.com. Must be HTTPS in production. For mock-server testing, set {@link BrazeInitializeOptions.allowInsecureEndpoint}. | | enableLogging | boolean | Enable verbose SDK logging. Defaults to false. Never enable in production builds — Braze SDK logs include event payloads which may contain PII. See SECURITY.md §8. | | enableSdkAuthentication | boolean | Enable SDK Authentication (signed JWT validation). Strongly recommended for production. Without it, anyone with the public SDK API key can spoof events for arbitrary user IDs. See SECURITY.md §2 for the full design. | | allowInsecureEndpoint | boolean | Allow non-HTTPS endpoint. Defaults to false and should remain so in production. Only set true for local mock-server testing per SECURITY.md §4. | | sessionTimeoutInSeconds | number | Session timeout in seconds. After this much inactivity, the SDK opens a new session on the next event. Braze's default across all three SDKs is 30 minutes (1800 seconds); supply a value here to override. Must be a positive integer; values ≤ 0 are rejected. Cross-platform note: the plugin contract uses seconds across all three platforms. iOS's underlying setter takes a TimeInterval (a Double of seconds); the iOS bridge casts. Android and Web take seconds directly with no conversion. |

BrazeChangeUserOptions

Options for {@link BrazePlugin.changeUser}. Identifies the current user to Braze; subsequent events and attributes are attributed to this user.

| Prop | Type | Description | | ---------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | userId | string | Your application's unique identifier for this user. Often an internal user ID; treat as PII even if it isn't directly readable as one. | | sdkAuthSignature | string | JWT signature generated by your backend, signed with your private key. Required when SDK Authentication is enabled. See SECURITY.md §2. |

BrazeGetUserIdResult

| Prop | Type | Description | | ------------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | userId | string | null | The current external user ID, or null if the user is still anonymous (i.e. {@link BrazePlugin.changeUser} has not been called). |

BrazeSetSdkAuthenticationSignatureOptions

| Prop | Type | Description | | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | signature | string | New SDK Authentication signature (signed JWT) to push into the SDK. Used to rotate the signature when the previous one expires or when an sdkAuthError event has fired indicating the backend rejected the previous token. See SECURITY.md §2. |

BrazeSetEmailOptions

| Prop | Type | Description | | ----------- | --------------------------- | ------------------------------------ | | email | string | null | Email address. Pass null to clear. |

BrazeSetPhoneNumberOptions

| Prop | Type | Description | | ----------------- | --------------------------- | --------------------------------------------------------- | | phoneNumber | string | null | Phone number, ideally E.164 format. Pass null to clear. |

BrazeSetFirstNameOptions

| Prop | Type | Description | | --------------- | --------------------------- | --------------------------------- | | firstName | string | null | First name. Pass null to clear. |

BrazeSetLastNameOptions

| Prop | Type | Description | | -------------- | --------------------------- | -------------------------------- | | lastName | string | null | Last name. Pass null to clear. |

BrazeSetLanguageOptions

| Prop | Type | Description | | -------------- | --------------------------- | ----------------------------------------------------------- | | language | string | null | ISO 639-1 language code, e.g. "en". Pass null to clear. |

BrazeSetCountryOptions

| Prop | Type | Description | | ------------- | --------------------------- | ------------------------------------------------------------------- | | country | string | null | ISO 3166-1 alpha-2 country code, e.g. "US". Pass null to clear. |

BrazeSetCustomUserAttributeOptions

| Prop | Type | Description | | ----------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | key | string | Attribute key. Max length / character constraints enforced by Braze backend. | | value | BrazeAttributeValue | Attribute value. Use setCustomUserAttribute to remove via wipeData. |

BrazeSubscriptionGroupOptions

| Prop | Type | Description | | ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | groupId | string | The Braze-issued UUID of the subscription group. Find it in the Braze dashboard under Subscription Group → API ID. |

BrazeAddAliasOptions

| Prop | Type | Description | | ----------- | ------------------- | ---------------------------------------------------------- | | alias | string | Alias value. (alias, label) pairs are unique across users. | | label | string | Label / namespace for this alias, e.g. "internal_id". |

BrazeGetDeviceIdResult

| Prop | Type | Description | | -------------- | ------------------- | ----------------------------------------------------------------- | | deviceId | string | The Braze SDK-assigned device identifier for the current install. |

BrazeSetDateOfBirthOptions

| Prop | Type | Description | | ----------- | ------------------- | ---------------------------- | | year | number | Four-digit year. | | month | number | Month as 1-12 (January = 1). | | day | number | Day of month, 1-31. |

BrazeSetGenderOptions

| Prop | Type | Description | | ------------ | --------------------------------------------------- | ----------------------------------------------------------------- | | gender | BrazeGender | Gender value; see {@link BrazeGender}. |

BrazeSetHomeCityOptions

| Prop | Type | Description | | -------------- | --------------------------- | -------------------------------- | | homeCity | string | null | Home city. Pass null to clear. |

BrazeLogCustomEventOptions

| Prop | Type | Description | | ---------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------- | | name | string | Event name. Max length enforced by the Braze backend (~255 chars). | | properties | BrazeEventProperties | Optional event properties. Braze accepts up to ~100 keys per event. |

BrazeLogPurchaseOptions

| Prop | Type | Description | | ---------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | productId | string | Product identifier. Max ~255 chars, alphanumeric + punctuation. Cannot begin with $. Enforced by the Braze backend. | | currency | string | ISO 4217 currency code, e.g. "USD". Required by the plugin even where the underlying Web SDK treats it as optional — having currency on every purchase keeps revenue analytics consistent across platforms. | | price | number | Per-unit price as a non-negative number in the currency's major units (dollars, not cents). The Android bridge wraps to BigDecimal internally. | | quantity | number | Number of units purchased. Defaults to 1. Per Braze: integer in 1-100. | | properties | BrazeEventProperties | Optional purchase properties (same shape as event properties). |

BrazeGetFeatureFlagResult

| Prop | Type | Description | | ---------- | --------------------------------------------------------------------- | ------------------------------------------------------------ | | flag | BrazeFeatureFlag | null | The flag, or null if no flag with this id is configured. |

BrazeFeatureFlag

| Prop | Type | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Feature flag identifier as configured in the Braze dashboard. | | enabled | boolean | Whether the flag is enabled for the current user. | | properties | Record<string, BrazeFeatureFlagPropertyValue> | Map of property keys to typed property values. Empty for flags with no configured properties. Cross-platform note: on Android and Web the properties are the raw Braze wire format and arrive zero-conversion. On iOS the bridge serializes BrazeKit's typed property enum into the same shape; if you find an iOS-specific gap please file an issue. |

BrazeGetFeatureFlagOptions

| Prop | Type | Description | | -------- | ------------------- | ------------------------ | | id | string | Feature flag identifier. |

BrazeGetAllFeatureFlagsResult

| Prop | Type | Description | | ----------- | ------------------------------- | -------------------------------------------------- | | flags | BrazeFeatureFlag[] | All feature flags configured for the current user. |

BrazeLogFeatureFlagImpressionOptions

| Prop | Type | Description | | -------- | ------------------- | ---------------------------------------------------------- | | id | string | Feature flag identifier whose impression should be logged. |

BrazeGetContentCardsResult

| Prop | Type | Description | | ----------------- | ------------------------------- | ------------------------------------------------------------------ | | cards | BrazeContentCard[] | All cards currently cached for the user. Empty if not yet fetched. | | lastUpdated | number | null | Last-refresh time as Unix epoch ms; null if never fetched. |

BrazeClassicContentCard

Classic content card: title + description + optional image and click URL. The most common card type.

| Prop | Type | Description | | ------------------ | ---------------------- | -------------------------------------------------------------- | | type | 'classic' | Discriminator; narrow to a concrete card type with this field. | | title | string | | | description | string | | | imageUrl | string | | | url | string | | | linkText | string | | | clicked | boolean | | | dismissed | boolean | | | dismissible | boolean | | | language | string | | | altImageText | string | |

BrazeCaptionedImageContentCard

Card with a large image, title, and description text.

| Prop | Type | Description | | ------------------ | ----------------------------- | -------------------------------------------------------------- | | type | 'captionedImage' | Discriminator; narrow to a concrete card type with this field. | | title | string | | | description | string | | | imageUrl | string | | | url | string | | | linkText | string | | | aspectRatio | number | null | Aspect ratio hint for image loading. null when not provided. | | clicked | boolean | | | dismissed | boolean | | | dismissible | boolean | | | language | string | | | altImageText | string | |

BrazeImageOnlyContentCard

Image-only card; no title or description.

| Prop | Type | Description | | ------------------ | --------------------------- | -------------------------------------------------------------- | | type | 'imageOnly' | Discriminator; narrow to a concrete card type with this field. | | imageUrl | string | | | url | string | | | aspectRatio | number | null | | | clicked | boolean | | | dismissed | boolean | | | dismissible | boolean | | | language | string | | | altImageText | string | |

BrazeControlContentCard

Control card: represents a user enrolled in the control arm of a content card multivariate test. Should be impression-logged but not rendered as visible content.

| Prop | Type | Description | | ---------- | ---------------------- | -------------------------------------------------------------- | | type | 'control' | Discriminator; narrow to a concrete card type with this field. |

BrazeLogContentCardClickOptions

| Prop | Type | Description | | ------------ | ------------------- | ---------------------------------------- | | cardId | string | Identifier of the card the user clicked. |

BrazeLogContentCardImpressionOptions

| Prop | Type | Description | | ------------ | ------------------- | -------------------------------------------------- | | cardId | string | Identifier of the card that was shown to the user. |

BrazeRegisterPushTokenOptions

| Prop | Type | Description | | ----------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | token | string | The platform-specific push token. On iOS this is the hex-encoded APNs device token (the same string that @capacitor/push-notifications emits in its registration event). On Android this is the FCM registration token. Web does not have a comparable concept (Web Push uses VAPID via the Push API + Service Worker, with no token to register manually); calling on web throws. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

BrazeFeatureFlagsUpdatedEvent

Payload delivered to 'featureFlagsUpdated' listeners. The full current set of feature flags is included on every update; consumers should treat this as a replacement, not a delta.

| Prop | Type | | ----------- | ------------------------------- | | flags | BrazeFeatureFlag[] |

BrazeContentCardsUpdatedEvent

Payload delivered to 'contentCardsUpdated' listeners. Same shape as {@link BrazeGetContentCardsResult}; the full current card set is included on every update, not a delta.

| Prop | Type | | ----------------- | ------------------------------- | | cards | BrazeContentCard[] | | lastUpdated | number | null |

BrazeInAppMessageReceivedEvent

Payload delivered to 'inAppMessageReceived' listeners. Fires once per IAM trigger, immediately before the SDK's presenter would display the message. Listeners cannot block display — the plugin always returns DISPLAY_NOW to the SDK after notifying — but they can read the message contents for analytics, conditional UI changes, or custom presentation overrides.

| Prop | Type | | ------------- | --------------------------------------------------------------- | | message | BrazeInAppMessage |

BrazeSlideupInAppMessage

Sliding banner; auto-dismisses by default. No buttons.

| Prop | Type | Description | | ------------------ | ------------------------------ | --------------------------------- | | type | 'slideup' | | | message | string | | | imageUrl | string | | | imageAltText | string | | | language | string | | | slideFrom | 'top' | 'bottom' | Direction the banner slides from. |

BrazeModalInAppMessage

Centered modal. imageUrl is optional; when present without message text, treat as an image-only modal.

| Prop | Type | | ------------------ | -------------------------------------- | | type | 'modal' | | header | string | | message | string | | imageUrl | string | | imageAltText | string | | language | string | | buttons | BrazeInAppMessageButton[] |

BrazeInAppMessageButton

A single button on a modal / full in-app message. Up to two per message. Index 0 is conventionally the dismiss button; index 1 is the call-to- action. Consumers reading the wire format should treat the order as authoritative — the SDK doesn't expose dedicated primary / secondary roles.

| Prop | Type | Description | | ----------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | id | number | Stable button identifier the SDK uses for click analytics. | | text | string | Display text of the button. | | clickAction | BrazeInAppMessageClickAction | Action to perform when the button is tapped. |

BrazeFullInAppMessage

Full-screen message. imageUrl is optional; when present without message text, treat as an image-only full-screen.

| Prop | Type | | ------------------ | -------------------------------------- | | type | 'full' | | header | string | | message | string | | imageUrl | string | | imageAltText | string | | language | string | | buttons | BrazeInAppMessageButton[] |

BrazeHtmlInAppMessage

Custom HTML rendered inside a WebView. message is the raw HTML; the Braze SDK already sandboxes the WebView (no JS bridge unless allowUserSuppliedJavascript: true was set at init — see