# How Aivi Works: Live Activities, Widgets, Pushes and Sharing

> How one HTTP request reaches every iPhone that shows a Live Activity or a widget: slugs, pushes, freshness, staleness, and sharing.

Source: https://docs.getaivi.app/concepts/how-it-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.

## The core model

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}`](https://docs.getaivi.app/api-reference/#update-an-activity) or [`PATCH /widgets/{slug}`](https://docs.getaivi.app/api-reference/#update-a-widget), 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](https://docs.getaivi.app/api-reference/#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](https://docs.getaivi.app/events/), and your system confirms it by publishing the new state. See [Buttons and toggles](https://docs.getaivi.app/concepts/interactive/).

## Live Activities and widgets

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

|                    | Live Activity                                                                                                                                                      | Widget                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Lifecycle          | Starts with the first `"state": "ONGOING"` update and ends with `"state": "IDLE"`. See [Activity states](https://docs.getaivi.app/api-reference/#activity-states). | No lifecycle. It is always on screen and shows the latest content you sent.                           |
| Where it shows     | The 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 arrive | Each 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 lasts  | About eight hours, the limit Apple sets, unless you turn on **Long-running** in the app.                                                                           | Until you remove it.                                                                                  |
| Templates          | [Live Activity Templates](https://docs.getaivi.app/templates/)                                                                                                     | [Widget Templates](https://docs.getaivi.app/widget-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](https://docs.getaivi.app/limitations/) page.

## Freshness

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](https://docs.getaivi.app/widget-templates/#progress-template) template’s `end_date` countdown and self-advancing bar, the [Countdown](https://docs.getaivi.app/widget-templates/#countdown-template) target, the [`time_since` / `time_until` formatters](https://docs.getaivi.app/building-blocks/#formatter), and the [Prices](https://docs.getaivi.app/widget-templates/#prices-template) 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](https://docs.getaivi.app/guides/scheduled-updates/), 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](https://docs.getaivi.app/templates/): that is the layer iOS budgets for real-time. A widget can sit alongside it as the persistent summary.

Widgets with buttons, the [Switchboard](https://docs.getaivi.app/widget-templates/#switchboard-template) and the [Remote](https://docs.getaivi.app/widget-templates/#remote-template), get a higher-priority push, so a confirmed press shows sooner. The delays and budgets are on the [Limitations](https://docs.getaivi.app/limitations/#widgets) page.

### Marking content as stale

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](https://docs.getaivi.app/api-reference/#update-a-widget).

## Sharing

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](https://docs.getaivi.app/concepts/interactive/#who-can-press), and the presses reach your account. You can remove a device from the app at any time, and anyone you shared with can unsubscribe.
