BrazeAPI

The BrazeAPI gem is a Ruby wrapper for the Braze REST API

Installation

Add this line to your application's Gemfile:

gem 'braze_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install braze_api

Usage

First you must create a client instance with your api_key, app_id, and braze_url:

braze = BrazeAPI::Client.new(api_key: YOUR_API_KEY, app_id: YOUR_APP_ID, braze_url: YOUR_BRAZE_URL)

Once you've created your braze instance you can call a number of methods to the endpoints available in the gem:

Users Track endpoint:

Track

braze.track(events: [], purchases: [], attributes: [])

With this method you can pass multiple event, purchase, and/or attribute objects at once. It will add a timestamp (current time) and your app_id to the event and purchase objects.

For single tracking objects you can call like:

braze.track_event({ external_id: '123', event_name: 'A great event' })
braze.track_purchase({ external_id: '123', product_id: 'Space1', currency: 'GBP', price: 12.50 })
braze.track_attribute({ external_id: '123', first_name: 'Janie' })

These methods call track with just the single object

• Event object documentation
• Purchase object documentation
• User Attributes object documentation

Users Alias Endpoint:

Alias

braze.track(alias_name: 'test@email.com', alias_label: 'email')

This method creates a user alias in Braze when passed an alias_name and an alias_label.

Users Identify Endpoint:

Identify

braze.identify(user_alias: { alias_name: 'test@email.com', alias_label: 'email' }, external_id: '123')

This method identifies an alias user when passed a user alias and an external id.

Users Export Endpoint:

Export Users

Called with an array of external ids and not passed fields to export will return all fields for each of the users corresponding to the ids.

braze.export_users(external_ids: ['123', '345'])

Called with an array of external ids and passed fields to export will return only those fields for each of the users corresponding to the ids.

braze.export_users(external_ids: ['123', '345'], fields_to_export: ['purchases','email_subscribe'])

Called with an email and not passed fields to export will return all fields for each of the users with that email.

braze.export_users(email: 'hello@gmail.com')

Users Delete Endpoint:

Delete Users

Called with an array of external ids returns an object with the number of users queued for deletion

braze.delete_users(external_ids: ['123', '345'])

Called with an array of braze ids returns an object with the number of users queued for deletion

braze.delete_users(braze_ids: ['123', '345'])

Called with an array of user aliases returns an object with the number of users queued for deletion

braze.delete_users(user_aliases: [ { user_alias: { alias_name: 'pete', alias_label: 'sampras' } } ])

Subscription Groups Status Set Endpoint:

Update Status

With this method you can update a user's subscription state for a particular subscription group. It is called with an email or an external id for an email subscription group, and with a phone number or external id for a push subscription group.

braze.update_status(
  external_id: '123',
  subscription_state: 'subscribed',
  subscription_group_id: 'b6dw887f-d8de-456f-345a-fc5ad8734723'
)
# With only an email for an email subscription group
braze.update_status(
  email: 'hello@gmail.com',
  subscription_state: 'subscribed',
  subscription_group_id: 'b6dw887f-d8de-456f-345a-fc5ad8734723'
)
# With only an phone for a push subscription group
braze.update_status(
  phone: '+440000000000',
  subscription_state: 'subscribed',
  subscription_group_id: 'b6dw887f-d8de-456f-345a-fc5ad8734723'
)

Subscription Group Status Endpoint:

Get Subscription Group Status

With this method you can get a user's subscription group state. One of external_id or email or phone is required for each user. The external_id, email, phone can be passed as an array of strings with a max of 50. Submitting both an email address and phone number (with no external_id) will result in an error.

# With an external_id (can also be an array)
braze.status(
  external_id: '123',
  subscription_group_id: 'b6dw887f-d8de-456f-345a-fc5ad8734723'
)
# With an email (can also be an array)
braze.status(
  email: 'hello@gmail.com',
  subscription_group_id: 'b6dw887f-d8de-456f-345a-fc5ad8734723'
)
# With an phone (can also be an array)
braze.status(
  phone: 'hello@gmail.com',
  subscription_group_id: 'b6dw887f-d8de-456f-345a-fc5ad8734723'
)

Subscription Groups Statuses Endpoint:

Get Subscription Groups Statuses for a User

With this method you can get a user's subscription group states. It is called with an email and an external id for an email subscription group, and with a phone number and an external id for a push subscription group.

# With only an email for email subscription groups (email can also be an array)
braze.statuses(
  external_id: '123',
  email: 'hello@gmail.com',
)
# With only an phone for sms subscription groups (phone can also be an array)
braze.statuses(
  external_id: '123',
  phone: '+440000000000',
)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/appearhere/braze_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the BrazeAPI project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.