← Back to Docs

iOS App, Widgets, & Push Notifications

The herbe.calendar iPhone app brings the unified calendar to your phone — with iCloud calendar integration, home-screen widgets, push notifications, and native gestures. This guide covers installation, pairing, what you get, and how to set up each piece.

Installing via TestFlight

The iOS app is currently distributed through Apple's TestFlight beta program. You need an Apple ID and the TestFlight app to install.

  1. Install TestFlight from the App Store on your iPhone (free, made by Apple).
  2. Ask your account administrator to add your Apple ID email to the herbe.calendar tester list.
  3. You'll receive an invitation email from Apple — tap View in TestFlight.
  4. In TestFlight, tap Accept on Herbe Calendar, then Install.
  5. The app appears on your home screen with the herbe logo.

TestFlight builds expire after 90 days. You'll get a reminder when a new build is available — tap Update in TestFlight to install it. When the app moves to the App Store proper, you'll just install it like any other app.

Pairing your phone

Your phone doesn't store your work password — instead it's linked to your web session via a one-time pair code. This means no separate iOS login flow and your phone only has access for as long as you allow.

First launch

Open the app — it shows an 8-character pair code with a Copy button. Tap it.

On the web app

Sign in to herbe.calendar in any browser, go to /mobile-pair (or scan the QR shown by the iOS app). Paste the code, pick the account you want the phone to act as if you belong to several, and click Pair.

Back on the phone

Within a few seconds the app switches to your calendar — fully signed in. iOS will ask for notification permission and calendar access; allow both for the full experience. You won't need to pair again unless you sign out or reinstall the app.

Pair codes expire after 10 minutes and are single-use. If you re-pair, your previous device pairings for the same account are automatically revoked.

iCloud / Apple Calendar integration

This is the headline reason to install the app even if you mostly work from your laptop. The herbe iPhone app reads your iCloud, Exchange, Gmail, and any other system calendars directly from your iPhone's Calendar app and pulls them into the unified view.

Why this matters

  • Your personal appointments (dentist, school pickup, gym) live in your phone's Calendar — they've never been visible to herbe.calendar before. Now they show up so colleagues can't book over them.
  • Apple doesn't expose a Calendar API to third parties — there is no Google-Calendar-style OAuth for iCloud. Reading them through the iPhone's on-device Calendar app is the only practical way.
  • Events stay private to you: even though they sync to the server so they appear when you open herbe.calendar on a different computer, only your own account ever sees them. Sharing your calendar with a colleague shows them only as busy, not the event title — unless you change your sharing level.
  • They also feed into booking availability — clients booking via your share link won't be offered a slot that conflicts with your personal calendar.

How it works

  1. On first launch, the app asks for permission to read calendars. Allow.
  2. The app reads every iOS calendar you have enabled and uploads them to the herbe server (90-day window — 30 days back, 60 days forward). This happens whenever the app foregrounds.
  3. Each iOS calendar (Personal, Work, Family, Birthdays, etc.) appears as its own toggleable entry in the Calendars dropdown, grouped under iOS, in the same color iOS uses for it.
  4. You can turn individual iOS calendars on/off from the herbe Calendars sheet — same as any other source.

Read-only for now

iOS calendar events are read-only inside herbe.calendar. To edit or delete them, open the Apple Calendar app. (Write support — creating events directly into your iCloud calendar from inside herbe — is wired up in the code but disabled in this build while we tighten the permission flow.)

Comparison with ICS subscription: you can also subscribe to an iCloud calendar via a public ICS URL — see the Integrations guide. The iPhone-app path doesn't require making your calendar public, supports more calendar types (Exchange, system calendars), and refreshes more often — but only works on devices where the iOS app is paired.

Home-screen & lock-screen widgets

The app ships with three widgets you can add to your home screen, plus accessory widgets for the iPhone Lock Screen and the Apple Watch–style always-on display.

Events widget

Today's schedule. Available in three home-screen sizes:

  • Small — up to 3 upcoming events plus a date block.
  • Medium — two columns, up to 8 events from today + tomorrow with a TOMORROW divider.
  • Large — same layout but holds up to 14 events. Switches to a single full-width column when the agenda is short.

Each row shows the time, a thin colored bar indicating the source (ERP red, Outlook blue, Google green, iOS gray), the title, and a sub-line with location or source label. Tap any event to open it in the app. The small + button at the bottom-right of every size jumps straight into the new-event form.

Tasks widget

Your open ERP, Microsoft To Do, and Google Tasks rolled up. Small shows the most urgent task with an overdue indicator; medium and large list more. Tap a row to open the task editor.

New widget

A one-tap shortcut to the new-event or new-task form. Useful pinned to the home screen for people who frequently jot down meetings on the go.

Lock-Screen accessory widgets

On iOS 16+, you can pin a herbe widget directly to the iPhone Lock Screen. Three styles:

  • Inline — a single line above the clock showing the time + title of the next event.
  • Circular — fits one of the small circular slots, shows just the next event's start time.
  • Rectangular — a wider strip with time range + title + total event count.

Glance at your phone without unlocking and see what's next. Tap to jump in.

How to add a widget

  1. Long-press on an empty area of your home screen until the icons jiggle.
  2. Tap the + in the top-left corner.
  3. Search for Herbe, pick a size, then Add Widget.
  4. For Lock-Screen widgets: long-press the Lock Screen → Customize → tap a widget slot → search Herbe.

Widgets refresh automatically whenever your data changes (after a foregrounding, push, or pull-to-refresh). You can also force a manual refresh by long-pressing the widget → Edit Widget → close — iOS rebuilds it.

Push notifications & alert preferences

herbe.calendar sends a notification to your phone when something happens that you should know about. Notifications go to two places in parallel: iOS push (a banner on your phone, even when the app is closed) and the in-app inbox (red dot on the hamburger button — view past notifications under the menu).

When you get a notification

  • Event reminders — 15 minutes before each meeting (configurable lead time, can be turned off per source).
  • New activity assigned to you — when someone creates an ERP activity with you on the persons list, OR adds you to an existing one.
  • Activity edited / cancelled — when someone changes or deletes an activity you're on or watching.
  • Comment / file on a watched activity — for any ERP activity you've marked with the watch (bell) icon.
  • Booking received / cancelled — when a client books or cancels a slot via your share link or Calendly.

Lifecycle events (assignment, edit, cancel, booking, imminent reminders) are sent as time-sensitive — they break through iOS Focus modes (Work, Do Not Disturb, Sleep). Informational events (comments, file additions) respect Focus.

Auto-watch

When you're assigned to an ERP activity, you're automatically added as a watcher — so you'll also get pinged for subsequent comments and file uploads on that activity. You can unwatch via the bell icon in the activity drawer at any time. Both behaviors are toggleable in alert preferences.

Configuring alerts

Open Settings → Alerts (the gear icon in the menu). Per-user preferences include:

  • Lead time before events (5–120 minutes)
  • Per-source on/off (ERP, Outlook, Google, iOS)
  • Per-channel on/off (push, in-app log)
  • Quiet hours window (e.g. 22:00 – 07:00) — with an option to still notify for imminent events
  • Whether watched-event notifications override quiet hours
  • Auto-watch on assignment / on person-add

Tapping a notification

Each push deep-links to the relevant context — a reminder opens the day view at the event's date, a comment notification opens the Kanban board with the activity drawer already open and the watch state loaded, a booking notification opens the day view at the booking date. The title from the notification shows in the drawer immediately while details load.

Gestures & native UX

  • Swipe left / right — navigate by the current view's range (1 day in Day view, 7 days in Week view, 1 month in Month view).
  • Pull down — refresh; works in Calendar, Tasks, and Kanban. A “Pull to refresh / Refreshing…” pill appears at the top.
  • Haptic feedback — subtle vibration on key actions (drag handoff, swipe-navigate, button taps).
  • Home-screen Quick Actions — long-press the app icon to jump straight to Today, Month, Tasks, or Kanban without opening the app first.
  • Deep links — taps on push notifications open the right view + drawer.

Troubleshooting

Notifications aren't arriving

  1. Settings → Notifications → Herbe Calendar — confirm “Allow Notifications” is on and a banner style is selected.
  2. Check Settings → Focus — if a Focus mode is active, informational pushes are suppressed. Lifecycle pushes (assignment / edit / cancel / reminder) should still come through.
  3. In the herbe app, open Settings → Alerts and verify the push channel + the relevant source are on, and that quiet hours aren't blocking the current time.
  4. Force-quit the app and reopen — this re-registers the push token if anything was stale.

iOS calendar events don't appear

  1. Settings → Privacy & Security → Calendars → Herbe Calendar — must be set to Full Access (not Add Only).
  2. Open the herbe app and let it foreground — this triggers a fresh EventKit read + sync.
  3. Check the Calendars sheet (hamburger → Calendars) — your iOS calendars should appear under the iOS group. If they're there but toggled off, turn them on.

Widget shows nothing or “Not paired”

  • Open the app once — widgets read the same credentials store the app does, and a foregrounding refreshes the widget timeline.
  • Re-add the widget if it's stuck — long-press → Remove → re-add.

Pair code says “invalid or expired”

Codes are single-use and expire after 10 minutes. Tap Refresh in the iOS app to get a new one and try again.