Braze Destination Config Reference Beta

Braze is a customer engagement destination. RudderStack sends events to Braze’s REST API from its servers, loads Braze’s own SDKs in device mode, or combines the two in hybrid mode.

In a Braze destination spec:

• type: braze
• definition_version: 1

Sample configuration

version: rudder/v1
kind: destination
metadata:
  name: braze-prod
spec:
  id: braze-prod
  display_name: Braze Production
  type: braze
  definition_version: 1
  enabled: true
  config:
    data_center: US-03
    rest_api_key: "{{ .BRAZE_REST_API_KEY }}"
    use_platform_specific_api_keys: false
    app_key: "{{ .BRAZE_APP_KEY }}"

    enable_subscription_group_in_group_call: false
    enable_nested_array_operations: false
    send_purchase_event_with_extra_properties: false
    use_ecommerce_recommended_events: true
    support_dedup: true

    enable_braze_logging:
      web: false
    enable_push_notification:
      web: true
    allow_user_supplied_javascript:
      web: false
    track_anonymous_user:
      web: true

    connection_mode:
      web: hybrid
      ios_swift: device
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - marketing

The above example uses one app identifier key for every platform. Because some sources connect in device or hybrid mode and others in cloud or hybrid, it needs both app_key and rest_api_key — see Key dependencies.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Key dependencies

Which keys Braze needs depends on the modes your sources connect in. Rudder CLI enforces each requirement below.

Write use_platform_specific_api_keys out whenever a source connects in device or hybrid mode. When it’s omitted, neither Rudder CLI nor the API asks for app_key or any platform key — so the spec validates and applies, and device mode has no app identifier key to load Braze with.

Connection

App identifier keys

Braze’s SDKs need an app identifier key. Use app_key for every platform, or set use_platform_specific_api_keys: true and give each platform its own key for separate attribution in Braze.

Event settings

Web SDK settings

These keys configure Braze’s web SDK, so they apply only when connection_mode.web is device or hybrid. Each is an object keyed by web, with a boolean value.

Event filtering

Client-side event filtering applies only to sources connected in device mode — the dashboard shows these controls only then, and the SDK is what applies the filter. Rudder CLI accepts the block in any mode, but it has no effect on cloud-mode events, or on the events hybrid mode sends through the API.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode:
  web: hybrid
  ios_swift: device
  react_native: device
  cloud: cloud

Source types

Braze accepts events from these source types in the mentioned connection modes:

In hybrid mode, RudderStack sends every user-generated event — identify, track, page, screen, group, and alias — through Braze’s REST API, and loads Braze’s SDK only for what needs it, such as in-app messages and push notifications. See Braze hybrid mode.

react_native and flutter device mode covers their Android and iOS builds only. A Flutter app deployed to the web can reach Braze in cloud mode only.

The dashboard additionally offers Braze to AMP, Shopify, and Reverse ETL sources. Rudder CLI doesn’t manage those connections, so amp, shopify, and warehouse are invalid here.

Connect a source

An event stream connection to this destination is checked against three rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. An unsupported type reports:

destination 'braze-prod' (type 'braze') does not support source 'my-source':
source type 'amp' is not among supported source types: android, android_kotlin, ...

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'braze-prod' config has no 'connection_mode' entry for source type 'web'

A source connecting in cloud or hybrid mode needs rest_api_key. Device-mode connections don’t. Without it:

destination 'braze-prod' config is missing fields required to connect a 'cloud' source: rest_api_key

The app identifier keys aren’t checked per connection — they’re covered by the destination-level rules in Key dependencies.

Secrets

Rudder CLI treats five keys as secrets: rest_api_key, app_key, android_api_key, ios_api_key, and web_api_key. Write each one you use as a {{ .VAR }} reference and supply the value at apply time:

config:
  rest_api_key: "{{ .BRAZE_REST_API_KEY }}"
  app_key: "{{ .BRAZE_APP_KEY }}"

export RUDDER_BRAZE_REST_API_KEY="..."
export RUDDER_BRAZE_APP_KEY="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

• The YAML that rudder-cli import writes may or may not include secret keys. Before you apply, make sure every secret key your configuration needs is present and populated through variable substitution.
• In device and hybrid mode the app identifier keys are embedded in the app or page, so masking them protects your YAML, not the values themselves.

See How to Use Variable Substitution in Rudder CLI.

See more

• Braze Destination for finding your keys, data centers, and domain allowlisting
• Destination Type Reference for Rudder CLI for the rules shared across destination types
• Destination YAML Reference for the spec envelope