BusinessCard/CODEX-Plan-AppClip.md

CODEX Plan - App Clip

Goal

Implement App Clip-based sharing so recipients can scan a QR code, open an App Clip, preview a card (including photo), and add it to Contacts without installing the full app.

Key Requirement (Photo Preservation)

• Use vCard 3.0 with embedded photo data for contact creation.
• Current model already supports this via BusinessCard.vCardFilePayload:
  • Includes VERSION:3.0.
  • Embeds PHOTO;ENCODING=b;TYPE=JPEG:<base64>.
• App Clip should fetch the record, build a contact with photo data attached, and then save to Contacts.

Data Flow (End-to-End)

1. User taps Share via App Clip in iOS app.
2. iOS app creates a SharedCard CloudKit record:
   • Stores vCard data (including PHOTO base64) + optional photo asset.
   • Sets expiresAt.
3. iOS app generates an App Clip URL and a QR code from that URL.
4. Recipient scans QR code → App Clip opens with recordID in URL.
5. App Clip fetches SharedCard record from CloudKit.
6. App Clip builds a contact from the vCard + photo, shows preview.
7. User taps Add to Contacts → contact saved with photo.
8. App Clip marks record as consumed or deletes it (optional).

UX Expectations

• App Clip must load quickly and feel instant.
• Preview shows name, role, company, and profile photo.
• Primary action is always Add to Contacts.
• Success state shows confirmation and optionally offers “Open full app”.
• Errors show a brief, user-friendly message with retry.

CloudKit Record Design

Record type: SharedCard

• recordID (system)
• fullName (String)
• role (String)
• company (String)
• vCardData (String) // vCard 3.0 with PHOTO base64
• photoData (CKAsset, optional) // optional raw photo file for preview
• createdAt (Date)
• expiresAt (Date)
• consumedAt (Date, optional) // set after App Clip saves contact

Notes:

• Keep TTL short (e.g., 7 days) for privacy.
• Use CKAsset only for preview, vCard remains primary source of truth.

URL Format

• https://yourapp.com/appclip?card=<recordID>
• Record ID must be safe for URL; use CKRecord.ID recordName.
• QR code payload should be only the URL (no vCard data).

Security / Privacy

• Short-lived records; delete expired on app launch and optionally after consumption.
• Keep payload minimal: avoid storing unnecessary data.
• Consider hashing record IDs in public URLs if desired (optional).
• No analytics or tracking unless explicitly approved.

Constraints

• iOS 26+, Swift 6.2, SwiftUI + @Observable.
• Protocol-first, Clean Architecture, one public type per file.
• String Catalogs only; no inline literals in views; use Design constants.
• No UIKit unless required (App Clip will need CNContactStore).
• WatchConnectivity remains unchanged.

Milestone 1: CloudKit Schema + Core Services (Main App)

• Add SharedCard CloudKit record design:
  • Fields: fullName, role, company, vCardData, photoData, expiresAt, createdAt.
  • Store photoData as CKAsset for size efficiency.
• Create protocols:
  • SharedCardUploading (upload + return URL/record ID).
  • SharedCardFetching (fetch by record ID).
  • SharedCardCleaning (delete expired records).
• Implement a CloudKit service:
  • SharedCardCloudKitService conforming to the protocols.
  • Use async/await; no force-try.
• Add state integration:
  • ShareCardState (or extend existing share state) to call upload and expose App Clip URL.
  • Persist a short-lived “last shared” URL for display.
• Add cleanup hook on app launch:
  • Trigger cleanupExpiredSharedCards() in AppState init or a dedicated startup service.
  • Cleanup should be safe when offline (no crash, no force-try).

CloudKit Behavior Details

• Use the private database (not public) unless sharing requires public discovery.
• Upload is write-once for a given share, no edits required.
• expiresAt should be server-trusted if possible; otherwise use client time.
• Cleanup query: expiresAt < now and optionally consumedAt != nil.
• Prefer batching deletes to avoid rate limits.

Code Skeletons (Milestone 1)

// BusinessCard/Protocols/SharedCardUploading.swift
protocol SharedCardUploading {
    func uploadSharedCard(_ card: BusinessCard) async throws -> SharedCardUploadResult
}

// BusinessCard/Protocols/SharedCardFetching.swift
protocol SharedCardFetching {
    func fetchSharedCard(recordID: String) async throws -> SharedCardPayload
}

// BusinessCard/Protocols/SharedCardCleaning.swift
protocol SharedCardCleaning {
    func cleanupExpiredSharedCards() async throws
}

// BusinessCard/Models/SharedCardPayload.swift
struct SharedCardPayload: Sendable {
    let recordID: String
    let vCardData: String
    let photoData: Data?
    let expiresAt: Date
}

// BusinessCard/Models/SharedCardUploadResult.swift
struct SharedCardUploadResult: Sendable {
    let recordID: String
    let appClipURL: URL
    let expiresAt: Date
}

// BusinessCard/Services/SharedCardCloudKitService.swift
struct SharedCardCloudKitService: SharedCardUploading, SharedCardFetching, SharedCardCleaning {
    func uploadSharedCard(_ card: BusinessCard) async throws -> SharedCardUploadResult {
        // Build vCard data using card.vCardFilePayload (includes photo base64).
        // Upload record + asset, return App Clip URL.
    }

    func fetchSharedCard(recordID: String) async throws -> SharedCardPayload {
        // Fetch vCard string + photo asset for App Clip.
    }

    func cleanupExpiredSharedCards() async throws {
        // Query by expiresAt < now, delete records.
    }
}

App Clip Entitlements and Capabilities

• App Clip target must include:
  • CloudKit capability
  • Contacts access usage description
  • Associated Domains

Milestone 2: Main App UI Integration

• Add “Share via App Clip” action in ShareCardView.
• Show a new QR code using App Clip URL (not the vCard URL).
• Add status UI for upload progress and errors.
• Ensure new strings are in .xcstrings.
• Add user-facing helper copy:
  • “This QR code opens an App Clip with your full card and photo.”
  • “Recipient can save the full contact without installing the app.”

Milestone 2.1: App Clip QR UI Details

• Use a dedicated QR view when App Clip URL is available.
• Provide a fallback state if upload fails (hide QR + show error).
• Show a lightweight loading state while upload is running.

Code Skeletons (Milestone 2)

// BusinessCard/State/ShareCardState.swift
@MainActor
@Observable
final class ShareCardState {
    private let uploader: SharedCardUploading

    var isUploading = false
    var appClipURL: URL?
    var lastUploadError: String?

    init(uploader: SharedCardUploading) {
        self.uploader = uploader
    }

    func shareViaAppClip(card: BusinessCard) async {
        // Call uploader.uploadSharedCard(card) and set appClipURL.
    }
}

Suggested ShareCardState Flow

• Guard that a card exists before upload.
• Set isUploading = true before calling CloudKit.
• On success: set appClipURL, clear lastUploadError.
• On failure: set lastUploadError, keep appClipURL nil.
• Always reset isUploading in defer.

Milestone 3: App Clip Target

• Create App Clip target (<15 MB).
• Add minimal model type:
  • SharedCardSnapshot (name, role, company, photo, vCardData).
• Add state:
  • AppClipCardStore (@Observable, @MainActor).
• Add services:
  • AppClipCloudKitService (fetch by record ID).
• Build UI:
  • AppClipRootView with card preview.
  • “Add to Contacts” primary action.
• Implement CNContactStore save flow:
  • Map to CNMutableContact.
  • Respect photo data and vCard fields.

Code Skeletons (Milestone 3)

// BusinessCardAppClip/Models/SharedCardSnapshot.swift
struct SharedCardSnapshot: Sendable {
    let vCardData: String
    let photoData: Data?
}

// BusinessCardAppClip/Services/AppClipCloudKitService.swift
struct AppClipCloudKitService {
    func fetchSharedCard(recordID: String) async throws -> SharedCardSnapshot {
        // Fetch vCard + photo asset.
    }
}

// BusinessCardAppClip/State/AppClipCardStore.swift
@MainActor
@Observable
final class AppClipCardStore {
    private let service: AppClipCloudKitService
    var snapshot: SharedCardSnapshot?
    var isLoading = false
    var errorMessage: String?

    init(service: AppClipCloudKitService) {
        self.service = service
    }

    func load(recordID: String) async {
        // Fetch snapshot.
    }

    func saveToContacts() async throws {
        // Parse vCard data + photo and write with CNContactStore.
    }
}

// BusinessCardAppClip/Views/AppClipRootView.swift
struct AppClipRootView: View {
    @Bindable var store: AppClipCardStore

    var body: some View {
        // Minimal preview + "Add to Contacts" button.
    }
}

Contact Save Implementation Sketch

// BusinessCardAppClip/Services/ContactSaveService.swift
struct ContactSaveService {
    func save(vCardData: String, photoData: Data?) async throws {
        // 1. Convert vCard string to Data.
        // 2. Parse using CNContactVCardSerialization.
        // 3. Create CNMutableContact, attach imageData if needed.
        // 4. Save via CNContactStore.
    }
}

App Clip Contact Save Details

• Parse vCard data into CNContact using CNContactVCardSerialization.
• If vCard photo is missing or invalid, use photoData asset as fallback.
• Do not create duplicates if a similar contact already exists (optional, future).
• Provide success confirmation and a short success message.

App Clip Permissions

• Request Contacts access on first save attempt.
• If denied, show an explanatory message with Settings guidance.

Error States

• CloudKit fetch fails → show retry + short description.
• Record expired → show “This card has expired” and provide fallback.
• Contact save denied → show “Contacts access required” with instructions.
• Malformed vCard → show “This card data is invalid” (log details).

Milestone 4: App Clip Invocation + App Store Connect

• Configure Associated Domains: appclips:yourapp.com.
• Generate App Clip URL format: https://yourapp.com/appclip?card=<recordID>.
• Configure App Clip Experience in App Store Connect.
• Validate invocation with QR code scans.

App Clip Size and Performance Notes

• Keep App Clip under 15 MB.
• Avoid loading unused assets.
• Use lightweight preview UI; no heavy animations.

Implementation Notes

• Use String(localized:) for non-Text strings in App Clip.
• Keep all user-facing text in the App Clip string catalog.
• Use Bedrock Design constants for spacing, corner radius, opacity, and animation.
• Avoid GeometryReader; use containerRelativeFrame() when possible.
• Use .scrollIndicators(.hidden) if any ScrollView is used.
• Ensure all interactive elements have accessibility labels/hints.

vCard Handling Notes

• vCard payload should remain ASCII-safe; base64 PHOTO may be long.
• vCard should be stored exactly as generated by vCardFilePayload.
• If App Clip uses CNContactVCardSerialization, preserve any existing fields.
• The App Clip should not attempt to parse fields manually unless needed for preview.

CloudKit Limits and Resilience

• CKRecord size limits apply; keep vCard payload small where possible.
• Photo asset should be a compressed JPEG to reduce size.
• If upload fails, allow retry and show a clear error state.
• If fetch fails due to network, show offline messaging and retry.

Testing Strategy

• Unit tests for CloudKit upload URL creation and expiration logic.
• Unit test for App Clip contact mapping (vCard + photo).
• Manual tests on device for App Clip invocation and contact save.

Open Questions (Resolve Before Build)

• Final App Clip domain and URL path?
• TTL for shared cards (3 days vs 7 days)?
• Should consumed records be deleted immediately or retained until expiry?
• Should App Clip show a minimal card preview or a full card layout?
• Do we want a “Copy contact info” fallback if Contacts permission is denied?

App Clip UI Flow (Screen-by-Screen)

1. Loading
   • Title: “Loading card…”
   • Show spinner and a short message.
   • Retry button only if fetch fails.
2. Card Preview
   • Photo (if available), name, role, company.
   • Primary button: “Add to Contacts”.
   • Secondary action (optional): “Open Full App”.
3. Contacts Permission
   • If permission not granted, show prompt messaging.
   • Provide “Continue” → triggers permission request.
4. Saving
   • Progress indicator with short status text.
5. Success
   • Confirmation text: “Saved to Contacts”.
   • Optional button: “Open Full App”.
6. Failure
   • Short error summary + “Try Again”.
   • If expired, show “This card has expired”.

App Store Connect Checklist (App Clip)

• Register App Clip in App Store Connect.
• Add App Clip Experience:
  • Title, subtitle, and invocation URL.
  • Provide header image and action button text.
• Configure Advanced Experiences (optional).
• Associate App Clip to the main app version.
• Verify Associated Domains in the app target.
• Upload build with App Clip and validate with Apple.
• Test invocation on-device with QR and direct URL.

Edge Cases

• No photo data → vCard should still import.
• Large photo → ensure CloudKit asset and vCard remain within limits.
• Multiple scans of same QR → record should still fetch until expired.
• Offline scanning → show “Requires internet to load” message.

Files To Add (Expected)

• BusinessCard/Protocols/SharedCardUploading.swift
• BusinessCard/Protocols/SharedCardFetching.swift
• BusinessCard/Protocols/SharedCardCleaning.swift
• BusinessCard/Services/SharedCardCloudKitService.swift
• BusinessCard/State/ShareCardState.swift (or extend existing state file)
• BusinessCard/Views/ShareCardView.swift (update only)
• BusinessCardAppClip/Models/SharedCardSnapshot.swift
• BusinessCardAppClip/State/AppClipCardStore.swift
• BusinessCardAppClip/Services/AppClipCloudKitService.swift
• BusinessCardAppClip/Views/AppClipRootView.swift

Documentation Updates (When Implementation Starts)

• Update README.md, ai_implementation.md, Agents.md together.
• Update ROADMAP.md for App Clip progress.