Skip to content

Widgets and Watch complications

The iOS Companion ships with three widgets for iPhone and iPad, plus two complications for Apple Watch. They are read-only surfaces that pull from the Companion's local snapshot store – they do not call the Hub directly. This page covers what each one does, how to add it, and how the privacy toggle works.

Widgets are a thin window onto the Companion

Widgets read a small snapshot file written by the Companion when it last syncs with the Hub. They never reach the Hub themselves. If your Hub is offline, widgets keep showing whatever was in the last snapshot (with a freshness indicator); they do not block, retry, or expose loading errors on the home screen.

What ships in v0.1

iPhone / iPad widgets

Widget Sizes What it shows
Reconnect Lock-screen rectangular, home-screen small One person you have not been in touch with for a while, with the gap (e.g. "4 months").
Today Lock-screen rectangular, home-screen medium Your next calendar event and any birthdays or anniversaries today.
Hub Status Lock-screen circular, lock-screen inline A dot or short string for Hub health: online, catching up, or offline.

A Live Activity widget for in-progress conversation capture stays registered on devices that support it; that one has its own lifecycle and does not appear in the widget gallery alongside the three above.

Apple Watch complications

Complication Family What it shows
Hub Status Corner / circular One-glance Hub health. The same dot the iPhone widget shows, sized for the watch face.
Next Meeting Rectangular The next event from your calendar, with start time.

The Watch complications pair implicitly through the iPhone Companion. Once your iPhone is paired to a Hub, the Watch app and complications become available on your wrist.

Adding widgets to your iPhone

Standard iOS gestures – nothing Ostler-specific.

  1. Lock screen. Long-press the lock screen, tap Customise, tap the lock screen, tap a widget slot, find Ostler, pick the widget you want.
  2. Home screen. Long-press an empty home-screen area until icons jiggle, tap the + in the top-left, search for Ostler, pick the size you want, tap Add Widget.
  3. Today view. Swipe right on the lock screen or first home page to reach the Today view; the Edit button at the bottom lets you add Ostler widgets there.

If a widget is empty after you add it (just shows the placeholder), open the Companion app once. The Companion writes the snapshot the widget reads from on the next sync; until that has happened, the widget shows its gallery placeholder.

Adding complications to your Apple Watch

  1. Long-press a watch face on your Watch.
  2. Tap Edit.
  3. Swipe to the complications page.
  4. Tap a slot, scroll to Ostler, pick Hub Status or Next Meeting.
  5. Press the Digital Crown to confirm.

The Apple Watch app on iPhone (the one that came with iOS) can do the same thing in the My Watch > Complications view, with a larger picker.

The "Hide names on widgets" toggle

By default, App Store builds of the Companion hide names on lock-screen widgets and complications. The Reconnect widget shows "4 months" instead of "Alice, 4 months"; the Today widget shows the calendar interval and event type instead of the meeting title or attendee names; the Hub Status complication is unaffected (no names involved).

This is a deliberate App Store posture: lock-screen widgets are visible to anyone who picks up your phone, even if they cannot unlock it. Names are personal data; an interval is not.

You can change the default in the Companion:

Settings > Privacy > Hide names on widgets

Toggle What lock-screen widgets show What home-screen widgets show
On (default for App Store builds) Interval and verb only ("Reconnect with someone, 4 months") First names allowed; never email or phone
Off First names allowed First names allowed; never email or phone

Home-screen widgets and the Today complication on the Watch follow the home-screen rules, not the lock-screen rules, because they are gated by the Lock-screen view of your phone or wrist – your phone or watch is unlocked when you are looking at them.

The Companion never puts email addresses or phone numbers on any widget surface, regardless of the toggle.

Freshness states

Widgets show a small freshness indicator when the data is older than the Companion expects. Three states:

  • Live – the snapshot was written within the last hour, or whatever cadence the Companion is set to.
  • Stale – the snapshot is older than expected. The widget shows the last value with a subtle stale indicator. Most often this means the Hub is offline or out of range.
  • No data – no snapshot has ever been written on this device. The widget shows a friendly placeholder until the Companion syncs once.

If a widget stays stale for an extended period, the most common fix is to open the Companion to force a sync, or to check the Hub on the Doctor dashboard.

What widgets do not do

Widgets are deliberately small surfaces. They do not:

  • Call the Hub. Reading a snapshot is fast and bounded; calling the Hub from a widget extension would burn the iOS memory budget and confuse the App Store reviewer flag for "background network activity from a widget." Snapshots refresh from the host app, on the schedule the host app sets.
  • Show conversation content. Body text from messages, emails, or notes never makes it onto a widget, by construction.
  • Hold credentials. The widget extension does not have the keys that decrypt the Companion's secure store. It reads from a sandboxed App-Group container that only contains rendered values.

Removing widgets

Long-press the widget on the lock screen or home screen, tap Remove. On the Watch, long-press the face, tap Edit, swap the slot for a different complication.

Removing widgets does not affect the Companion app or the Hub. The next time you add the widget back, it will pick up where it left off as soon as the Companion's next sync runs.