MagicBell Ruby SDK

This library provides convenient access to the MagicBell API for applications written in Ruby. It includes helpers for creating notifications, fetching them, and calculating the HMAC for a user.

Installation

shell
gem install magicbell

Bundler

If you are installing using bundler, add the gem to your app's Gemfile, and run bundle install a usual.

Gemfile
source 'https://rubygems.org'

gem 'magicbell'

Configuration

The library needs to be configured with your MagicBell project's API key and secret.

Global configuration

By default, this library will automatically pick your MagicBell project's API key and secret from the MAGICBELL_API_KEY and MAGICBELL_API_SECRET environment variables, respectively.

Alternatively, you can configure your MagicBell manually. For example, for a rails project, create an initializer file for MagicBell and set your project's keys:

config/initializers/magicbell.rb
MagicBell.configure do |config|
  config.api_key = 'MAGICBELL_API_KEY'
  config.api_secret = 'MAGICBELL_API_SECRET'
end

Per-request configuration

For apps that need to use multiple keys during the lifetime of a process, provide the specific keys when you create instances of MagicBell::Client:

ruby
require 'magicbell'

magicbell = MagicBell::Client.new(
  api_key: 'MAGICBELL_PROJECT_API_KEY',
  api_secret: 'MAGICBELL_PROJECT_API_SECRET'
)

Please keep in mind that any instance of MagicBell::Client will default to the global configuration unless an API key and secret are provided.

Usage

Create a notification

You can send a notification to one or many users by identifying them by their email address:

ruby
require 'magicbell'

magicbell = MagicBell::Client.new

magicbell.create_notification(
  title: 'Rob assigned a task to you',
  recipients: [
    { email: 'joe@example.com' },
    { email: 'mary@example.com' }
  ]
)

Or you can identify users by an external_id (their ID in your database, for example):

ruby
require 'magicbell'

magicbell = MagicBell::Client.new

magicbell.create_notification(
  title: 'Rob assigned a task to you',
  recipients: [
    { external_id: 'DATABASE_ID' }
  ]
)

This method has the benefit of allowing users to access their notifications when their email address changes. Make sure you identify users by their externalID when you initialize the notification inbox, too.

You can also provide other data accepted by our API:

ruby
require 'magicbell'

magicbell = MagicBell::Client.new

magicbell.create_notification(
  title: 'Rob assigned to a task to you',
  content: 'Hey Joe, can give this customer a demo of our app?',
  action_url: 'https://example.com/task_path',
  custom_attributes: {
    recipient: {
      first_name: 'Joe',
      last_name: 'Smith'
    }
  },
  overrides: {
    channels: {
      web_push: {
        title: 'New task assigned'
      }
    }
  },
  recipients: [
    { email: 'joe@example.com' }
  ],
)

Fetch a user's notifications

To fetch a user's notifications you can do this:

ruby
require 'magicbell'

magicbell = MagicBell::Client.new

user = magicbell.user_with_email('joe@example.com')
user.notifications.each { |notification| puts notification.attribute('title') }

If you identify a user by an ID, you can use the magicbell.user_with_external_id method instead.

Please note that the example above fetches the user's 15 most recent notifications (the default number per page). If you'd like to fetch subsequent pages, use the each_page method instead:

ruby
require 'magicbell'

magicbell = MagicBell::Client.new

user = magicbell.user_with_email('joe@example.com')
user.notifications.each_page do |page|
  page.each do |notification|
    puts notification.attribute('title')
  end
end

Mark a user's notification as read/unread

ruby
require 'magicbell'

magicbell = MagicBell::Client.new

user = magicbell.user_with_email('joe@example.com')

notification = user.notifications.first
notification.mark_as_read
notification.mark_as_unread

Mark all notifications of a user as read

ruby
require 'magicbell'

magicbell = MagicBell::Client.new

user = magicbell.user_with_email('joe@example.com')
user.mark_all_notifications_as_read

Mark all notifications of a user as seen

ruby
require 'magicbell'

magicbell = MagicBell::Client.new

user = magicbell.user_with_email('joe@example.com')
user.mark_all_notifications_as_seen

Error handling

This gem raises a MagicBell::Client::HTTPError if the MagicBell API returns a non-2xx response.

ruby
require 'magicbell'

begin
  magicbell = MagicBell::Client.new
  magicbell.create_notification(
    title: 'Rob assigned to a task to you'
  )
rescue MagicBell::Client::HTTPError => e
  # Report the error to your error tracker, for example
    error_context = {
    response_status: e.response_status,
    response_headers: e.response_headers,
    response_body: e.response_body
  }

  ErrorReporter.report(e, context: error_context)
end

Calculate the HMAC secret for a user

You can use the MagicBell.hmac method. Note that in this case, the API secret, which is used to generate the HMAC, will be fetched from the global configuration.

ruby
require 'magicbell'

hmac = MagicBell.hmac('joe@example.com')

You can also use the API secret of a specific client instance to calculate the HMAC:

ruby
require 'magicbell'

magicbell = MagicBell::Client.new(
  api_key: 'MAGICBELL_API_KEY',
  api_secret: 'MAGICBELL_API_SECRET'
)

hmac = magicbell.hmac('joe@example.com')