Introduction

Novu is a high-performant, extremely simplified notification management centre. It lets you receive notifications and events from various channels under one UI component. Finally, Novu offers simple components and APIs to manage all your communication channels (Email, SMS, Direct, Push) all in one place. Although in this tutorial we would only be looking at how to receive Push notifications for Segment events. In this article, we would be learning how to send Push notifications for Segment events using Novu.

Goals

For every track event on Segment, we would like to receive a notification on the Novu Notification centre. This tutorial will be extremely beneficial if you are looking for a neat solution to manage Segment events all in one place.

Prerequisites

A little bit of HTML and JS knowledge.
An existing Segment account If you don't already have one, head over to segment.com and create one; the process is simple and straightforward!

Overview

Here is a simple block diagram describing our workflow.

The Segment engine works with Sources and Destinations.
Sources are entities that provide data in the engine.
Destinations are entities that receive the data flowing out of the engine.
Unfortunately, Segment doesn’t have a native Novu Destination integration yet. So we would need something else to deliver data to Novu from Segment.
Introducing Segment Destination Actions. It’s a cloud function that runs once a destination event has been triggered at Segment. This is a seamless integration into the Segment system and doesn't require any server setup of our own! So using this, payloads could be sent to Novu servers.
This is such an awesome feature that lets us send data to any custom destination we wish to.
The cloud function gets triggered and sends a payload to the Novu servers which then forwards it to our specific client based on the AppID.
Finally, our UI element on the website will be updated as result.

Out of these steps, our part is just to

Write a cloud function that delivers the payload to Novu servers.
Embed the Novu Notification centre onto our website.

Steps

Now that we have a better understanding of the process, let's get started!

Setting up Novu

Head over to https://web.novu.co/ and sign up with your email. You can also use GitHub to log in.
After logging into your Novu account and submitting some basic information, you should be able to see your Novu dashboard. My dashboard is depicted in the screenshot below.
In Novu, we create a notification template with a unique name to distinguish it from the others. Let’s create our first notification template. Hit the New button on the top right. Give a unique identifier to your notification. Then click on Add channel → In-app.

Here you can specify a title and a redirect link upon clicking the notification. You can also choose to opt for SMS and email notifications. But as mentioned earlier in this tutorial, we would only be focussing on Push notifications.

\
You should see the notification has been successfully created once you hit create. Make sure it’s also enabled.
Now go grab your API key from Settings → API keys. Store this somewhere safe, we will need it later as we set up Segment next.

Setting up Segment

Log in to your Segment Dashboard. From the sidebar, select Destinations. Click on the Add Destination button to proceed.
Click on Create Function then pick Destination as a Function type.
Segment offers an in-built code editor and testing environment to build our Destination Functions. As discussed in the overview section earlier, the destination function needs to send the payload to Novu servers every time an event is triggered here at Segment.
Let us first look at how Destination Function is structured. For every Track event of Segment, the below onTrack function is triggered. The code inside this function gets run every time basically. As we would like to hit our Novu servers every time that happens, we would simply be making an API call to NOVU servers with the event payload.

Make the following changes to the below code snippet.

Notification Name: This is the unique name that was set to the intended notification template at Novu.
API endpoint and KEY: Paste your API key inside the placeholder YOUR-API-KEY Feel free to customize the payload according to your needs. I shall be sending only a Hello world text as my goal is just to see if the notification hits Novu centre. Replace the API key that you copied from the Novu dashboard and paste it below.
Payload: Feel free to customize it as per your needs and the event object received from Segment.

async function onTrack(event, settings) {
    const payload = {
        name: "on-boarding-notification",
        to: {
            "subscriberId": "yoyo",
            "email": "hi@hi.com",
            "firstName": "Vitalik",
            "lastName": "Buterin"
        },
        payload: {
            name: "Hello World",
            organization: {
                logo: 'https://happycorp.com/logo.png',
            }
        }
    }
    const endpoint = 'https://api.novu.co/v1/events/trigger';
    const ApiKey = '***YOUR-API-KEY***'; // Your NOVU API key
    let response;
    try {
        response = await fetch(endpoint, {
            method: 'POST',
            headers: {
                Authorization: `ApiKey ${ApiKey}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });
    } catch (error) {
        // Retry on connection error
        throw new RetryError(error.message);
    }
    if (response.status >= 500 || response.status === 429) {
        // Retry on 5xx (server errors) and 429s (rate limits)
        throw new RetryError(`Failed with ${response.status}`);
    }
}

\

Once the code is ready, hit the Run button to test the function. A successful request should be sent. You can also click on the record below from Request Trace to view the response sent by the Novu server. It should be a successful response(2XX)
If it didn’t work as expected, please trace back and troubleshoot your code setup before proceeding ahead.
Insights for troubleshooting
The notification name needs to be an exact match
Make sure the API key is correct
The status code and error response must be helpful. Refer to this doc to know what each status code means.
To verify our communication with Novu servers, look for the payload delivered on the Activity feed of the Novu Dashboard.
Now that we have tested and verified our Destination function. Let’s wrap up the process by providing basic information about our Destination function.
Amazing work We’re almost there
The destination function is now ready to be connected to a destination.
Either you can connect this function to any of the existing Destinations or create a new one. Here is a sample configuration connection on Segment. I have my Test source and Novu instance #1 destination connected to the destination function

Novu Notification centre

We have already confirmed the payload being sent to Novu and received at our Activity Feed. But wouldn’t it be nice to see the notification received on our notification centre in real-time? Now, let’s create a simple HTML page with the Novu embedded in it.
Novu offers two options to render the notification centre
1. IFrame Embed
2. React Component
Follow this documentation guide and pick the one that best suits your needs.
In this article, I will be creating a simple web page with an IFrame embed. The code snippet for the same can be found here.
Here is a final view of our Notification centre in action. As we can see the notifications are already showing up here. On clicking the notification, it should be redirecting you to the custom redirect URL you set earlier for this Notification template.
After configuring everything at Novu. Make sure you toggle to Production to lock in your changes

Summary

Congratulation!! In this tutorial, we learned how to configure and set up both Segment and Novu so that we may receive real-time updates for Segment events.

Final remarks

This was a basic demonstration of how to leverage Segment’s destination function and Novu APIs to receive notifications. In a real-world scenario, one is expected to have multiple notification templates corresponding to the events delivered by Segment. I haven’t created anything of that sort for the sake of simplicity. But you can get creative and satisfy all your needs as you now wield the power of building Novu integrations.

How to integrate Novu with Segment?