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:
“by 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
=>
“
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:
“by 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
=>
“
Examples
Initializing API
“by api = BrazeRuby::API.new(‘
Maruku could not parse this XML/HTML:
<braze-rest-api-key>', '
“
Track User Attributes
“by api.track_users(attributes: [{ external_id: 123, first_name: John, last_name: Smith, gender: male, email: [email protected] }])
“
Track Attributes for Single User
“by api.track_attribute(external_id: 123, first_name: ‘John’, …)
“
Track Event
“by api.track_users(events: [{ external_id: 123, name: add-to-cart, time: Time.now }])
“
Track Events for Single User
“by api.track_event(external_id: 123, name: ‘Event’, …)
“
Track Purchase
“by api.track_users(purchases: [{ external_id: 123, product_id: 456, currency: CAD, price: 1.99, time: Time.now }])
“
Track Purchases for Single User
“by api.track_purchase(external_id: 123, product_id: 456, …)
“
Track Everything for Everyone All at Once
“by api.track_users(purchases: purchases, events: events, attributes: attributes)
“
Send Message
Messages Payload
“by messages = { android_push: { alert: ‘Hello Android’ }, apple_push: { alert: “Hello iOS” } }
“
Option A, Using External User IDs
“by api.send_messages(messages: messages, external_user_ids: [123, 456])
“
Option B, Using Segment ID
“by api.send_messages(messages: messages, segment_id: ‘
Maruku could not parse this XML/HTML:
<segment-id>')
“
Schedule Message
“by api.schedule_messages(send_at: 1.hour.since, messages: messages, external_user_ids: [123, 456])
“
Schedule Campaigns
“by api.trigger_campaign_schedule( campaign_id: ‘campaign-id’, recipients: [{ external_user_id: 123 }] schedule: { time: Time.now.iso8601 } )
“
Delete Scheduled Campaign
“by api.delete_campaign_trigger_schedule( campaign_id: ‘campaign_id’, schedule_id: ‘schedule_id’ )
“
Send Campaigns
“by api.trigger_campaign_send( campaign_id: ‘campaign-id’, recipients: [123, trigger_properties: { first_name: John }] )
“
Send Canvas
“by api.trigger_canvas_send( canvas_id: ‘canvas-id’, recipients: [external_user_id: 123, canvas_entry_properties: John] )
“
Changing Email Subscription
“by api.email_status(email: ‘[email protected]’, status: :opted_in)
“
List Scheduled Messages and Canvases
“by api.scheduled_messages(end_time: Time.now.advance(weeks: 2).iso861)
“
List Segments
“by api.list_segments
“
Export Users
By IDs
“by api.export_users(external_ids: [1])
“
By Segment
“by api.export_users(segment_id: segment_id, callback_endpoint: ‘https://example.com’)
“
Delete Users
{}
Delete Braze Users with an array of external_ids
“by api.delete_users([1, 2, 3])
“
Subscription groups
Get subscription group status for users by id
“by api.subscription_user_status(external_id: [1])
“
Get users status for a specific subscription group
“by api.subscription_status_get( external_id: [1], subscription_group_id: ‘some-uuid’ )
“
Set user status for a specific subscription group
“by api.subscription_status_set( external_id: [1], subscription_group_id: ‘some-uuid’, subscription_state: ‘subscribed|unsubscribed’ )
“
User Alias
Create an alias-only user
“by api.create_user_aliases( user_aliases: [{ user_alias: { alias_name: device123, alias_label: my_device_identifier, } }] )
“
Identify an alias-only user
“by 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.
“by 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.
“by api.remove_external_ids(external_ids: [old_external_id])
“
Email Sync
Get List of or Query Email Unsubscribes
“by api.email_unsubscribes(email: [[email protected]])
“
Get List of or Query Hard Bounced Emails
“by api.email_hard_bounces(email: [[email protected]])
“
Remove Email Addresses From Spam List
“by api.remove_emails_from_spam(email: [[email protected]])
“
Debugging
The BRAZE_RUBY_DEBUG environment variable will trigger full printouts of the Faraday gem’s HTTP requests and responses.
“sh 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