Notifications

Introduction

Looking to maximize your impact? Time spent with your content and user retention is crucial. For this, Prepr contains an actionable notification tool, allowing you to segment your audience and send smart, personalized notifications. Track your results to learn what content captivates your audience and make them come back for more.

Create a Notification Model

Notifications are publications with a title, some text, and a link to the publication on your frontend (such as website or app). To do so, you need a Notification model. You can start with this example and import this in your Prepr Environment:

{
   "id":"c304e7bc-66ad-4e94-83b0-9bb59fe29fda",
   "created_on":"2020-12-21T11:12:19+00:00",
   "changed_on":"2020-12-21T11:13:49+00:00",
   "body":"Notification",
   "description":"Default notification model for email",
   "label":"PublicationModel",
   "status":"published",
   "stories":false,
   "timelines":false,
   "allow_stories":false,
   "channels":false,
   "allow_channels":false,
   "container_required":false,
   "channels_required":false,
   "seo_score":false,
   "slug":null,
   "for":null,
   "fields":[
      {
         "type":"Text",
         "required":false,
         "preview":true,
         "body":"Title",
         "view":"single_line",
         "localized":true,
         "id":"0852ade5-aa0f-4d47-a280-b91b93250696",
         "api_id":"title",
         "created_on":"2020-12-21T11:12:30+00:00",
         "changed_on":"2020-12-21T11:12:30+00:00",
         "label":"PublicationModelField",
         "title":false,
         "seo_title":false,
         "seo_description":false,
         "description":null,
         "disable_editing":false,
         "appearance":"single_line",
         "accept_restrictions":null,
         "no_html":false
      },
      {
         "type":"Text",
         "required":false,
         "preview":true,
         "body":"Summary",
         "view":"single_line",
         "localized":true,
         "id":"bfc1dcb9-71a2-4630-9081-178e921a6df4",
         "api_id":"summary",
         "created_on":"2020-12-21T11:12:38+00:00",
         "changed_on":"2020-12-21T11:12:38+00:00",
         "label":"PublicationModelField",
         "title":false,
         "seo_title":false,
         "seo_description":false,
         "description":null,
         "disable_editing":false,
         "appearance":"single_line",
         "accept_restrictions":null,
         "no_html":false
      },
      {
         "accept":[
            "photo"
         ],
         "max":"1",
         "preview":true,
         "type":"Asset",
         "min":"1",
         "required":false,
         "presets":[
            {
               "name":"email",
               "width":"300",
               "height":"200"
            }
         ],
         "body":"Image",
         "localized":true,
         "id":"5edb04c0-a9d8-4165-92ac-5d59b542b11c",
         "api_id":"image",
         "created_on":"2020-12-21T11:13:00+00:00",
         "changed_on":"2020-12-21T11:13:36+00:00",
         "label":"PublicationModelField",
         "title":false,
         "seo_title":false,
         "seo_description":false,
         "description":null,
         "disable_editing":false,
         "appearance":null,
         "accept_restrictions":null,
         "presets_change_required":false
      },
      {
         "type":"Publication",
         "min":"1",
         "required":true,
         "max":"1",
         "preview":false,
         "body":"Link notification to publication",
         "localized":true,
         "id":"5de90c98-dee8-4f88-894b-92d41e985bef",
         "api_id":"publication",
         "created_on":"2020-12-21T11:13:29+00:00",
         "changed_on":"2020-12-21T11:13:29+00:00",
         "label":"PublicationModelField",
         "title":false,
         "seo_title":false,
         "seo_description":false,
         "description":null,
         "disable_editing":false,
         "appearance":null,
         "accept_restrictions":null
      },
      {
         "type":"Notification",
         "required":false,
         "body":"Notification",
         "id":"4a9de5b8-5c0c-4542-9131-05fe443e732a",
         "api_id":"notification",
         "created_on":"2020-12-21T11:13:45+00:00",
         "changed_on":"2020-12-21T11:13:45+00:00",
         "label":"PublicationModelField",
         "title":false,
         "seo_title":false,
         "seo_description":false,
         "description":null,
         "localized":false,
         "preview":false,
         "disable_editing":false,
         "appearance":null,
         "accept_restrictions":null
      }
   ]
}

This template has the following placeholders:

{{title}}, {{summary}}, {{image}}, {{publication_id}}, {{publication_slug}}, {{publication_url}}.

Field types

The Notification Service supports Text, Assets, Publication link fields.

Text

Text fields are available as their api_id. For Example title is available as {{title}}.

Assets

To add a image to the notification, add a Assets field and add one preset format. The first image and preset are available under the api_id name of the field.

A notification is usually linked to a publication in a front-end or app. Use the Publication link field to connect the Notification that publication.

Build a smart segment

To notify a segment of your audience, you can use the smart segment builder in Prepr (Audience > Segments). Prepr offers a range of segment variables, such as personal details and interaction data. A common used filter is the Subscribed event so users can subscribe to topics they want to be notified about.

Build-in emailservice

Email template configuration

The email template used for notifications can be configured via Settings > Email templates. This configuration tool gives you a plain text editor for your HTML template.

Use placeholders to insert your publication text and publication image(s). You can also use the link placeholder to the publication in your notification. Placeholders need to match exactly with the field api name in your publication model.

In the example above, the placeholders are:
{{notification_title}}
{{notification_summary}}
{{notification_cover}}
{{link}}

Profile fields of the user can be used in the template as well.
{{firstName}}
{{lastName}}
{{email}}

Note

Your notifications are default sent with the Prepr email services. To send notifications from your own email domain, we advise you to integrate your email provider with Prepr (via Settings > Integrations ).

Send a notification

Once the notification field is added, you can now notify your audience.

  • Create a publication with the notification field and fill in the title, other text fields, and an asset.
  • Select the Prepr-publication to which the notification will lead.
  • Select one or more segments you want to notify and choose the email template. The notification will be sent once the publication reached the status 'Published'. The text fields and image fields you preselected in your email template (see below) will appear in your notification.

Email notifications will only be sent if an email template has been selected.

Email domain

Your notifications are default sent with the Prepr email services. To send notifications from your own email domain, we advise you to integrate your email provider with Prepr (via Settings > Integrations).

Custom integration

Webhook configuration

You can configure a webhook in Prepr (via Settings > Integrations) to your own endpoint.

You need to add the publication.published event to the webhook. When a notification publication is published, the event publication.published will be sent to your endpoint.

Handle events

If you have configured your webhooks you start receiving webhook events. There are some steps to process the payload of the webhook event. Because the payload only contains essential data, some lookups are necessary.

1. Retrieve the publication
Retrieve the publication that's have been triggered with notification field, to retrieve the segments to send a notification to.

GET: /publication/{payload.id}?fields=notification,items
{
    "published": {
        "nl-NL": "2020-12-18T15:00:00+00:00"
    },
    "items": {
        ... contents of the publication
    },
    "notification": {
        "nl-NL": {
            "segments": {
                "items": [
                    {
                        "id": "xc4da27c-4de4-4b34-a0c6-ce54854ff1bc" // segment one
                    },
                    {
                        "id": "la5f7e5f-7ee1-499d-8b6f-715327b910c6" // segment two
                    }
                ]
            }
        }
    }
}

In this notification there are two segments triggered (xc4da27c-4de4-4b34-a0c6-ce54854ff1bc and la5f7e5f-7ee1-499d-8b6f-715327b910c6).

2. Retrieve audience
To retrieve the audience that we have to notify you to need to do a request to a audience endpoint.

GET: /persons

Add the received segement IDs to the following request. The response will return unique users. Users that are in two segments will not be in the response twice.

{
    "fields" : "emails", // specify the fields needed
    "segments": [
        {
            "in": [
                "xc4da27c-4de4-4b34-a0c6-ce54854ff1bc",
                "la5f7e5f-7ee1-499d-8b6f-715327b910c6"
            ]
        }
    ],
    "email": [ // (optional) filter check if audience in a segment have a emailadress 
        {
            "has": true
        }
    ]
}

Paginate audience

Don't forget to paginate audience responses , because if the segment(s) contains more audience than resource return limit, you will miss audience to notify!

3. Sending notifications
Now you can loop through your audience list. And using the publication content to notify.

4. (Optional) Personalized
To personalize you need to replace content inside your publication.

For example, the Prepr email notification loops through all items inside the publication and do a search-replace with the values here below:

SearchReplace
{{environment}}Environment name
{{firstName}}Firstname
{{lastName}}Lastname
{{email}}Email address
{{url}}Publication production url

Things to keep in mind

Duplicate events
You should build some logics to prevent replicated events (in case a content editor made a mistake, and re-publish the notification). For example Prepr email notification stores the payload.id + publish.locale as a unique string in a cache layer. You can also update a dedicated boolean field to set it to "Notified".

Multiple locales
You make use of multiple languages, you should keep in mind that you only process the language that is published.