MagicBell Ruby Library
This library provides convenient access to the MagicBell REST API from applications written in Ruby. It includes helpers for creating notifications, fetching them, and calculating the HMAC for a user.
MagicBell is the notification inbox for your web and mobile applications. You may find it helpful to familiarize yourself with the core concepts of MagicBell.
Installation
First, sign up for a MagicBell account and grab your MagicBell project's API key and secret from the "Settings" section of your MagicBell dashboard.
If you just want to use the package, run:
gem install magicbell
Bundler
If you are installing via bundler, add the gem to your app's Gemfile:
# Gemfile
source 'https://rubygems.org'
gem 'magicbell'
and run bundle install
a usual.
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
:
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:
require 'magicbell'
magicbell = MagicBell::Client.new
magicbell.create_notification(
title: 'Rob assigned a task to you',
recipients: [{
email: '[email protected]'
}, {
email: '[email protected]'
}]
)
Or you can identify users by an external_id
(their ID in your database, for example):
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:
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: '[email protected]'
}],
)
Fetch a user's notifications
To fetch a user's notifications you can do this:
require 'magicbell'
magicbell = MagicBell::Client.new
user = magicbell.user_with_email('[email protected]')
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:
require 'magicbell'
magicbell = MagicBell::Client.new
user = magicbell.user_with_email('[email protected]')
user.notifications.each_page do |page|
page.each do |notification|
puts notification.attribute('title')
end
end
Mark a user's notification as read/unread
require 'magicbell'
magicbell = MagicBell::Client.new
user = magicbell.user_with_email('[email protected]')
notification = user.notifications.first
notification.mark_as_read
notification.mark_as_unread
Mark all notifications of a user as read
require 'magicbell'
magicbell = MagicBell::Client.new
user = magicbell.user_with_email('[email protected]')
user.mark_all_notifications_as_read
Mark all notifications of a user as seen
require 'magicbell'
magicbell = MagicBell::Client.new
user = magicbell.user_with_email('[email protected]')
user.mark_all_notifications_as_seen
Error handling
This gem raises a MagicBell::Client::HTTPError
if the MagicBell API returns a
non-2xx response.
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.
require 'magicbell'
hmac = MagicBell.hmac('[email protected]')
You can also use the API secret of a specific client instance to calculate the HMAC:
require 'magicbell'
magicbell = MagicBell::Client.new(
api_key: 'MAGICBELL_API_KEY',
api_secret: 'MAGICBELL_API_SECRET'
)
hmac = magicbell.hmac('[email protected]')
Please refer to our docs to know how to turn on HMAC authentication for your MagicBell project.
API docs
Please visit our website and our docs for more information.
Contact Us
Have a query or hit upon a problem? Feel free to contact us at [email protected].