Skip to main content

Introduction

Courier provides an npm package @trycourier/react-preferences that contains Courier preference enabled React components. Courier Preferences components are ready to plug into your React app to immediately configure user preferences.

In this Guide, we will add the PreferencesList component into a simple Typescript React App that will allow a user to configure which notifications they wish to receive. You can see the final code here Newsletter Preferences

Context​

Let's imagine we have created a newsletter for bird lovers using Courier. When a user first signs up for our newsletter, they are automatically subscribed to receive bird facts. Our newsletter also allows a user to receive bird pictures and bird jokes, but they must choose to sign up for extra communications. We want to create a Typescript React app that will allow users to see and customize their subscribed topics.

Set Up Newsletter Notifications​

We want to have 3 subscription topics for our fellow bird lovers: facts, pictures, and jokes. Let's create a notification to template for these subscription topics for 3 birds: Pigeons, Humminbirds, and Budgies. For simplicity and demonstration, we can create 1 template per bird per topic for a total of 9 notifications.

Example Fact Notification:

Example Fact Notification

Example Picture Notification:

Example Picture Notification

Example Joke Notification:

Example Joke Notification

Total Notifications:

Total Notifications

In order to easily know which message we are sending, we can add a descriptive event name in notification settings

Notification with event

Set Up the Newsletter Preferences​

Let's set up our newsletter preferences section by navigating the preferences in Courier Designer. We can edit the section, and name it Newsletter, as well as pick the channels for delivery.

Newsletter section

Next, let's create the subscription topics.

The first subscription topic, will be our facts topic. We want to have the default status to be OPTED_IN so our users don't need to change anything to receive these notifications.

Facts subscription topic

We will link our 3 bird fact notification templates to this topic

Facts subscription topic linked notifications

The second and third topics, pictures and jokes respectfully, should have an OPTED_OUT status, so users have to set their preferences to receive them. We will link the remaining notifications to these topics

Pictures subscription topic
Pictures subscription topic linked notifications

Our Preferences Designer should look like this.

Preferences Center Designer

When we preview the Hosted Preferences Page we get something that looks like this.

Preferences Center Designer Preview

Publish the page to continue

Embedding the Preferences Center into a Typescript React app​

In this example, we will be adding the Courier Preferences Center to a Typescript React App that uses Webpack 5. You can look at the companion code here.

In our code we used the following:

  • React 17,
  • Typescript,
  • Webpack 5
  • Material UI
  • Eslint
  • Yarn

Adding and Configuring Courier Provider​

In Courier Studio, configure the Courier Provider under channels. Scroll all the way to the bottom and click install provider. Copy and paste your public Client Key and add it to your app as an environment variable in an .env file.

We named our variable REACT_APP_COURIER_CLIENT_KEY

Now, add the trycourier packages @trycourier/react-hooks, @trycourier/react-provider, and @trycourier/react-preferences like so

yarn add @trycourier/react-hooks @trycourier/react-provider @trycourier/react-preferences
All @trycourier packages must be the same version

You also need to add styled-components as it is a peer dependency

yarn add styled-components

Embed Courier Provider into your code 

import {CourierProvider} from '@trycourier/react-provider';

    <CourierProvider
        clientKey={clientKey}
        userId={userName}>
    </CourierProvider>
Configuration

clientKey is obtained from the Courier Provider in the Studio App. userId is a unique id for the user whose preferences you wish to target. In order for a recipient to successfully have their preferences respected by a notification, you must include to.user_id in the Send request. This is because the user_id ties the recipient profile to their set preferences. If no user_id is present in the request, the preferences method will not register.

In the sample app, a dialogue has been created for user input, but the user_id can be hardcoded or an environment variable.

Adding Courier Preferences List​

Now we can add PreferencesList as a child of CourierProvider. CourierProvider will provide preferences with our user context, this will allow PreferencesList to configure the user preferences without the need for more code configuration. 

import {CourierProvider} from '@trycourier/react-provider';
import {PreferenceList} from '@trycourier/react-preferences';
    <CourierProvider
        clientKey={clientKey}
        userId={userName}>
        <PreferenceList />
    </CourierProvider>

Using the Preferences App​

When we first open the sample app, we will see our userName input modal to target the specific user whose preferences we wish to change.

Username modal empty
Once we have submitted a username, we will see the default view of our Preferences Center.
Username modal filled

This list will look the same as the preview of our published preferences center.

Preferences App Default

Subscribing to Notifications​

We can switch the subscription toggles on to subscribe the user into the pictures and jokes subscription topics. We can send the user a message with a picture.

User Id

In order for a recipient to successfully have their preferences respected by a notification, you must include to.user_id in the Send request. This is because the user_id ties the recipient profile to their set preferences. If no user_id is present in the request, the preferences method will not register.

Preferences App Subscribed To All

Courier will see the user is opted in and the message will be sent. The Courier log determining subscription will look like this

User preferences opted in

Unsubscribing from Notifications​

We can click the toggles again to unsubscribe the user from the bird jokes topic. We can send the user a message with a joke.

User Id

In order for a recipient to successfully have their preferences respected by a notification, you must include to.user_id in the Send request. This is because the user_id ties the recipient profile to their set preferences. If no user_id is present in the request, the preferences method will not register.

Preferences App Unsubscribed From Jokes

Courier will see the user is opted out and the message will not be sent. The Courier log determining unsubscribe will look like this

User preferences opted out

Embedding the Preferences Center to Non-React Builds​

You can embed the Preferences Center to non-React builds by using the implementation below:

<div id="root">
  <noscript>JavaScript is required.</noscript>
    <!-- This embedded component comes from the courier-component script defined below and should render the same UI as the hosted preferences page from Courier -->
  <courier-preference-page /> 
  <div id="root" />
  <script type="text/javascript">
    window.courierConfig = {
      clientKey: clientKey, // You can get your client key from https://app.courier.com/settings/api-keys
      userId: userId // The user ID corresponding to the user who is viewing and modifying preferences.
    }
  </script>
  <script src="https://courier-components-xvdza5.s3.amazonaws.com/v3.6.4.js"></script>
</div>

We hope this guide was useful to embed the Courier Preferences Center into a simple Typescript React app.

Was this helpful?