BrazeRuby

A wrapper for the Braze REST API. Forked from https://github.com/DynamoMTL/appboy

Installation

Add this line to your application's Gemfile:

gem 'braze_ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install braze_ruby

Configuration

Configuration settings may be passed when a new API object is instantiated:

api_key = "instance-api-key"
braze_url = "instance-braze-url"
options = { key: "instance-options" }

api = BrazeRuby::API.new(api_key, braze_url, options)

api.api_key
# => "instance-api-key"
api.braze_url
# => "instance-braze-url"
api.options
# => {:key=>"instance-options"}

Alternatively, you can pass your Braze REST API key, Braze REST URL, and any required Faraday options to the BrazeRuby::configure method. Then, if you instantiate an API object with no arguments it will use these global configuration settings:

BrazeRuby.configure do |config|
  config.rest_api_key = "global-api-key"
  config.rest_url = "global-braze-url"
  config.options = { key: "global-options" }
end

api = BrazeRuby::API.new

api.api_key
# => "global-api-key"
api.braze_url
# => "global-braze-url"
api.options
# => {:key=>"global-options"}

Available `options` keys

retry - Number of times to retry a failed request
open_timeout - Number of seconds to wait for the connection to open
timeout - Number of seconds to wait for the request to complete
middlewares - Array of Faraday middleware to use

Examples

Initializing API

api = BrazeRuby::API.new('<braze-rest-api-key>', '<braze-rest-url')

Track User Attributes

api.track_users(attributes: [{
  external_id: 123,
  first_name: 'John',
  last_name: 'Smith',
  gender: 'male',
  email: 'jsmith@example.com'
}])

Track Attributes for Single User

api.track_attribute(external_id: 123, first_name: 'John', ...)

Track Event

api.track_users(events: [{
  external_id: 123,
  name: 'add-to-cart',
  time: Time.now
}])

Track Events for Single User

api.track_event(external_id: 123, name: 'Event', ...)

Track Purchase

api.track_users(purchases: [{
  external_id: 123,
  product_id: 456,
  currency: 'CAD',
  price: 1.99,
  time: Time.now
}])

Track Purchases for Single User

api.track_purchase(external_id: 123, product_id: 456, ...)

Track Everything for Everyone All at Once

api.track_users(purchases: purchases, events: events, attributes: attributes)

Send Message

Messages Payload

messages = {
  android_push: { alert: 'Hello Android' },
  apple_push:   { alert: "Hello iOS" }
}

Option A, Using External User IDs

api.send_messages(messages: messages, external_user_ids: [123, 456])

Option B, Using Segment ID

api.send_messages(messages: messages, segment_id: '<segment-id>')

Schedule Message

api.schedule_messages(send_at: 1.hour.since, messages: messages, external_user_ids: [123, 456])

Schedule Campaigns

api.trigger_campaign_schedule(
  campaign_id: 'campaign-id',
  recipients: [{ external_user_id: 123 }]
  schedule: { time: Time.now.iso8601 }
)

Delete Scheduled Campaign

api.delete_campaign_trigger_schedule(
  campaign_id: 'campaign_id',
  schedule_id: 'schedule_id'
)

Send Campaigns

api.trigger_campaign_send(
  campaign_id: 'campaign-id',
  recipients: [{external_user_id: 123, trigger_properties: { first_name: 'John' }}]
)

Send Canvas

api.trigger_canvas_send(
  canvas_id: 'canvas-id',
  recipients: [external_user_id: 123, canvas_entry_properties: {first_name: 'John'}]
)

Changing Email Subscription

api.email_status(email: 'john@example.com', status: :opted_in)

List Scheduled Messages and Canvases

api.scheduled_messages(end_time: Time.now.advance(weeks: 2).iso861)

List Segments

api.list_segments

Export Users

By IDs

api.export_users(external_ids: [1])

By Segment

api.export_users(segment_id: segment_id, callback_endpoint: 'https://example.com')

Delete Users

Delete Braze Users with an array of external_ids

api.delete_users([1, 2, 3])

Subscription groups

Get subscription group status for users by id

api.subscription_user_status(external_id: [1])

Get users status for a specific subscription group

api.subscription_status_get(
  external_id: [1],
  subscription_group_id: 'some-uuid'
)

Set user status for a specific subscription group

api.subscription_status_set(
  external_id: [1],
  subscription_group_id: 'some-uuid',
  subscription_state: 'subscribed|unsubscribed'
)

Set user status for a specific subscription group using v2 route

api.v2_subscription_status_set(
  subscription_groups: [
    {
      external_id: [1],
      subscription_group_id: 'some-uuid',
      subscription_state: 'subscribed|unsubscribed'
    }
  ]
)

User Alias

Create an alias-only user

api.create_user_aliases(
  user_aliases: [{
    user_alias: {
      alias_name: "device123",
      alias_label: "my_device_identifier",
    }
  }]
)

Identify an alias-only user

api.identify_users(
  aliases_to_identify: [{
    external_id: 1234,
    user_alias: {
      alias_name: "device123",
      alias_label: "my_device_identifier",
    }
  }]
)

External ID Migration

Rename users' external IDs with an array of external_id_renames

Note: you can send up to 50 rename objects per request.

api.rename_external_ids(
  external_id_renames: [{
    current_external_id: "old_external_id",
    new_external_id: "new_external_id",
  }]
)

Remove users' old deprecated external IDs

Note: you can send up to 50 external IDs per request.

api.remove_external_ids(external_ids: ['old_external_id'])

Email Sync

Get List of or Query Email Unsubscribes

api.email_unsubscribes(email: ['jdoe@example.com'])

Get List of or Query Hard Bounced Emails

api.email_hard_bounces(email: ['jdoe@example.com'])

Remove Email Addresses From Spam List

api.remove_emails_from_spam(email: ['jdoe@example.com'])

Braze catalogs

As of november 2024, Braze catalogs still have some moving parts (beta) and only partial support has been implemented

Create Catalogs

api.create_catalogs(
  catalogs: [
    {
      name: "restaurants",
      description: "My Restaurants",
      fields: [
        {name: "id", type: "string"},
        {name: "Name", type: "string"},
        {name: "Loyalty_Program", type: "boolean"},
        {name: "Created_At", type: "time"}
      ]
    }
  ]
)

List Catalogs

api.list_catalogs

Delete Catalog

api.delete_catalog("restaurants")

Create Catalog Items

api.create_catalog_items(
  "restaurants",
  items: [
    {
      id: "restaurant1",
      Name: "Restaurant1",
      Loyalty_Program: true,
      Created_At: "2022-11-01T09:03:19.967+00:00"
    }
  ]
)

Delete Catalog Items

api.delete_catalog_items(
  "restaurants",
  items: [
    {id: "restaurant1"}
  ]
)

Update Catalog Items

This functions like an upsert, the name of the associated permission api key permission is catalog.replace_items

api.update_catalog_items(
  "restaurants",
  items: [
    {
      id: "restaurant1",
      Name: "NewRestaurantName",
      Loyalty_Program: false,
      Created_At: "2022-11-01T09:03:19.967+00:00"
    }
  ]
)

Debugging

The BRAZE_RUBY_DEBUG environment variable will trigger full printouts of the Faraday gem's HTTP requests and responses.

cd /my/app
export BRAZE_RUBY_DEBUG=true
bundle exec rails whatever

Releasing

Before releasing the CHANGELOG should be updated so that the new version has it's own section and an empty Unreleased section is ready for the next change. New versions are released by running a script locally that bumps the minor level of the gem and then pushes to a GitHub Action that actually sends the new version to RubyGems.org:

$ ./bin/release

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request
Update CHANGELOG

braze_ruby

Development

Runtime