@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/app-clips/references/size-capabilities-and-promotion.md

@@ -1,113 +1,171 @@
-# App Clip Size, Capabilities, and Promotion
-
-Use this before App Clip feasibility reviews or capability audits, and when checking size budgets, measurement, Background Assets, SKOverlay, Live Activities App Clip extension constraints, CloudKit limits, or unsupported capabilities.
-
-## Contents
-
-- [Feasibility Review Template](#feasibility-review-template)
-- [Size Limits](#size-limits)
-- [Background Assets](#background-assets)
-- [SKOverlay for Full App Promotion](#skoverlay-for-full-app-promotion)
-- [Capabilities and Limitations](#capabilities-and-limitations)
-- [Additional Restrictions](#additional-restrictions)
-
-## Feasibility Review Template
-
-For capability reviews, explicitly cover:
-
-- Size basis: deployment target, physical versus digital invocation, reliable-internet expectation, App Thinning Size Report, and demo-link/App Clip Code constraints.
-- Download fit: large bundled media, ML models, catalogs, or required pre-task downloads should move to streaming/server-backed content, post-task assets, or the full app.
-- UX fit: reject marketing-only, ad-heavy, web-view-heavy, install-gated, or launch-blocking App Clip designs.
-- CloudKit boundary: App Clips can read the public database on iOS 16+ with `CloudKit-Anonymous`; do not plan public writes, iCloud Documents, key-value storage, private/shared containers, full CloudKit sync, or durable offline state in the App Clip.
-- Live Activities boundary: App Clip-only widget extension, Live Activities only, App Clip Extension capability, and exact raw entitlement key `com.apple.developer.on-demand-install-capable`; hand implementation details to ActivityKit/WidgetKit.
-- Unsupported runtime features: name App Intents, Background Tasks, background URL sessions, custom URL schemes, in-app purchases, durable persistent local state, SKAdNetwork, and App Tracking Transparency when relevant.
-- Sibling handoff: keep this skill at feasibility and App Clip boundary level; route StoreKit purchases, BackgroundTasks, CloudKit schema/sync, detailed ActivityKit/WidgetKit work, durable credentials, and long-term state to sibling or full-app domains.
-- Depth control: for product/PM feasibility reviews, stop at capability fit, size basis, invocation constraints, and handoff destinations. Describe location confirmation, install promotion, App Group/keychain handoff, and Live Activities conceptually. Do not add Swift package decomposition, API symbols such as `APActivationPayload`, `CLCircularRegion`, or `SKOverlay.AppClipConfiguration`, App Group/keychain implementation recipes, or other API-level implementation guidance unless the user asks for implementation.
+# Size, capabilities and promotion
+
+What fits in an App Clip, what the platform withholds, and how to offer the
+full app without getting in the way. Summary in `../SKILL.md`.
+
+## Feasibility review outline
+
+For a product or PM question ("can our clip do X?"), answer at boundary level
+under these headings and skip API detail unless implementation is requested.
+
+1. **Size basis.** Oldest supported iOS version, physical versus digital
+   invocations, whether a reliable connection can be expected, the App
+   Thinning Size Report figure, and any demo-link or App Clip Code constraint.
+2. **Download fit.** Large media, ML models, catalogs and anything that must
+   download before the task starts belong in streaming or server responses,
+   in assets fetched after the task, or in the full app.
+3. **Experience fit.** Turn down designs built around marketing, ads, web
+   views, an install requirement, or a launch that waits on something.
+4. **CloudKit boundary.** Public database reads only, from iOS 16, through
+   `CloudKit-Anonymous`. Nothing beyond that: no writing, no document or
+   key-value iCloud storage, no private or shared containers, no full sync, no
+   offline store that must last.
+5. **Live Activities boundary.** Only via a clip-owned widget extension, contains nothing but Live Activities, and has the App
+   Clip Extension capability (which puts the install-capable entitlement on
+   that extension). The
+   implementation itself is ActivityKit and WidgetKit work.
+6. **Runtime exclusions.** Name each one: custom URL schemes, App Intents,
+   `SKAdNetwork`, in-app purchases, Background Tasks, `App Tracking
+   Transparency`, background URL sessions, and local state that must last.
+7. **Handoffs and depth.** Name where each excluded piece goes (ActivityKit,
+   WidgetKit, StoreKit, BackgroundTasks, CloudKit, the full app) without
+   recipes, symbols or package layouts.
+
+## Size limits
+
+Limits apply to the uncompressed clip as measured by the App Thinning Size
+Report.
+
+| Oldest iOS the clip supports | Maximum uncompressed size |
+|---|---|
+| iOS 15 or earlier | 10 MB |
+| iOS 16 | 15 MB |
+| iOS 17 or later, digital invocations only | 100 MB |
 
-## Size Limits
+The 100 MB tier needs all of these:
 
-App Clip binaries must stay within strict uncompressed size limits, measured with the App Thinning Size Report:
+- only digital invocations (website, Spotlight, links), no App Clip Codes, QR
+  codes or NFC tags;
+- a setting where a good internet connection is likely;
+- no support for iOS 16 or earlier.
 
-| Deployment / Invocation Support | Maximum Uncompressed Size |
-|---|---|
-| iOS 15 and earlier | 10 MB |
-| iOS 16 and earlier | 15 MB |
-| iOS 17 and later | 100 MB |
+The demo link that App Store Connect generates is an exception: it may use the
+100 MB limit while still accepting App Clip Code, NFC and QR test
+invocations. Demo App Clip Codes must use the short demo link.
 
-The larger iOS 17+ limit is for digital invocations where a reliable internet connection is likely, when the App Clip does not support physical invocations and does not support iOS 16 or earlier. Physical invocation or iOS 16 support uses a smaller budget. App Store Connect demo links can use the larger limit while supporting NFC tags and QR codes for testing; demo App Clip Codes require the short demo link. Apple has changed App Clip size policy over time, so re-check the current App Store Connect and App Clip documentation before making release-blocking decisions.
+Measuring:
 
-**Measure size:** Archive the app → Distribute → Export as Ad Hoc/Development with App Thinning → check `App Thinning Size Report.txt`.
+1. Archive the app (Product > Archive).
+2. In the Organizer choose Distribute App and export for Ad Hoc or
+   Development with App Thinning set to all compatible device variants.
+3. Open `App Thinning Size Report.txt` in the export folder and read the
+   clip's uncompressed size for each variant.
 
-For feasibility reviews, name the size basis explicitly: deployment target, physical versus digital invocation, reliable-internet expectation, and whether demo links or App Clip Codes are in scope.
+Apple has revised these limits before; check the current App Clip
+documentation before a size question blocks a release.
 
 ## Background Assets
 
-Use Background Assets only for content that can arrive after launch without blocking the in-the-moment task. App Clips cannot set a background asset download's priority to essential with `isEssential`. They are a poor fit for large bundled media, ML models, catalogs, or downloads that must finish before useful work. Move those flows to streaming/server-backed content, post-task assets, or the full app.
+- A clip can download extra content with Background Assets, but it cannot mark
+  a download essential (`isEssential`).
+- That makes Background Assets right only for content that may arrive after
+  launch without holding up the task. It is a poor fit for large media, ML
+  models, catalogs or anything that must finish downloading first.
 
-## SKOverlay for Full App Promotion
+## Promoting the full app with SKOverlay
 
-Display an overlay recommending the full app from within the App Clip.
+Offer the full app once the person has what they came for.
 
-### SwiftUI
+SwiftUI:
 
 ```swift
-struct OrderCompleteView: View {
-    @State private var showOverlay = false
+import StoreKit
+import SwiftUI
+
+struct TicketIssuedView: View {
+    @State private var offerApp = false
 
     var body: some View {
         VStack {
-            Text("Order placed!")
-            Button("Get the full app") { showOverlay = true }
+            Label("Ticket saved", systemImage: "checkmark.seal")
+            Button("Keep all your tickets in the app") { offerApp = true }
         }
-        .appStoreOverlay(isPresented: $showOverlay) {
-            SKOverlay.AppClipConfiguration(position: .bottom)
+        .appStoreOverlay(isPresented: $offerApp) {
+            SKOverlay.AppClipConfiguration(position: .bottomRaised)
         }
     }
 }
 ```
 
-### UIKit
+UIKit:
 
 ```swift
-func displayOverlay() {
-    guard let scene = view.window?.windowScene else { return }
-
-    let config = SKOverlay.AppClipConfiguration(position: .bottom)
-    let overlay = SKOverlay(configuration: config)
-    overlay.delegate = self
-    overlay.present(in: scene)
+import StoreKit
+import UIKit
+
+final class TicketIssuedController: UIViewController, SKOverlayDelegate {
+    func offerFullApp() {
+        let settings = SKOverlay.AppClipConfiguration(position: .bottom)
+        let banner = SKOverlay(configuration: settings)
+        banner.delegate = self
+        if let windowScene = view.window?.windowScene {
+            banner.present(in: windowScene)
+        }
+    }
 }
 ```
 
-`SKOverlay.AppClipConfiguration` resolves to the App Clip's corresponding full app. Available iOS 14.0+.
-
-**Never** block the user's task to force installation  -  show the overlay after task completion.
-
-## Capabilities and Limitations
-
-### Available to App Clips
-
-SwiftUI, UIKit, Core Location (when-in-use), Sign in with Apple, Apple Pay, CloudKit public database reads only with `CloudKit-Anonymous` (iOS 16+), Background Assets, StoreKit `SKOverlay`, Keychain, App Groups, ephemeral notifications, and Live Activities through an App Clip-only widget extension.
-
-### Live Activities
-
-Starting in iOS 16, an App Clip can offer a Live Activity through a widget extension that belongs only to the App Clip. That extension can include only Live Activities, not ordinary widgets, and it needs the App Clip Extension capability. When reviewing this boundary, always name the exact raw entitlement key: `com.apple.developer.on-demand-install-capable`. Keep detailed ActivityKit and WidgetKit implementation guidance in those sibling skills.
-
-### Not available / no runtime functionality
-
-In feasibility reviews, explicitly name restricted or unsupported App Clip runtime features instead of summarizing them generically: App Intents, Background Tasks, background URL sessions, custom URL schemes, in-app purchases, durable persistent local state, SKAdNetwork, App Tracking Transparency, CallKit, Contacts, CoreMotion, EventKit, HealthKit, HomeKit, MediaPlayer, Messages, NearbyInteraction, PhotoKit, SensorKit, and Speech.
-
-## Additional Restrictions
-
-- No background URL sessions.
-- No background Bluetooth.
-- No multiple scenes on iPad.
-- No on-demand resources.
-- No custom URL schemes.
-- No in-app purchases; reserve purchase flows for the full app and StoreKit sibling guidance.
-- No durable local-state guarantee; migrate important non-secret state to a server or full-app handoff.
-- No CloudKit public writes, iCloud Documents, iCloud key-value storage, private containers, or shared containers.
-- No App Clip design that requires install, marketing exposure, web-view navigation, or blocking downloads before the user gets value.
-- Hand off detailed ActivityKit/WidgetKit Live Activity implementation, StoreKit purchase/full-app monetization, BackgroundTasks processing, CloudKit schema or sync beyond public reads, durable credentials, and long-term state to sibling or full-app domains without adding implementation detail here.
-- In feasibility answers, avoid implementation-level Swift package routing, App Group/keychain recipes, location-confirmation API symbols, `SKOverlay` API calls, or framework snippets unless the user explicitly asks for implementation.
-- `UIDevice.name` and `identifierForVendor` return empty strings.
+- `SKOverlay.AppClipConfiguration` (iOS 14+) automatically points at the
+  clip's parent app; no App Store ID is needed.
+- Present it after the task is complete. Never block the task to push an
+  install.
+
+## What the clip can use
+
+- SwiftUI and UIKit
+- Location through Core Location, limited to When In Use
+- Sign in with Apple and Apple Pay
+- Touch ID through LocalAuthentication (Face ID is unavailable because the
+  `NSFaceIDUsageDescription` key cannot be used)
+- Reading the public CloudKit database (iOS 16+, `CloudKit-Anonymous`)
+- Background Assets for downloads that are not essential
+- StoreKit `SKOverlay` for full-app promotion
+- Keychain and App Groups
+- Ephemeral notifications
+- Live Activities through a clip-only widget extension: supported from iOS 16
+  (the ActivityKit APIs themselves need iOS 16.1); the extension belongs only
+  to the clip, holds only Live Activities (no Home Screen, Lock Screen or Today
+  widgets), has the App Clip Extension capability, which gives it the
+  install-capable entitlement (`com.apple.developer.on-demand-install-capable`),
+  and uses the clip's bundle ID as its prefix
+
+## What provides no functionality
+
+These compile, but at run time they report unavailability, return empty data
+or fail:
+
+- Tracking and attribution: `SKAdNetwork`, App Tracking Transparency
+- System integration: App Intents, Background Tasks, background URL
+  sessions, custom URL schemes
+- Commerce and storage: in-app purchases, persistent local state
+- AssetsLibrary, CallKit, Contacts and ContactsUI, CoreMotion, EventKit and
+  EventKitUI, FileProvider and FileProviderUI, HealthKit, HomeKit,
+  MediaPlayer, Messages and MessageUI, NearbyInteraction, PhotoKit,
+  ResearchKit, SensorKit, Speech
+
+## Further restrictions
+
+- No background networking with `URLSession` background sessions.
+- No Bluetooth connections kept alive while the clip is not in use.
+- iPad: a single scene only.
+- On-demand resources are unavailable.
+- Custom URL schemes cannot be registered.
+- Purchases and monetization belong to the full app and StoreKit; the clip
+  sells nothing in-app.
+- No guarantee that local state survives.
+- CloudKit stays read-only and public: no document storage, key-value store,
+  or private or shared containers.
+- No design that requires installing the app, sitting through marketing,
+  browsing web views or waiting on a download before the person gets value.
+- `UIDevice.current.name` and `identifierForVendor` return an empty value
+  rather than anything that identifies the device.