Guides

App notices

App notices are service-status screens the SDK draws for you — a screen that holds the app until it's resolved. You publish one from the console and it reaches every matching install the next time it checks in; nothing about your app has to change, and nothing ships to the App Store.

What you can show

Every notice is one of a fixed set of kinds, with a short plain-text title and message you write — up to 60 and 280 characters, with no images and no links in the text. A link button opens either your app's own store listing or an https address on a domain you've verified; a Try again button checks in again instead. Only an owner can publish an update required or retired screen, and a kill switch only from their own session in the console — never an API token or a CI credential.

The current SDKs draw screens only. A banner or a sheet is saved and served as written, but neither SDK shows one, so a maintenance or update-available notice doesn't appear on a device today.

A screen that blocks the app always shows something — there's no silent lock with nothing to look at. On a screen that blocks without a button (only the kill switch can do this), the message is the whole point: it's the one place a notice is allowed to be a dead end, because stopping the app is the point.

Who it reaches

You target a notice the same way you'd describe a release: by app version, build, and the SDK release an install carries, with one comparison each (older than, at least, in a list, and so on). That targeting is resolved on our side, so an older copy of the SDK can never misread it. Two more conditions are checked on the device itself, because only the device knows them: the OS version it's running, and its region. The iOS SDK checks the OS version and not the region: it doesn't show a notice whose conditions name a region at all, so leave the region out of a notice meant for iOS. The Android SDK, which is in private beta, checks both, reading the region the device is set to.

There's no percentage rollout. A notice is a fact about a build, not a campaign, so it either matches an install or it doesn't — every install that matches sees it.

Update available and update required only ever reach people who installed through a storefront — anyone on your own TestFlight or ad-hoc builds updates through that route instead. Every other kind reaches every distribution except your own debug builds, so you're never locked out of a build you're actively working on; a debug build logs what it would have shown instead.

Never a dead end

Before an update notice is saved, we check it against your App Store listing: we fill in the oldest OS it can run on so nobody is sent toward an update their phone can't install, and if the listing shows your current release matching the very versions you're about to block, we ask you to confirm rather than silently save it — the listing can lag a release by a few hours. If a retirement's successor needs a newer OS than some of the people you're retiring are running, we tell you, so you can add a message for them before you publish.

Two things we can't check for you: exactly when your release is live in every country, and whether your app is even listed in all of them. Hold the notice until you've confirmed the release yourself.

The kill switch

The kill switch is the break-glass option: a whole-app stop for a build that's actively doing harm — flooding your own servers, or compromised and leaking data — rather than one that's simply old. You give it a reason, traffic or safety, and name the versions and SDK releases it covers. While it holds, for every matching install:

• The person sees your message on a screen that holds the app.
• The SDK stops capturing and sending anything at all, except the one request that could lift the kill.
• Your app is told it's been killed, so your own code can stop whatever it was doing — the SDK can't stop your app's own network calls or timers for you.
• The SDK never quits your app for you, in the foreground or the background. If a background relaunch — a silent push, a background refresh — would keep a stopped build generating traffic, end that work from the same signal.

When a device can't check in

A kill is meant to be trusted, so it never lifts just because we went quiet for a moment. What a device does without an answer depends on why it has none:

• Offline. Your choice, set when you publish the kill: hold it until the device is back online (the default), or let it come back online running — which only pauses the stop, since the screen returns the instant the device reconnects, even mid-session, until it hears from us again.
• Online, but we don't answer — a brief outage on our side, say. This always holds, and you can't turn it off: if a short restart on our end let a fleet you deliberately stopped start reporting into your servers again, the kill switch couldn't be trusted for the one thing it's for.

A kill ends when any of these happens:

• You lift it, or publish a new one that no longer matches the install.
• The person updates to a version it doesn't name.
• The person reinstalls the app.
• For a standard kill: it has failed to reach us at all across at least three separate days spanning at least six months — the one case that only means we've been gone a long time, which a restart or a short outage can never trigger by itself.

A safety kill marked permanent — for a build that must never run again, whatever happens to your organization with us — skips that last exit and holds even past the end of your agreement with us. While we still serve your app, an owner can lift it from the console like any other kill; once we no longer do, only an update past the versions it names, or a reinstall, clears it. Because of that, a permanent kill can only ever be scoped to named versions, never to “every version, forever,” and we ask you to type a confirmation naming them before we'll save it.

What we can tell you

Every number here is a lower bound, counted from installs that report in under the consent your users granted — see Privacy & consent. An install that doesn't report isn't missing from your count because nothing reached it; it's missing because it doesn't report, which is also true of the installs a notice is aimed at. Read the gap as the shape of your audience, never as delivery failing.

A person who opens the app behind an update required or outage screen still starts a session, and it's treated like any other session in your organization — the app is open and running, even if it's showing a screen instead of your content. An install under a kill switch sends nothing and starts no session, so it adds nothing to your usage; the one request it still makes — the check that could lift the kill — doesn't either. Those checks don't count toward your usage, and we keep nothing from them about any one person or device.

Branding

Every notice screen looks native by default — your app icon, the system colors, your users' own light or dark setting. On plans that include branding, set your own accent, surface and text colors, corner style, and a font your app already bundles. The colors are checked against a contrast floor when you save, so a brand can never ship an unreadable screen. The same look applies to the other forms and prompts the SDK draws in your app.