Skip to content
Get the appGet app

How Aivi works

Aivi has two kinds of things to show: Live Activities and widgets. Both work the same way. You set one up once in the app, then your own system sends it content over HTTP, and Aivi pushes that content to every device that shows it.

  1. Create it in the app. In the Activities or Widgets tab, pick a template, a name, and a slug: a short ID such as dishwasher or living-room. The API never creates an activity or a widget; it only updates one that exists.
  2. Send a PATCH. Your system sends the content to PATCH /activities/{slug} or PATCH /widgets/{slug}, with your API token. Each update carries the whole content; it replaces what was there before.
  3. Aivi checks and stores it. The content must be for the template you picked in the app and pass that template’s schema. A request that doesn’t is refused, and nothing changes; see Errors.
  4. Aivi pushes it. Every device that shows the activity or widget gets an Apple push notification, and draws the content with the template on the device itself.

Your system only ever talks to Aivi. It doesn’t need to know which phones show the content, or whether they are online: Aivi keeps that list, and one request reaches all of them.

Some templates also take presses. A press travels the other way, from the phone through Aivi to your system as an event, and your system confirms it by publishing the new state. See Buttons and toggles.

Live Activities and widgets have separate templates and behave differently on the device:

Live ActivityWidget
LifecycleStarts with the first "state": "ONGOING" update and ends with "state": "IDLE". See Activity states.No lifecycle. It is always on screen and shows the latest content you sent.
Where it showsThe Lock Screen and the Dynamic Island; iOS also shows it on the Apple Watch, CarPlay, and the Mac.The Home Screen, the Lock Screen, StandBy, and the Apple Watch.
How updates arriveEach update is pushed to the card itself and shows within seconds.A push asks iOS to reload the widget, which then fetches the latest content. It shows within minutes.
How long it lastsAbout eight hours, the limit Apple sets, unless you turn on Long-running in the app.Until you remove it.
TemplatesLive Activity TemplatesWidget Templates

Use a Live Activity for something that is happening now and will finish: a wash cycle, a charging car, a deploy. Use a widget for state you want to see all the time: battery levels, prices, today’s energy. The two work well together: a widget as the persistent summary, and a Live Activity while a task runs.

iOS sets a budget for both: how many Live Activities can start and how many updates each one gets, and how often a widget reloads. The numbers are on the Limitations page.

Widgets are Aivi’s persistent, best-effort layer. Knowing how updates travel helps you pick the right tool:

  • Content pushes arrive in minutes, not seconds. Updating a widget stores the content and sends a low-priority background push to every device showing it. iOS batches and budgets these pushes to save battery, so a change typically appears within minutes: often faster, occasionally slower (Low Power Mode, a sleeping device). Design for “latest known state”, not for real-time.
  • Predictable data stays live without pushes. Anything the device can compute on its own keeps ticking between pushes: the Progress template’s end_date countdown and self-advancing bar, the Countdown target, the time_since / time_until formatters, and the Prices timeline highlighting the current period. One push can keep a widget correct for hours or days; prefer this over frequent pushes.
  • Known changes can be sent ahead. When you already know what a widget should say later, send those states in one request as a schedule, and the device switches to each one on time on its own.
  • Real-time belongs to Live Activities. If you need second-by-second updates during an ongoing task, use a Live Activity: that is the layer iOS budgets for real-time. A widget can sit alongside it as the persistent summary.

Widgets with buttons, the Switchboard and the Remote, get a higher-priority push, so a confirmed press shows sooner. The delays and budgets are on the Limitations page.

By default a widget shows its last content indefinitely, with no judgement about age; only you know your update cadence. Set stale_after (in seconds) to opt in to staleness: once the content is older than the threshold, the widget visually demotes it and shows an “as of 14:32” line instead of presenting old data as current. You can set it when creating the widget in the app, or per request via the API.

You can share any activity or widget with other people. Send an invite link from the app; accepting it needs the Aivi app, but no account and no subscription. An invite link expires 15 minutes after you create it.

Sharing counts devices, not people: someone with an iPhone and an iPad who accepts on both uses two places.

  • A Live Activity shows on up to 5 devices, and the device you created it on is one of them. That leaves room for 4 more.
  • A widget can be shown by every device signed in to your account, and, besides those, by up to 5 devices you share it with.

A shared activity or widget is still yours. Your API token updates it, and one request reaches every device that shows it. Anyone it is shared with can press its buttons, and the presses reach your account. You can remove a device from the app at any time, and anyone you shared with can unsubscribe.