Apphud SDK

The Apphud SDK (version 4.5.0) is built around a single SPM target (ApphudSDK) that uses several internal singletons to manage state and logic. While the public API is accessed via the Apphud class, the engine is driven by ApphudInternal.shared.

Core Components:

• Apphud (Public Entry Point): A final class containing static methods. It holds no state and forwards all calls to the internal engine.
• ApphudInternal.shared (The Engine): Manages the current user, paywalls, placements, permission groups, and delegates.
• ApphudAsyncStoreKit.shared (StoreKit 2 Engine): The primary purchase engine. It handles product caching, product.purchase(options:), and listens to Transaction.updates and PurchaseIntent.intents.
• ApphudStoreKitWrapper.shared (StoreKit 1 Compatibility): Used for observer-mode tracking of transactions not started by the SDK, receipt refreshing, and providing a feeder for the deprecated SKProduct surface.
• ApphudHttpClient.shared: Handles request building, retries, and host fallback.
• ApphudDataActor.shared: A global actor managing file-based caches and the pending user-property queue.
• ApphudLoggerService.shared: Manages paywall analytics and load-time metrics.

Apphud uses a single upload mechanism via submitReceipt to synchronize purchase data with the backend. This process handles both StoreKit 1 and StoreKit 2 transactions.

Key Submission Details

• Endpoint: POST /v1/subscriptions
• Data Sent: Includes device_id, user_id, environment, bundle_id, receipt_data (base64), transaction_id, and jws (for StoreKit 2).
• Product Info: For real purchases, the payload includes product_bundle_id, paywall_id, placement_id, variation_identifier, experiment_id, screen_id, and rule_id.
• Concurrency: The SDK uses a single-flight slot submittingTransaction to prevent redundant uploads. Non-owning callers (like restoration or eligibility checks) join the in-flight request. Owning callers (ownsTransaction: true) that differ from the in-flight transaction will receive an immediate error to prevent finishing a transaction on a foreign result.
• Retry Logic: If an upload fails, the SDK uses scheduleSubmitReceiptRetry with an increasing delay. It also sets a requiresReceiptSubmissionKey in UserDefaults to ensure the receipt is re-submitted during the next registration attempt.

// Note: This is an internal method used by the SDK to sync transactions
submitReceipt(productInfo:apphudProduct:transactionIdentifier:transactionProductIdentifier:transactionState:receipt_string:transactionJws:notifyDelegate:eligibilityCheck:ownsTransaction:fromScreen:callback:) async

To maintain consistency, follow these naming rules:

• Prefixes: Every type must be prefixed with Apphud. Internal free functions use the lowercase apphud prefix (e.g., apphudLog, apphudIsSandbox).
• File Naming:
  • ApphudInternal+<Concern>.swift for engine extensions.
  • +I.swift, +Extensions.swift, or +Macros.swift for ApphudUI controller extensions.
  • *Wrapper for SK1 compatibility.
  • *AsyncStoreKit for the SK2 engine.
  • *Observer for for await listeners.
  • *Actor or *Storage for actors.
  • *Manager for screen coordination.
  • *Controller for view controllers.
  • *Service for the logger.
  • *Tests for XCTest cases.
• Constants:
  • Public constants use APPHUD_UPPER_SNAKE_CASE.
  • Specific exceptions: _ApphudCamelCase is used for _ApphudUserPropertyKey* strings and _Apphud*FinishTransactionNotification names.
  • UserDefaults keys are stored in *Key properties or string literals colocated with their accessor.
• JSON Mapping:
  • Wire format is snake_case; Swift uses camelCase.
  • Exceptions (Public snake_case properties):
    • ApphudRule: rule_name, screen_name (both @objc), screen_id, paywall_id, paywall_identifier.
    • ApphudRuleScreen: status_bar_color (not @objc).

The ApphudStoreKitWrapper provides compatibility for StoreKit 1. It acts as an SKPaymentTransactionObserver but does not initiate payments itself.

Key Behaviors

• Transaction Observation: It processes .purchased transactions on the main actor. It also handles transaction removal by posting _ApphudDidFinishTransactionNotification and _ApphudWillFinishTransactionNotification.
• Swizzling: The SDK performs SKPaymentQueue.doSwizzle() to exchange add(_:) with apphudAdd(_:). This allows the SDK to automatically set the applicationUsername (or appAccountToken for SK2) to ensure transactions are correctly associated with the Apphud user.
• Swizzling Activation: Swizzling is enabled after the first user load (via preparePaywalls), unless the server explicitly sends swizzle_disabled: true or the SDK is running in Flutter observer mode.
• Receipt Refreshing: The SDK manages SKReceiptRefreshRequest and uses a 15-second watchdog timer to ensure that receipt refresh attempts do not hang indefinitely.

Apphud follows a specific lifecycle to ensure UI components have the necessary data:

1. User Registration: The process begins when a user is identified/registered.
2. Server Fetch: The SDK calls POST /v1/customers to retrieve configured paywalls and placements.
3. StoreKit Synchronization: Once paywalls/placements are received, the SDK identifies all required product IDs and fetches the corresponding SKProducts (StoreKit 2) from the App Store.
4. Readiness: The delegate.paywallsDidFullyLoad or delegate.placementsDidFullyLoad methods are called once the products are fetched and mapped to the paywalls/placements.

Key Models:

• ApphudPaywall: Represents a configured paywall UI configuration.
• ApphudPlacement: A logical grouping used to decide which paywall to show.
• ApphudProduct: The primary product model used for purchases and eligibility checks. It wraps the underlying SKProduct.

Understanding the threading model is critical for avoiding race conditions and ensuring UI responsiveness when using the SDK.

• Main Actor: The SDK's core state (current user, paywalls, placements, etc.) and all public APIs (start, purchase, placements) are @MainActor.
• Callbacks: All delegate methods and public callbacks are guaranteed to be delivered on the main thread.
• HTTP Requests: Network requests are initiated on a background task (.userInitiated) but their results are dispatched back to the @MainActor.
• StoreKit: StoreKit callbacks (like SKPaymentTransactionObserver) arrive on StoreKit's own threads and are immediately hopped to the @MainActor by the SDK.
• Background Processing: Heavy lifting, such as walking Transaction.all or managing the ApphudDataActor (caches, pending properties), happens on background threads or dedicated actors to keep the main thread free.