Announcements And Notifications
Build custom announcement feeds, notification inboxes, push preferences, and APNs routing with Gleam SDK APIs.
Last reviewed June 2, 2026
Announcements
Announcements are published updates from the Gleam project. Use them when your app wants a custom changelog, release-note feed, or latest-update card instead of showing the hosted Portal announcements page.
Anonymous users can read public announcements. Signed-in users can also receive targeted announcements when their identity matches the audience.
Fetch announcements
let announcements = try await Gleam.shared.fetchAnnouncements()
let latest = try await Gleam.shared.fetchLatestAnnouncements()
for item in announcements {
print(item.title)
}Notification Inbox
Use notification polling when the app owns its own notification center UI, when APNs is not enabled, or as a catch-up pass after app launch. The API requires an authenticated SDK session.
Poll notifications
let notifications = try await Gleam.shared.fetchNotifications(
limit: 20,
unreadOnly: false
)
if let notification = notifications.first,
let url = try Gleam.shared.url(forNotification: notification) {
// Open this URL in your existing Gleam Portal presentation flow.
}Push Preferences
The SDK exposes only the iOS push preference values currently supported by Gleam: replies and announcements. Render these controls near your app's normal notification settings when you build a custom preferences screen.
Read and update preferences
let preferences = try await Gleam.shared.getNotificationPreferences()
try await Gleam.shared.setNotificationPreferences(
GleamNotificationPreferences(
notifyIosPushReply: preferences.notifyIosPushReply,
notifyIosPushAnnouncement: true
)
)Custom Experience Pattern
A custom update experience usually combines three SDK calls: announcements for product updates, notifications for user-specific follow-up, and preferences for what should become push.
Keep APNs as the real-time delivery channel, but use the in-app notification inbox as the durable state the user can revisit after opening the app.
| Native screen | SDK methods | Typical UI |
|---|---|---|
| What's new feed | fetchAnnouncements(), fetchLatestAnnouncements() | Changelog list, latest update card, release-note detail route. |
| Notification center | fetchNotifications(limit:unreadOnly:), url(forNotification:) | Unread badge, reply/update inbox, tap-to-open request or announcement. |
| Notification settings | getNotificationPreferences(), setNotificationPreferences(...) | Reply and announcement push toggles inside the host app settings. |
| Push routing | registerDeviceToken(...), url(forRemoteNotification:) | APNs registration plus deep links back to the relevant Gleam surface. |
Returned Models
| Model | Fields |
|---|---|
| GleamAnnouncement | id, title, body, publishedAt |
| GleamNotification | id, kind, title, body, linkPath, projectId, postId, commentId, announcementId, readAt, createdAt |
| GleamNotificationPreferences | notifyIosPushReply, notifyIosPushAnnouncement |
Recommended Usage Pattern
Announcements, notification inbox polling, and APNs push solve different parts of the same follow-up problem. Use announcements for published product updates, the inbox for authenticated catch-up state, and APNs for time-sensitive return moments after your app has notification permission.
A simple integration can start with announcements only. Add inbox polling when signed-in users need unread state, and add APNs when replies or shipped requests should bring users back to the exact Portal route.
Keep the polling interval conservative. The app should refresh notifications when it starts, when the user opens the relevant screen, and after foregrounding from a notification tap. It should not run a tight background loop just to simulate push delivery.
Treat unread state as product context, not as a source of truth for billing, security, or permissions. If the app needs to decide whether a user can see a private update, rely on the authenticated SDK session and server response rather than local cache alone.
| Need | Use | Why |
|---|---|---|
| Show public product updates | fetchAnnouncements() or fetchLatestAnnouncements() | Works for anonymous users and gives the app a lightweight changelog or latest-update surface. |
| Show user-specific follow-up | fetchNotifications(limit:unreadOnly:) | Requires an authenticated SDK session and returns the items that belong to the current user. |
| Let users control push behavior | getNotificationPreferences() and setNotificationPreferences(...) | Keeps reply and announcement follow-up aligned with the user's product-level preferences. |
| Bring the user back immediately | APNs registration plus routed notification URLs | Best for replies, shipped requests, and updates that should reopen the app at a specific Portal destination. |