cozy-notifications

cozy-notifications provides tools to send notifications (push or email) from a Cozy application or konnector.

Installation

yarn add cozy-notifications

You will most likely also need a custom webpack config if building for node (for example in konnectors, since mjml and its dependents are not built for node-js).

webpack.config.js

const webpackMerge = require('webpack-merge')
const cozyNotificationsWebpackConfig = require('cozy-notifications/dist/webpack/config')

module.exports = webpackMerge({
  // initialConfig
}, cozyNotificationsWebpackConfig)

The custom webpack config provided by cozy-notifications applies aliases and resolves for cozy-notifications to be used in a build targetting node.

sendNotification

The main entrypoint of this library is sendNotifification(cozyClient, notificationView).

Before being able to use it, we need to define a notification view class.

Notification views

Notification views are responsible for

• fetching the data necessary for the notification
• providing a template for the notification
• configuring the notification (category, channels)
• deciding if the notification should be sent

class MyNotification {
  async buildData() {
    return {
      // data that will be used in the template
    }
  }

  getPushContent() {
    return 'push content'
  }

  getTitle() {
    return 'title'
  }

  getExtraAttributes() {
    return {
      data: {
        // data that will be sent in the notification payload for mobiles
        redirectLink: "settings/#/subscription"
      }
    }
  }
}

MyNotification.template = require('./template.hbs')

getExtraAttributes

In getExtraAttributes, you can pass data that will be sent in the notification payload for mobiles.

getExtraAttributes() {
  return {
    data: {
      // Standardized. When opening the notification, it will open settings app on subscription page.
      redirectLink: "settings/#/subscription",
      // Standardized. When opening the notification, it will refresh the app.
      refresh: true,
      // You can also pass whatever you want.
      age: 42
    }
  }
}

In getExtraAttributes, you can also pass a state (only needed if your notification is stateful).

getExtraAttributes() {
  return {
    // State to send the notification only 1 time per day.
    state: new Date().toLocaleDateString('fr-FR', {
      day: '2-digit',
      month: '2-digit',
      year: 'numeric'
    })
  }
}

preferredChannels

We can define one which channels the user will receive the notification.

MyNotification.preferredChannels = ['mobile', 'mail']

In this example, we first try to send the notification to a mobile, and if it fails to the email address of the user. Some things to know :

• the stack has a fallback by email mechanism. So preferredChannels = ['mobile', 'mail'] is equivalent to preferredChannels = ['mobile'].
• the stack do not check the delivery of the email. So if you set preferredChannels = ['mail', 'mobile'], it is very unlikely that a mobile notification will be sent.

mobile

The mobile channels consists of a push notification. Its title will be the result of the getTitle method and its content will be the result of getPushContent.

mail

Emails need more markup and thus will need the template class attribute. They are written in mjml, making it possible to write good looking emails in every major mail client.

Templates

Templates serve for the HTML content of emails.

Templates used in notification views are based on

• handlebars for templating
• handlebars-layouts to be able to extend layouts
• mjml to build responsive emails

This makes it simple to create emails that are based on built-in templates.

For now cozy-notifications supports only the pre-built cozy-layout template.

This template has the following parts to be filled:

• appName
• topLogo
• appURL
• footerHelp
• content

Since appName, topLogo and appURL will mostly never change inside a particular application, it is advised to create a template extending cozy-layout in your application and then refer to it in each of your email templates.

To provide the content for a particular part, use the following syntax:

{{#content "part"}}
  Content of the part
{{/content}}

where you replace "part" with the name of the part you want to fill.

Note: it is advised in an application to have your templates inside .hbs files for syntax coloring to work correctly. You must configure your bundler and/or test runner to require those files correctly.

app-layout.hbs

{{#extend "cozy-layout"}}
  {{#content "logoUrl"}}https://example.com/logo-url{{/content}}

  {{#content "appName"}}
    My App
  {{/content}}

  {{#content "topLogo"}}{{/content}}

  {{#content "appURL"}}https://my-app.com{{/content}}

  {{#content "footerHelp"}}
    <a href="{{ settingsUrl }}">
      {{tGlobal @root.lang 'settings'}}
    </a>
    <a href="https://support.cozy.io/">
      {{tGlobal @root.lang 'support'}}
    </a>
  {{/content}}
{{/extend}}

Now that we have provided generic parts, we can code a particular template.

A sample template for a particular notification:

my-notification.hbs

{{#extend "app-layout"}}
  {{#content "emailTitle"}}
    A notification from My App !
  {{/content}}

  {{#content "emailSubtitle"}}
    You should read this :)
  {{/content}}

  {{#content "content"}}
    
    {{ greeting name }},

    Just to tell you that My App is awesome !
    
  {{/content}}

{{/extend}}

We can now use our template for a notification view.

import template from './my-notification.hbs'
import appTemplate from './app-layout.hbs'
import { NotificationView } from 'cozy-notifications'

class MyNotificationView extends NotificationView {
  getPartials () {
    return { 'app-layout': appTemplate }
  }
}
MyNotificationView.template = template

Accessing different parts

cozy-notifications is built with the vision that in the future, the whole email will not be sent directly to the stack, but only rendered parts will be sent; in other words, only appURL, topLogo, content etc... will be sent, instead of the whole content). This is why cozy-notifications needs to know our uncompiled partials. We can destructure parts to access rendered parts.

import { renderer } from 'cozy-notifications'
const render = renderer({ partials, helpers })
const { parts } = render({ template, data })
// { "emailTitle": "A notification from My App !", ... }

Built-in helpers

• t will be passed automatically as a helper in templates. We must pass the locales object when instantiating the NotificationView.

const locales = {
  de: {
    hello: "Guten Tag %{name} !"
  }
}

const myNotifView = new MyNotificationView({
  ...,
  locales
})

{{ t "hello" name='Homer' }}

• webLink is able to build links that go the web version of an app

{{ webLink slug="home" }}

• universalLink is able to build links that use automatically the web or mobile version the app

{{ universalLink slug="banks" }}

• palette lets you pick a color by giving its --varName.

  A primary button
 

Related documentation

• Notification configuration and routes on cozy-stack
• Notification custom behavior for flagship app on cozy-stack
• How to debug notifications on flagship app
• How to debug notifications on cozy-banks
• How notifications have been added in devtools on cozy-banks