Notifications Spec

How to add CM notifications to your app

Notifications Configuration Example

Notifications are defined in your config file.

Here's an example notification config section. It creates one notification to remind users to complete the app's onboarding.

• Content: deliver a message reminding the user to complete setup, with a CTA

• Schedule: this notification will appear 10 minutes after the user dismisses the app.

• Cancelation: the notificaiton will be canceled when the user completes setup

• Timezone: it will be delivered between 9am and 9pm in the user's local timezone.

 "notifications": {
    "completeSetupReminder": {
      "title": "Complete Setup",
      "body": "It only takes 2 minutes to start healthy habbits with LifeTracker.",
      "sound": "default",
      "cancelationEvents": ["completeSetup"],
      "deliveryTimeOfDayStart": "09:00",
      "deliveryTimeOfDayEnd": "21:00",
      "deliveryTime": {
        "eventName": "app_entered_background",
        "eventOffsetSeconds": 600
      }
    }
  }

Notification Config Specification

A top level notifications object in your config file contains a set of named notification maps/objects. Each notification object has the following properties:

Notification Content Properties

• title [optional, string]: the title shown on the notification. If omitted and a body is included, the app's name will be used as the title.

• body [optional, string]: a string for the text content shown in the notification

• actionName [optional, string]: the name of the namedAction to launch when the user taps this notification. If not set, it will launch the app without performing an action.
• sound [optional, string]: the sound to play when the notification is delivered. Values are:

  • omitted: no sound is played

  • “default”: system default notification sound

  • Custom string: a named custom sound embedded in your app binary; see Apple Docs.
• badgeCount [optional, int]: sets the app icon's badge (count). Set 0 to clear the badge. Badge updates can be scheduled in tandem with notification alerts, or simply omit the title/body to schedule a badge update without a notification alert.

Scheduling Notifications

We offer powerful config options to schedule when your users recieve notificaitons.

• idealDeliveryConditions: see our spec on smart notification delivery for details
• deliveryTime [required, object]: specifies when this notification should be delivered. There are two timing options, and exactly one of these must be provided on each notification.deliveryTime object:

  • Exact timestamp, is specified with deliveryTime.TimestampEpoch - an int Unix epoch time in seconds.
  • Relative to an event: the notification is delivered after an event. This is set by deliveryTime.eventName, with optional additional properties listed below.

• deliveryTime.eventName [optional, string]: the event name to fire this notification after.
• deliveryTime.eventOffsetSeconds [optional, int]: the delay between the event specified in eventName and the notificaiton delivery, in seconds.

• deliveryTime.eventInstance [optional, string]: Behaviours are:

  • "latest-once" [default]: will deliver after the latest instance of the event. Once delivered, will not be deliver again. Without an eventOffsetSeconds, this is funtionally the same as "first".

  • "latest" will deliver after the latest instance of the event. This may deliver several times if the event reoccurs.

  • "first": delivers notification once after the first instance of eventName in your app, and only the first.

• deliveryDaysOfWeek [optional, array of strings]: defaults to 7 days a week. This array specifies the days of week where this notification should be delivered in user-local timezone (example: ["Saturday","Sunday"]). If the deliveryTime is not on one of these days, it will be pushed back to the first allowed day.

• deliveryTimeOfDayStart/deliveryTimeOfDayEnd [optional, string]: the start and end time defining when to deliver the notificaiton, in "HH:MM" format, in the user local timezone. For example, start="09:00" and end="21:00" would deliver the notification between 9am and 9pm. If the deliveryTime is not in this range, it will be pushed back to the next time in the range.

• cancelationEvents [optional, array of strings]: if any of the event names listed here are fired, this notification will be canceled, and will never again be scheduled.
• scheduleCondition [optional, string]: a Critical Moments condition string, which is checked before the notification is scheduled. The notificaiton is not scheduled unless this condition returns true.

  • Note: this condition is checked at schedule time, not delivery time. The condition may no longer be true when the notification is delivered. It's helpful to check things unlikley to change (completed_setup, app_version > x), but less helpful for things that change often (has_wifi, device_battery_level).

Less Common Properties

These properties are only needed for more advanced notifications, and can typically be omitted.

• launchImageName [optional, string]: The name of the image or storyboard to use when your app launches. Apple docs.
• relevanceScore [optional, float]: The score the system uses to determine if the notification is the summary’s featured notification (from 0 to 1).

• interruptionLevel [optional, string]: one of "active", "critical", "passive", "timeSensitive". See Apple docs for details. "timeSensitive" requires you to set the "Time Sensitive Notification" capability on your app, and "critical" require approval from Apple.

Combining with Other Notification Systems

You can easily use your own notifications, such as push, along side Critical Moments. Our notification delegate will only handle notifications originating from Critical Moments, and will pass through any others to the notification delegete you set.