Feeds v. guides

Knock uses two different concepts to power in-app messaging: feeds and guides. Feeds power notification centers with messages generated in advance by workflow triggers, while guides power in-product UI with content fetched as needed based on targeting rules managed in the Knock dashboard. In this document we'll cover the key differences between the two, and when to use each.

The feeds API enables you to build notification feeds, inboxes, and notification centers that display a chronological list of per-user notifications.

Feed messages are generated ahead of render time by triggering workflows or scheduling broadcasts. When a user opens their feed, the API fetches pre-generated messages and displays them.

• Returns a list of messages generated ahead of time by triggering workflows and scheduling broadcasts.
• Returns messages in reverse chronological order.
• Returns aggregate values for unread counts, read counts, and seen counts, for use in feed badge UIs.
• Can be filtered by status (unread, read, seen, archived) or custom properties.

• When you want to build a notification feed, inbox, or notification center.
• When you want to build a notification experience that can be thought of as a list of items.

The guides API enables you to power in-product messaging using your own UI components. Use guides for announcements, upgrade flows, paywalls, banners, and other UI that doesn't fit the feed-based model.

Guides are data-driven and evaluated at render time. When a user is eligible to see a guide based on targeting and activation rules configured in the Knock dashboard, the API returns the guide data to your application. Your engineering team controls the UI layer, while your content team manages content, targeting, and activation rules in the dashboard.

• Returns guides based on eligibility determined by targeting conditions and activation location rules.
• Can fetch a single guide by its unique key or a list of guides filtered by type (message type).
• Does not include aggregate counts of unseen/unread items.
• Generates messages when a guide is fetched and returned to a user.

• When you need eligibility determined at runtime based on user attributes or application state.
• When you want to control the UI layer in your codebase while non-technical teams manage content and targeting.
• When you need location-based activation rules (showing UI on specific pages or routes).
• For non-feed UI such as modals, banners, tooltips, badges, or inline components like paywalls.