Skip to main content

Create a Notification Preference

Questionnaire​

Before jumping into creating a notification preference, answer these questions:

  1. Which user types does this notification send to?
  2. Does this notification require a new notification preference or will it relate to an existing notification preference?
    • If creating a new notification preference, will it require a new notification category or fit under an existing category?
    • If adding to an existing preference, ping us at #ask-retention-notifications (We haven't documented the process yet!).
  3. Are any toggles involved?
    • 🚦 If toggling notification preferences, read the section on toggles.
  4. Which notification channels (push, email, in-app) will this notification send through?
    • 📩 If sending emails, read the section regarding email.
  5. For each sending channel, will this notification be opt-out or opt-in?1

Option 1: Notification preference generator​

Run the command bin/rails generate notifications:preference and follow the steps to generate the necessary changes.

Option 2: Step-by-step​

Throughout the following steps, don't forget to update i18n config files as necessary.

Step 1: notification_reasons.rb​

The notification_reasons.rb file holds important backend information regarding notification preferences. It holds a list of notification categories and notification reasons2, as well as each notification reason's applicable user groups, communication types, and (optionally) tooltips. This is also where toggling of notification preferences occurs.

1. Add to self.reasons, following the pattern that exists in the file. Be sure to read the comment re: ordering.​

2. If creating a new category, add to self.categories as well.​

Step 2: notification_reason_label.rb​

Our next file, notification_reason_label.rb is used to generate the frontend of the notification preferences page (found at /users/<user-id>/notification_preferences).

All notification reasons must have a label as this provides a user-friendly description for the notification preference. Adding a new label is easy. Add a method that matches the name of the notification reason to notification_reason_label.rb. Its contents will be the translated copy for the notification preference.

✨ That's it for the most basic steps! ✨

But if your use case has toggles, emails, or opt-out notifications, read on.

Additional steps​

Toggles​

If you need to toggle any preferences, do so within the for_user class of notification_reasons.rb. See existing examples. To test in different toggle states, refer to: Testing Locally | Developer Experience.

Email​

Is your email going to send through Mailgun? Does your Mailgun tag not match your key in notification_reasons.rb?

If yes to both, add your mapping to email_tag_map.yml. This piece is important for the Mailgun unsubscribe flow.

Opt-out notifications​

If you want your notification to send by default (giving users the ability to opt-out), add it to the appropriate sections of default_user_types_for_notification.rb. For example, if I wanted an email to send to all potential student recipients who did not explicitly unsubscribe, I'd add it to DEFAULT_EMAILS_FOR_STUDENTS.

Example PRs​

Footnotes​

  1. "Opt-in" refers to a notification that is not sent by default, which a user could subscribe to, aka opt-in to receive. "Opt-out" refers to a notification that is sent by default, which a user could unsubscribe to, aka opt-out of receiving. ↩

  2. A "reason" refers to a notification preference type. A "notification category" groups together related reasons. ↩