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

​

Using Hooks to Create Custom Preferences

These hooks exist as a separate package so that you can build your own interface using our api and state management without having to install all the dependencies that @trycourier/react-inbox or other react-dom based packages include. This is Courier’s out-of-the-box preference page for reference which uses the same hook.

You can use this sample tester to explore and understand Courier’s preference component.

​

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, Hummingbirds, 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 Picture Notification:

Example Joke Notification:

Total Notifications:

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

​

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.

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.

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

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

Our Preferences Designer should look like this.

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

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

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>

​

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.

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

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

​

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.

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

​

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.

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

​

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.