Engagement journeys

engagement brings people back to a habit app with reminder ladders that obey a weekly limit, quiet hours and a stop after ignored messages, and it makes dark patterns hard to write.

The limits are declared once in main.yaml and enforced on every engagement message at run time, whichever channel notify picks. Study CX, an app for children aged 6 to 16, is the reference case. It runs inside your app on notify and durable workflows, and it is free. The calls come from mainsdk/notify, and app.engagement is built on first use from the notify.engagement section.

notify:
  engagement:
    max-per-week: 4
    quiet-hours: "21:00-08:00"
    stop-after-ignored: 5
    audience: { children: strict }
    guardian: { controls: [pause, frequency, quiet-hours, view] }
    categories: [reminders]
    active: user.active
    ignored-after: 48h
    send-time: { default: "17:00" }
    copy: { ai: true, limit: $2/month }
    proof:
      finished-today: { kind: count, event: lesson.finished, window: day }
    links:
      offer: https://app.example.com/offer
    measure: { return-within: 48h, unsubscribe-within: 7d }

import { journey, ladder } from "mainsdk/notify";

export const comeBack = journey("come-back", { version: 1, start: "user.inactive", category: "reminders" },
  async ({ user }) => ladder(user, [
    { after: "1d", template: "reminder.gentle" },
    { after: "3d", template: "reminder.gentle-2" },
    { after: "7d", template: "reminder.last" },
  ], { sendAt: "usual" }));

engagement:
  driver: builtin

Quick start

notify:
  channels: [push, whatsapp, email]
  engagement:
    max-per-week: 4                    # required, 1 to 21
    quiet-hours: "21:00-08:00"
    stop-after-ignored: 5
    categories: [reminders]
    active: user.active                # the event that means the person came back

import { journey, ladder } from "mainsdk/notify";

export const comeBack = journey("come-back", { version: 1, start: "user.inactive", category: "reminders" },
  async ({ user }) => ladder(user, [
    { after: "1d", template: "reminder.gentle" },
    { after: "3d", template: { flag: "reminder-copy", variants: ["reminder.a", "reminder.b"] } },
    { after: "7d", template: "reminder.last" },
  ], { sendAt: "usual" }));

Publish user.inactive for a person and the journey starts one run for them. Publish user.active and the run ends with outcome: "returned"; nothing more is sent.

Configuration

notify:
  quiet: { from: "22:00", to: "08:00" }
  engagement:
    max-per-week: 4                         # engagement messages per person per rolling 7 days
    quiet-hours: "21:00-08:00"              # the stricter of this, notify.quiet and the person's own wins
    stop-after-ignored: 5
    audience: { children: strict }          # strict is the only value
    guardian: { controls: [pause, frequency, quiet-hours, view] }
    categories: [reminders]                 # notify categories that count as engagement messages
    active: user.active
    ignored-after: 48h
    send-time: { default: "17:00" }
    copy: { ai: true, limit: $2/month }     # per tenant; past it, the template text
    proof:
      finished-today: { kind: count, event: lesson.finished, window: day }
    links:
      offer: https://app.example.com/offer  # a {{link.offer}} placeholder
    measure: { return-within: 48h, unsubscribe-within: 7d }

Every key has a row in the main.yaml reference. A bad value stops the app at start with MAIN-ENGAGE-0008 naming the key.

What you get

Journeys and ladders

journey(name, { version?, start, category }, fn)       // a durable workflow, one run per person and journey
ladder(user, rungs, { sendAt? })                       // { outcome: "returned" | "stopped" | "finished" }
engagement.register(journey)                           // bind a journey to this app's instance
engagement.start(journey, user)                        // start a run now; one at a time per person
engagement.attach()                                    // listen for `active` and each journey's start event

ladder is built only from waitFor, step and sleep, so it resumes after a crash without sending twice. It waits for the person's return before every rung. app.engagement calls attach() for you.

Sending and status

engagement.send(user, { template, data?, journey?, rung? })   // status: sent | deferred | skipped | stopped, with a code
engagement.sendTime(user)                                      // { at, wait, basis: "usual" | "default" }
engagement.status(user)                                        // { sentThisWeek, ignoredInARow, stopped, nextAllowedAt }
engagement.results(flag, { from, to })                         // per variant: sent, returnRate, unsubscribeRate, winner
engagement.copy(template, { locale, variant? })                // { text, via: "ai" | "template" }
engagement.preferences(user).set({ maxPerWeek? })              // a person may lower their own limit, never raise it

Before each send the SDK checks, in process and from the person's own counters, in this order: the stop signal, opt-outs, the guardian's pause, the weekly limit (MAIN-ENGAGE-0001), the strict rules for children (MAIN-ENGAGE-0005) and quiet hours (the message is deferred to the next allowed minute). urgent: true is refused with MAIN-ENGAGE-0006: engagement never skips quiet hours.

A message counts as ignored when the person sends no active event within ignored-after. After stop-after-ignored ignored messages in a row, the person gets nothing (MAIN-ENGAGE-0002) and their live runs end, until they come back on their own. Only your own first-party activity is used: no open pixels and no rewritten links.

Guardians

engagement.guardian(child).get()
engagement.guardian(child).set({ paused?, maxPerWeek?, quietHours? })   // only lowers or widens

Only a subject that access relates to the child as guardian_of may call this; anyone else gets MAIN-ENGAGE-0004, and so does a change that loosens a limit. Each change is audited.

One-step stop on every channel

An engagement message carries a stop for its category. Stopping takes effect before the next send, asks no "are you sure", and counts as an unsubscribe for the variant that was sent.

import { app } from "mainsdk";

// The device sends back the handle it was given in the push payload's `stop` field.
export async function onStopAction(handle: string) {
  return app().engagement.stopByHandle(handle, { channel: "push" });   // { category, optedOut: true, confirm: false }
}

engagement.optOut(user, { channel, category?, via? }) does the same for a person you already know. Email needs email.unsubscribe-url in main.yaml, because the one-click link is minted by email. The handle is a keyed hash, kept with the person's counters and dropped by engagement.erase(userId).

Links in messages

A link in a message is a {{link.<name>}} placeholder, declared under notify.engagement.links. It is minted through share (ADR-0056) once per journey, rung and variant and never per person, with placement <journey>.<rung>.<variant>. Three recipients of variant a all get the same URL, so the link carries no one's identity.

notify:
  engagement:
    links:
      offer: https://app.example.com/offer

Opens come back as aggregate counts per variant through the getqr webhook preset and share.track.engagement. They appear in engagement.results next to the return and unsubscribe rates, never decide the winner, and never count toward the ignored signal. A link goes through share, never a shortener of your own; see App links for links routes and Share links and QR codes for the host rules.

Send time, variants and copy

• sendAt: "usual" picks the local hour the person was most often active over 28 days, from 24 hourly counters of their own active events, with at least 5 active days and personalisation consent. Otherwise, and always for children, it uses send-time.default. A time inside quiet hours moves to the next allowed minute.
• A rung's { flag, variants } picks its template with the flag, so a person keeps one variant on every instance. engagement.results names a winner only when its return rate beats the first variant's, its unsubscribe rate is no higher, each variant has at least 100 sends and no group is hidden by analytics.min-group.
• With copy.ai: true, engagement.copy writes text with ai.generate using the template as the brief. Placeholders stay as tokens, so no recipient data reaches the model. The copy is cached per tenant, template, version, locale and variant, and must pass the copy rules. A refused answer, a tenant over its limit or a failing driver sends the template text (MAIN-ENGAGE-0003).
• A {{proof.<name>}} placeholder runs a declared analytics query. A hidden, empty or undeclared result sends the text without the proof line (MAIN-ENGAGE-0007). Comparative proof never reaches children.

Children

A children's audience is an age band under 18, a child label, or users.audience: children with no known adult. The strict rules apply even when audience.children is not set: no streak-loss or loss framing, no guilt, no false urgency, no comparison with other people (MAIN-ENGAGE-0005), and the default send time. notify.engagement.guardian is required whenever a child may use the app.

Check, manifest and privacy label

mainsdk check has an engagement gate. The rule pass runs offline; the model pass runs only with check.ai: true and an ai driver, and the output carries a note: line (and notes in --json) when it was skipped.

mainsdk discover --out manifest.json writes notify.engagement into the manifest: the guardrail values, whether the strict rules and guardian controls apply, and each journey with its rungs. mainsdk privacy labels --format web prints the one-line promise, built from the resolved guardrails and never written by hand:

At most 4 reminders a week, none between 21:00 and 08:00, and they stop after 5 are ignored. For children: no streaks, guilt or comparisons, and a guardian can pause or limit reminders.

Pushed config

A push may only tighten: lower max-per-week or stop-after-ignored, widen quiet-hours (paths notify.engagement.max-per-week, notify.engagement.stop-after-ignored and notify.engagement.quiet-hours). A loosening push is refused with MAIN-ENGAGE-0008, the last good value stays, and the refusal is audited.

What is connected, and what is not

app.engagement is wired to notify, email, workflows, events, flags, access (the guardian_of relation), share (links), ai (copy, when the app has an ai section) and jobs (held messages). These modules are not built yet, so set app.socialPorts.engagement = { ... } before the first use if you have your own: analytics (proof queries and the engagement.sent event), privacy (the personalisation consent) and children (the analytics audience rule). Without them, proof lines fall back to the text without proof, send time uses the default basis, and a child is known by ageBand or a child label. engagement.erase(userId) is called by your erase flow until privacy.erase calls it.

Errors and checks

Swapping drivers

engagement has no driver of its own. Messages leave through the channels notify picks, and journeys run on the workflows driver, so swap those: change notify.channels, or workflows.driver. The guardrails and your calls stay the same. See Swap a driver.

Testing

The test app from @mainsdk/testing reads a notify.engagement section like the one above, and time-dependent rules (weekly limit, quiet hours, ignored messages) are tested with createEngagement(deps), which takes a now function so a test can move the clock. Name each test after the spec criterion, for example engagement AC1 skips the fifth message in a week.

Helpers for wiring and tests

Next

• Notifications: the channels, preferences and quiet hours underneath.
• Workflows: the engine behind journeys.
• App links: routes for {{link.*}} placeholders.
• Send engagement reminders: the steps, end to end.