Category onboarding for news and media

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

This playbook implements the News and media strategies hub’s category opt-in onboarding flow as a 5-day Welcome Journey. The Journey progressively nudges readers to complete their profile, pick category preferences, and (optionally) confirm their email — without competing with editorial broadcasts that publish breaking news from the dashboard or API. This Journey is gap-driven: each step checks whether the reader has already taken the action it would otherwise prompt, and stays silent if they have. A reader who arrives fully set up gets only the welcome and final emails. A reader who never returns gets the IAMs and a follow-up email reinforcing what’s still missing.

---

​

At a glance

1. Send a welcome email introducing the company, app, and community.
2. Wait Until the reader has a profile (subscription_status Tag exists). On expiration, show a Profile setup IAM.
3. Wait Until the reader has at least one category Tag set (cat_* = 1). On expiration, show a Category IAM.
4. If either gap remains, send a follow-up email reinforcing what’s missing.
5. After 5 days, send a final email branched on subscription_status (upgrade pitch, community welcome, etc.).

---

​

Onboarding goals

​

Prerequisites

Work through the News and media strategies implementation roadmap before building this Journey. The strategy hub defines the data foundation; this page implements one specific Journey on top of it. Required:

• Familiarity with Journeys concepts — entry/exit rules, Wait Until, and Yes/No branch.
• An active OneSignal app with at least the data foundation from News and media strategies — subscription_status and the cat_* category Tags.
• A Category Prompt or your own category-selection UI on the site to capture the cat_* Tags.
• A preference center page on your site for IAMs and emails to deep-link to. See Deep linking for the configuration.

Recommended:

• The confirmed opt-in Journey. When run in parallel, this Welcome Journey can gate every email step on confirmed_opt_in = true so unconfirmed addresses don’t receive marketing email.
• An HTML in-app message template for the Category IAM. The HTML format lets readers change category preferences inline without leaving the app.

​

Journey configuration

​

Required data

​

Journey segments

Define these once and reuse them across the Journey steps. Has profile:

• Name: “Has profile”
• Filter: subscription_status exists.

A reader matches whenever subscription_status is set to any value (free, metered, subscriber, or lapsed_subscriber). Has selected categories:

• Name: “Has selected categories”
• Filters: cat_breaking_news = 1 OR cat_world = 1 OR (every other cat_* Tag with the same OR).

A reader matches as soon as any one category Tag flips from 0 to 1. Update this segment whenever you add a new category to your data model. Fully onboarded:

• Name: “Fully onboarded”
• Filters: subscription_status exists AND (cat_breaking_news = 1 OR cat_world = 1 OR …).

Used by Step 4’s Yes/No branch — readers in this segment skip the follow-up email.

​

Journey templates

These templates are starting points — clone, edit, and re-use them in your own Journey. They use Liquid syntax for personalization against first_name, subscription_status, favorite_section, and metered_articles_remaining.

​

Email templates

Three emails carry the long-form moments of the Journey. All three skip automatically when the reader has no email Subscription, so the IAMs and gap checks still drive the rest of the flow. Email 1 — Welcome (immediate) Purpose: Introduce the publication, the app, the community, and what to expect. Suggested subject: Welcome to OneSignal News, {{ first_name | default: 'reader' }} Content outline:

• A short welcome and thank-you for opting in.
• 2–3 things the reader can do next — pick categories, follow newsletters, install the app, join your community channel.
• A manage your topics CTA that deep-links to your preference center.
• Links to your social and community channels (Discord, X, YouTube) so they can follow along outside the app.

Email 2 — Reinforce (Day 2, conditional) Purpose: Catch readers who landed in the Journey but haven’t completed their profile or picked categories. A single template that addresses both gaps generically. Suggested subject: Finish setting up your OneSignal News experience Content outline:

• Friendly reminder that they’re a few clicks away from a personalized news feed.
• Two CTAs side by side — one to log in or create an account, one to pick categories. Both deep-link to your preference center.
• A reassurance line that they can update preferences anytime.

Email 3 — Final (Day 5) Purpose: Cross-sell other channels and surfaces, branched by subscription_status. The closing email of the Journey. Branch the content with Liquid (or send conditional templates from a Yes/No branch in the Journey itself):

​

In-app message templates

Two IAMs nudge readers who arrive at a Wait Until expiration branch. IAMs are queued by the Journey step and display the next time the reader opens the app or site. Profile setup IAM Purpose: Convert anonymous readers into authenticated profiles. A standard IAM with a “Log in or create an account” CTA that deep-links to the customer’s auth flow. Keep copy short — one benefit (“personalized news, saved articles, sync across devices”) plus the CTA. Category IAM Purpose: Capture category preferences from readers who haven’t selected any. Two implementation options:

• HTML IAM with inline form. Use the In-App HTML Templates checklist/survey example as a starting point. Render checkboxes for each category; on submit, set the matching cat_* Tag to 1. Highest conversion because the reader doesn’t leave the app.
• Simple IAM with deep-link. A single CTA that deep-links to a preference center page that re-triggers the Category Prompt or shows your custom category UI. Easier to build but adds friction.

The Category Prompt itself can’t be triggered from a Journey IAM directly — Journeys can’t run client-side prompts. Either render the form inline (HTML IAM), or deep-link to a page that triggers the prompt client-side.

​

Journey settings

Entry rules:

• Audience: All users.
• Future additions only: Checked — must stay checked so existing users aren’t bulk-enrolled when the Journey is set live.

Exit rules:

• Default — when the reader moves through the entire Journey.

Re-entry rules: No — the reader can receive this Journey only once.

---

​

Journey steps

The Journey has 5 sequential steps. Each email step is preceded by a Yes/No on confirmed_opt_in = true if you’re running double opt-in in parallel.

​

Step 1 — Welcome email

​

Step 2 — Wait Until profile set

​

Step 3 — Wait Until categories set

​

Step 4 — Follow-up email (if data is missing)

​

Step 5 — Final email (Day 5)

---

​

Best practices

• Don’t compete with editorial sends. Breaking news goes out as one-time dashboard or API campaigns to category segments (cat_breaking_news = 1), not as Journey messages. The Welcome Journey only sends meta messages — welcome, profile/category nudges, and the final upgrade pitch. If you ever feel tempted to add an editorial-style push to this Journey, route it through the Breaking news broadcasts flow instead.
• Initialize all cat_* Tags to 0 at first prompt. Aligns with the Category Prompt pattern and lets the segment distinguish “opted out” from “never saw the prompt.” See News and media strategies → Tags for the full convention.
• Update the “Has selected categories” segment whenever you add a new category. Each cat_* Tag has to be OR’d into the segment manually. Document the segment alongside your category list so it doesn’t drift.
• Gate every email step on confirmed_opt_in = true if you run double opt-in. A reader who hasn’t confirmed should never get marketing email. The IAMs and gap checks still run for them — only the emails skip.
• Keep IAMs short. The Profile and Category IAMs each serve one job. Don’t bundle multiple CTAs into either; readers about to convert on a single ask are derailed by a second one.
• Set a global frequency cap. Editorial sends will reach readers in the same few days as this Journey. A cap on the segment side (e.g., max one push per reader per 4 hours) prevents the editor’s send and any incidental Journey nudges from piling up.
• Lapsed subscribers can stay in the entry rule (“All users, future additions only”), but the Email 3 lapsed-subscriber branch is a stopgap. For most teams, a dedicated win-back Journey handles lapsed subscribers better than a final touch tucked inside the welcome flow.

---

​

FAQ

​

Why doesn’t this Journey send breaking news pushes?

Breaking news is editorially driven and time-sensitive — sent as one-time dashboard or API campaigns to category segments (cat_breaking_news = 1), not as Journey messages. Mixing editorial content into this Journey would either delay breaking news (waiting on the Journey schedule) or compete with the editor’s manual send. Keep the two responsibilities separate.

​

What happens to readers without an email Subscription?

The three email steps skip automatically — OneSignal won’t send an email to a reader who has no email channel. The Wait Until steps and IAMs still run for these readers, so push-only and SMS-only readers still get the gap-driven nudges.

​

What if the reader has email but no push?

Welcome and follow-up emails still send. The IAMs never display because the reader has no app or site session for them to render in. The Journey effectively becomes an email-only flow for this reader.

​

What is the Wait Until step actually checking?

Wait Until listens for the reader to enter the configured segment. The instant they do, the event branch fires and the Journey continues. If 24 hours pass without the segment matching, the expiration branch fires instead. A reader who already qualifies when they reach the step progresses immediately — no IAM is queued.

​

How do I add a new category?

Three steps:

1. Add a new cat_<category> Tag to your data model. Initialize to 0 for new readers, and re-run the prompt for existing readers if you want them to see the new option.
2. Add the category to your Category Prompt or custom category UI.
3. Update the Has selected categories and Fully onboarded segments to OR in the new Tag. Every step using those segments picks up the change automatically.

​

Should I run this alongside the double-opt-in Journey?

Yes if you collect email and want CAN-SPAM / GDPR-aligned consent. Add the confirmed opt-in Journey in parallel, gated on the same audience. This Welcome Journey then checks confirmed_opt_in = true before each email step so unconfirmed addresses never receive marketing email.

​

Why is the entry rule “All users” instead of a more specific segment?

This Journey is gap-driven, not entry-segmented. Every reader is checked at each step against whether they’ve completed the corresponding action; readers who arrived already set up just pass through silently. Future additions only still prevents bulk-enrolling existing users when the Journey is set live.

​

How long does the Journey last?

Roughly 5 days from entry. Step 1 fires immediately, Steps 2 and 3 each have a 24-hour Wait Until window, Step 4 follows immediately, then Step 5 waits 3 more days before the final email.

​

Related pages