SPB Git

Repository Public

SYSTEM-INTEGRATION.md 6.6 KB

# SP Mail Next — system integration

Server contract: sp-mail/docs/next/ARCHITECTURE-NEXT.md §3 D-N4, D-N10, §4.2 and docs/next/PUSH.md. Code: Sources/Shared/System/ (app side), Packages/SPMailSystem (logic shared with the extensions, unit-tested), Sources/Widgets, Sources/ShareExtension, Sources/NotificationService, Sources/Intents.

# Targets and identifiers

Target macOS (Developer ID) iOS / iPadOS (App Store Connect)
App ai.spboucher.spmail ai.spboucher.spmail.ios
Widgets ai.spboucher.spmail.widgets ai.spboucher.spmail.ios.widgets
Share extension ai.spboucher.spmail.share ai.spboucher.spmail.ios.share
Notification service ai.spboucher.spmail.notifications ai.spboucher.spmail.ios.notifications

Debug builds insert .dev after the app identifier (ai.spboucher.spmail.dev.widgets, …), use their own shared group and the URL scheme spmail-dev.

# Shared state (decision D-N10)

Two channels, both written by the app only (SharedStateWriter), read by the extensions through SharedStore:

  1. Shared keychain access group 3YM54G49SN.group.ai.spboucher.spmail — the session token (copied with SharedContainer.migrateToken, the app's own entry is kept), the extension state (signed in, preview level, app lock, mailboxes) and the key of the sealed snapshot. Any build signed by the team can declare this group: nothing to register at Apple.
  2. App Group container — the sealed widget snapshot and the share queue (sealed files, 1 MiB chunks). macOS uses the Team-ID-prefixed group 3YM54G49SN.group.ai.spboucher.spmail (no registration under Developer ID). iOS needs group.ai.spboucher.spmail registered and attached to the four App IDs.

The mail database stays in the app container; no extension opens it. Sign-out and a revoked session clear both channels.

# App Group on iOS — the one manual step

The App Store Connect API key used by Scripts/provision.py and by automatic signing can turn the App Groups capability on (done for the four iOS App IDs), but it cannot create a group identifier nor attach it to an App ID: an archive signed with the group entitlement fails with « Provisioning profile … doesn't support the group.ai.spboucher.spmail App Group ».

Until that step is done, the iOS Release build is signed without the container entitlement and degrades cleanly: token, state and widget snapshot go through the shared keychain group (widgets, the notification service and the share extension all work); the only loss is that a share with files cannot be queued for the app — the share extension sends it directly through the API instead (text-only drafts can still be queued).

To enable the container, once, in the Apple Developer account (Certificates, Identifiers & Profiles):

  1. Identifiers → App Groups → + → identifier group.ai.spboucher.spmail.
  2. On each of ai.spboucher.spmail.ios, .ios.widgets, .ios.share, .ios.notifications: App Groups → Configure → select that group → Save.
  3. Archive with SPMAIL_IOS_APP_GROUP=1 Scripts/ios-archive.sh archive (selects Config/*-iOS-AppGroup.entitlements).

Optional, same place: enabling « Communication Notifications » on ai.spboucher.spmail.ios (not a capability type of the API either) and adding com.apple.developer.usernotifications.communication to the app entitlements lets the notification service show the sender monogram as an avatar. Without it the notification is delivered as a normal one.

# Push and notifications

  • Registration: asked once a session exists (never before sign-in); the APNs environment is read from the signature (PushEnvironmentDetector), not from the build configuration; re-registration on token, session, app version or locale change; the device is deleted on sign-out. A server without APNs credentials is shown as « Non configuré sur le serveur » and the app announces new mail by itself.
  • One notification per message: when the server's push pipeline is active for this device the app posts no local notification; otherwise it posts one, never for a message already announced (ledger + what is in Notification Centre), under the same request identifier as the server's apns-collapse-id.
  • Categories MAIL_NEW (reply with text, mark as read, archive, delete on iOS), MAIL_REMINDER (open, remind in one hour, done), MAIL_ALERT. Actions run through the sync engine / the normal send path. Reply and delete always require the device to be unlocked; with the app lock on, every mail action does.
  • Privacy: the server applies the account's preview level; the notification service extension lowers it further when SP Mail is locked or the device hides senders and subjects. Widgets and Spotlight follow the same level.
  • Background work: iOS decides if and when BGAppRefreshTask / BGProcessingTask run; nothing stays connected while the app is suspended. With an active push pipeline the app asks for a sparse refresh only (cache and widgets), none in Low Power Mode or Low Data Mode.

spmail://conversation?mb=<mailbox>&email=<id>[&thread=<id>], spmail://inbox[?mb=], spmail://compose, spmail://search?q=, spmail://reminders, spmail://share; mailto: on both platforms. Identifiers are opaque; a link never carries content. Universal links (applinks:) are not used: the server's apple-app-site-association lists webcredentials only.

# Signing and release

text
Scripts/provision.py --check     # dry run
Scripts/provision.py             # bundle ids, capabilities, one Developer ID profile per macOS bundle → Build/profiles/
Scripts/release.sh && Scripts/verify-release.sh     # macOS: app + three extensions, each with its own profile
Scripts/ios-archive.sh archive && Scripts/ios-archive.sh export

# Development stack with push

Scripts/dev-backend.sh start runs a private backend whose APNs host is the local fake (Scripts/dev-fake-apns.mjs, requests logged in Build/fake-apns.jsonl). A simulator cannot receive those pushes: Scripts/system-shots.sh delivers the same payloads with xcrun simctl push and drives the UI (Tests/SystemUITests).

# What only a physical device can verify

Real APNs delivery (token, environment, topic), the notification service extension (not launched for simctl push), widgets on a real Lock Screen, Handoff between devices, background refresh timing, Siri phrases, the macOS Release build launched from a notarised copy.

Files main
Menu

Theme