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>
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.
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.
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.
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.
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.
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.