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"
= { key: "instance-options" }
api = BrazeRuby::API.new(api_key, braze_url, )
api.api_key
# => "instance-api-key"
api.braze_url
# => "instance-braze-url"
api.
# => {: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. = { key: "global-options" }
end
api = BrazeRuby::API.new
api.api_key
# => "global-api-key"
api.braze_url
# => "global-braze-url"
api.
# => {:key=>"global-options"}
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
= {
android_push: { alert: 'Hello Android' },
apple_push: { alert: "Hello iOS" }
}
Option A, Using External User IDs
api.(messages: , external_user_ids: [123, 456])
Option B, Using Segment ID
api.(messages: , segment_id: '<segment-id>')
Schedule Message
api.(send_at: 1.hour.since, 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.(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'
)
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
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