Ruby On Rails Plugin

🚧

Backend SDKs in User Model Beta

You still can try using new User Model endpoints, we advise customers to not use these SDKs in production.

Setup

Before configuring your Ruby on Rails application, please follow the Email Quickstart here: https://documentation.onesignal.com/docs/email-quickstart

Installation

Add this line to your application's Gemfile:

gem 'onesignal-rails-plugin', '~> 1.0.0'

And then execute:
$ bundle
Or install it yourself as:
$ gem install onesignal-rails-plugin
Or install from Github:
$ gem "onesignal-rails-plugin", '~> 1.0.0', git: 'git://github.com/OneSignal/onesignal-rails-plugin.git'

Configuration

To change all mailers to target the OneSignal integration, edit config/application.rb or config/environments/$ENVIRONMENT.rb and
add/change the following to the ActionMailer configuration

config.action_mailer.delivery_method = :onesignal

Alternatively a specific mailer can be configured to use the OneSignal delivery method. Within your mailer

class MyOneSignalMailer < ActionMailer::Base
  self.delivery_method = :onesignal  
  def some_email(params)
    mail(...)
  end
end

The OneSignal-specific configuration information can be set in either environment variables or more dynamically via code. To access your app ID
and REST API key, please view the documentation.

There are three options to specify your app ID and REST API key to the plugin, depending on your needs.

1. Using Environment Variables
2. Using Application Configuration
3. Using ActionMailer Configuration

Option 1. Using Environment Variables

Ensure the OneSignal environment variables have been set and they will be picked up automatically by the plugin

ONESIGNAL_APP_KEY = 'YOUR_API_KEY'
ONESIGNAL_APP_ID = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

Option 2. Using Application Configuration

The OneSignal::Rails::Plugin module can be configured in code by creating initializer file config/initializers/onesignal_rails_plugin.rb and adding the following
(Warning: for security purposes, REST API keys should not be hardcoded into your application)

OneSignal::Rails::Plugin.configure do |c|
  c.app_key = 'your-app-key'
  c.app_id = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
end

Option 3. Using ActionMailer Configuration

For more granular and dynamic control you can specify the configuration within a specific mailer. Within your mailer add the following (Warning: for security purposes, REST API keys should not be hardcoded into your application)

class MyExistingMailer < ActionMailer::Base
  self.delivery_method = :onesignal
  self.onesignal_settings = {
      app_key: 'your-app-key',
      app_id: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
    }

  def some_existing_email(params)
    mail(...)
  end
end

Usage

If the purpose of the mailer is to generate a transactional email where the recipient, subject, and body are specified within the application, no additional changes are required. Your existing mailers will now send emails through your OneSignal integration!

OneSignal Extensions

The mail functionality is extended to include additional attributes provided by the OneSignal API. These attributes should be specified within your mailer through the mail invocation. See Examples for examples of how to invoke mail to exploit these extensions.

template_id (string)

Specifies the id of a template created within OneSignal that should be used, rather than the body provided by your application (either via the body parameter, or defined within the view of the mailer). To use the subject within the template, specify a OneSignal::Rails::Plugin::USE_TEMPLATE_SUBJECT within the subject parameter. If the subject parameter is set to anything else, it will be used as the subject of the email, overriding the subject within the template.

include_external_user_ids (string array)

A string array that lists the OneSignal external IDs that are to be the recipients of the email being sent, rather than the information provided by your application via the to parameter.

include_player_ids (string array)

A string array that lists the OneSignal player IDs that are to be the recipients of the email being sent, rather than the information provided by your application via the to parameter.

included_segments (string array)

A string array that lists the OneSignal segments that are to be the recipients of the email being sent, rather than the information provided by your application via the to parameter.

excluded_segments (string array)

A string array that lists the OneSignal segments that will not be the recipients of the email being sent (all others will), rather than the information provided by your application via the to parameter.

custom_notification_args (object)

An object that allows for customizing the email notification that will be sent. Each property key and value of the object will be copied into the payload of the create notification operation.
This allows for greater customization of notification being sent. Example of parameters that would most likely be specified within this object:

• external_id: Correlation and idempotency key.
• send_after: Schedule the message for future delivery.
• throttle_rate_per_minute: throttle delivery of the notification, either because throttling is not enabled at the application level or to override the application level throttling settings.

Examples

The following shows examples of how to invoke the mail function within your mailer when integrated with OneSignal. Note the body is not specified as it is assumed to be generated through the view associated to the mailer. This is not an exhaustive list, and different examples could be combined depending on your specific scenario.

# Send a transactional email to a specific recipient (standard ActionMailer usage) 
mail(subject: "email example", from: '[email protected]', to: '[email protected]')

# Send a transactional email, relying on the OneSignal default 'from' address specified within the OneSignal dashboard
mail(subject: "use OneSignal default from address example", to: '[email protected]')

# Send an email using a OneSignal template as both the subject and body of the email
mail(subject: OneSignal::Rails::Plugin::USE_TEMPLATE_SUBJECT, to: '[email protected]', template_id: '00000000-0000-0000-0000-000000000000')

# Send an email using a OneSignal template, overriding the subject specified on the template
mail(subject: "template subject override example", to: '[email protected]', template_id: '00000000-0000-0000-0000-000000000000')

# Send an email to a list of OneSignal users via their external user IDs
mail(subject: "external id example", include_external_user_ids: ["User123", "User456"])

# Send an email to a list of OneSignal users via their player IDs
mail(subject: "player id example", include_player_ids: ["00000000-0000-0000-0000-000000000000", "11111111-1111-1111-1111-111111111111"])

# Send an email to a list of OneSignal users that are within the provided segments
mail(subject: "include segments example", included_segments: ["Subscribed Users"])

# Send an email to the app's audience, excluding the provided segments.
mail(subject: "excluded segments example", excluded_segments: ["Engaged Users"])

# Send an email with the external_id, which ensures idempotency
mail(subject: "set external_id example", to: '[email protected]', custom_notification_args: { 'external_id' => "00000000-0000-0000-0000-000000000000" })

# Send an email after a certain time
mail(subject: "send after example", to: '[email protected]', custom_notification_args: { 'send_after' => "2022-05-19 15:20:00 GMT-0400" })

# Send an email with rate throttling to 1 per minute
mail(subject: "throttle rate example", to: '[email protected]', custom_notification_args: { 'throttle_rate_per_minute' => 1 })