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: '[email protected]'
}])

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: '[email protected]', 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: ['[email protected]'])

Get List of or Query Hard Bounced Emails

api.email_hard_bounces(email: ['[email protected]'])

Remove Email Addresses From Spam List

api.remove_emails_from_spam(email: ['[email protected]'])

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

EDIT : This functions hints at functioning like an upsert but actual API behaviour is more of the create if not existing. Further calls on items already existing will do nothing. Use edit_catalog_items for that, see below 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"
    }
  ]
)

Edit Catalog Items

This functions actually updates items. The update catalog items does not. This is very confusing and Braze support answers late nov 2024 did not clarify this point. TL;DR Actual behaviour is update_catalog_items functions more or less like an create if not existing. edit_catalog_items functions like an update without the creation bit if it item does not already exists. This will stay in an in-between state while Braze continues working on its implementation.

edit_catalog_items only updates the property in the payload, it does not reset value for the existing properties that were omitted.

When fixed we will be able to better name things

api.edit_catalog_items(
  "restaurants",
  items: [
    {
      id: "restaurant1",
      Name: "NewRestaurantName",
    }
  ]
)

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

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