Promoted Iap

Promoted In-App Purchases Generator

Set up promoted In-App Purchases so your premium offerings appear directly on your App Store product page, in search results, and in editorial features.

When This Skill Activates

Use this skill when the user:

• Asks to "promote IAP" or "show purchase on product page"
• Mentions "promoted in-app purchase" or "App Store product page IAP"
• Wants subscription/IAP visible in App Store search results
• Asks about paymentQueue(_:shouldAddStorePayment:for:)
• Wants to handle purchases initiated from the App Store

Pre-Generation Checks

1. Project Context Detection

• [ ] Check for existing StoreKit implementation
• [ ] Check deployment target (iOS 15+ for StoreKit 2)
• [ ] Look for existing IAP product definitions
• [ ] Check if paywall-generator was already used

2. Conflict Detection

Glob: **/*Promoted*.swift, **/*StorePayment*.swift
Grep: "shouldAddStorePayment" or "PurchaseIntent" or "promotedPurchase"

How Promoted IAP Works

1. App Store Connect: Mark IAP products as "Promoted" with promotional image 2. Product Page: Up to 20 promoted IAPs appear on your product page 3. Search Results: Promoted IAPs can appear in search 4. User Action: User taps "Buy" on App Store → your app opens to complete purchase 5. Your App: Must handle the incoming purchase intent

Promoted IAP Display Order

• You control the order in App Store Connect
• Choose your most compelling IAP as the first promoted product
• Apple may also feature your IAPs in editorial content

Configuration Questions

Ask user via AskUserQuestion:

1. What type of IAP to promote?

• Auto-renewable subscription
• Non-consumable (one-time unlock)
• Consumable (credits/tokens)

2. How to handle App Store-initiated purchases?

• Show immediately (direct purchase)
• Show paywall first (let user see options before buying)
• Show onboarding then purchase (new users from App Store)

3. Number of promoted products?

• Single product
• Multiple products (2-5)
• Full catalog (6+)

Generation Process

Step 1: Read Templates

Read templates.md for promoted IAP implementation code.

Step 2: Create Core Files

1. PromotedPurchaseHandler.swift — Handle purchases initiated from App Store 2. PromotedProductConfiguration.swift — Product definitions and promotional images specs 3. PromotedPurchaseFlowView.swift — UI for completing promoted purchases in-app

Step 3: Determine File Location

- If Sources/Store/ exists → Sources/Store/Promoted/
- If Store/ exists → Store/Promoted/
- Otherwise → Store/Promoted/

Output Format

Files Created

Store/Promoted/
├── PromotedPurchaseHandler.swift        # App Store purchase handling
├── PromotedProductConfiguration.swift   # Product setup & image specs
└── PromotedPurchaseFlowView.swift       # In-app purchase completion UI

Integration Steps

Handle App Store-Initiated Purchases (StoreKit 2):

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .task {
                    // Listen for purchases initiated from App Store
                    for await purchaseIntent in PurchaseIntent.intents {
                        await PromotedPurchaseHandler.shared.handle(purchaseIntent)
                    }
                }
        }
    }
}

Complete the Purchase:

// PromotedPurchaseHandler determines the right flow:
// 1. Direct purchase (existing user, known product)
// 2. Paywall (show options first)
// 3. Onboarding (new user from App Store)

App Store Connect Setup

1. Go to App Store Connect > Your App > In-App Purchases 2. Select the IAP product 3. Under "App Store Promotion":

• Upload promotional image (1024x1024, no alpha, no rounded corners)
• Set display order
• Enable promotion

4. Repeat for each product you want to promote

Promotional Image Requirements

• Size: 1024 x 1024 pixels
• Format: PNG or JPEG, no transparency
• Content: Feature the product value, not just the app icon
• Text: Minimal — the product name appears separately
• Style: Match your app's visual identity

Testing Instructions

1. StoreKit Configuration: Add promoted products to your .storekit file 2. Test purchase flow: Simulate App Store-initiated purchase 3. Test user states: New user, existing free user, existing subscriber 4. Verify UI: Purchase completion view looks correct for each product type

References

• templates.md — Production Swift templates
• Related: generators/paywall-generator — Full paywall for purchase completion
• Related: generators/subscription-offers — Offer types for promoted subscriptions
• Related: app-store/marketing-strategy — Strategic product promotion planning

Promoted IAP Templates

Production-ready Swift code for handling promoted In-App Purchases.

PromotedPurchaseHandler.swift

import StoreKit
import SwiftUI

/// Handles purchases initiated from the App Store product page
@Observable
@MainActor
final class PromotedPurchaseHandler {

    static let shared = PromotedPurchaseHandler()

    private(set) var pendingPurchaseIntent: PurchaseIntent?
    private(set) var isProcessing = false

    /// The flow to show when a promoted purchase arrives
    enum PurchaseFlow: Identifiable {
        case directPurchase(Product)
        case showPaywall(Product)
        case showOnboarding(Product)

        var id: String {
            switch self {
            case .directPurchase(let p): "direct-\(p.id)"
            case .showPaywall(let p): "paywall-\(p.id)"
            case .showOnboarding(let p): "onboarding-\(p.id)"
            }
        }
    }

    private(set) var activePurchaseFlow: PurchaseFlow?

    // MARK: - Handle Purchase Intent

    /// Call this from your app's root view task to handle App Store purchases
    func handle(_ intent: PurchaseIntent) async {
        pendingPurchaseIntent = intent
        isProcessing = true

        let product = intent.product

        // Determine the right flow based on user state
        let flow = await determinePurchaseFlow(for: product)
        activePurchaseFlow = flow

        isProcessing = false
    }

    /// Complete the pending promoted purchase
    func completePurchase() async throws -> Transaction? {
        guard let intent = pendingPurchaseIntent else { return nil }

        let result = try await intent.product.purchase()

        switch result {
        case .success(let verification):
            guard case .verified(let transaction) = verification else {
                throw PromotedPurchaseError.verificationFailed
            }
            await transaction.finish()
            cleanup()
            return transaction

        case .userCancelled:
            cleanup()
            return nil

        case .pending:
            cleanup()
            return nil

        @unknown default:
            cleanup()
            return nil
        }
    }

    /// Cancel the pending promoted purchase
    func cancelPurchase() {
        cleanup()
    }

    // MARK: - Private

    private func determinePurchaseFlow(for product: Product) async -> PurchaseFlow {
        // Check if user has completed onboarding
        let hasCompletedOnboarding = UserDefaults.standard.bool(
            forKey: "hasCompletedOnboarding"
        )

        if !hasCompletedOnboarding {
            // New user from App Store — show onboarding first
            return .showOnboarding(product)
        }

        // Existing user — check if they should see the paywall
        // (e.g., to show other subscription options)
        if product.type == .autoRenewable {
            return .showPaywall(product)
        }

        // Direct purchase for non-subscription IAPs
        return .directPurchase(product)
    }

    private func cleanup() {
        pendingPurchaseIntent = nil
        activePurchaseFlow = nil
        isProcessing = false
    }
}

enum PromotedPurchaseError: LocalizedError {
    case verificationFailed
    case noPendingPurchase

    var errorDescription: String? {
        switch self {
        case .verificationFailed: "Purchase verification failed"
        case .noPendingPurchase: "No pending purchase to complete"
        }
    }
}

PromotedProductConfiguration.swift

import StoreKit

/// Configuration for promoted In-App Purchases
struct PromotedProductConfiguration {

    /// Products to promote on the App Store product page
    /// Listed in display priority order (first = most prominent)
    static let promotedProducts: [PromotedProduct] = [
        PromotedProduct(
            id: "com.yourapp.pro",
            displayName: "Pro Upgrade",
            promotionalImageName: "promo_pro_upgrade",
            promotionPriority: .high
        ),
        // Add more promoted products as needed
    ]

    /// All promoted product IDs
    static var productIDs: Set<String> {
        Set(promotedProducts.map(\.id))
    }
}

struct PromotedProduct: Identifiable {
    let id: String
    let displayName: String
    let promotionalImageName: String
    let promotionPriority: PromotionPriority

    enum PromotionPriority {
        case high   // First in list, most visible
        case medium // Middle of list
        case low    // End of list
    }
}

// MARK: - Promotional Image Guidelines

/*
 App Store Connect Promotional Image Requirements:

 SIZE: 1024 x 1024 pixels
 FORMAT: PNG or JPEG
 TRANSPARENCY: Not allowed (no alpha channel)
 CORNERS: Square (App Store rounds them automatically)

 CONTENT BEST PRACTICES:
 - Show the key benefit or feature being purchased
 - Use your app's color scheme and visual identity
 - Keep text minimal (product name appears separately)
 - Make it visually distinct from your app icon
 - Test at small sizes (appears as thumbnail in search)

 EXAMPLES BY IAP TYPE:
 - Subscription: Show premium features collage
 - Feature Unlock: Show the specific feature in action
 - Content Pack: Show sample content thumbnails
 - Credits/Tokens: Show the currency with quantity
*/

PromotedPurchaseFlowView.swift

import SwiftUI
import StoreKit

/// Root view modifier that handles promoted purchase flows
struct PromotedPurchaseFlowModifier: ViewModifier {
    @State private var handler = PromotedPurchaseHandler.shared

    func body(content: Content) -> some View {
        content
            .task {
                for await intent in PurchaseIntent.intents {
                    await handler.handle(intent)
                }
            }
            .sheet(item: $handler.activePurchaseFlow) { flow in
                PromotedPurchaseFlowView(flow: flow, handler: handler)
            }
    }
}

extension View {
    /// Add promoted purchase handling to this view
    func handlePromotedPurchases() -> some View {
        modifier(PromotedPurchaseFlowModifier())
    }
}

/// View that presents the appropriate flow for a promoted purchase
struct PromotedPurchaseFlowView: View {
    let flow: PromotedPurchaseHandler.PurchaseFlow
    let handler: PromotedPurchaseHandler

    @Environment(\.dismiss) private var dismiss
    @State private var isPurchasing = false
    @State private var purchaseError: String?

    var body: some View {
        NavigationStack {
            Group {
                switch flow {
                case .directPurchase(let product):
                    directPurchaseView(product: product)
                case .showPaywall(let product):
                    paywallView(product: product)
                case .showOnboarding(let product):
                    onboardingView(product: product)
                }
            }
            .toolbar {
                ToolbarItem(placement: .cancellationAction) {
                    Button("Cancel") {
                        handler.cancelPurchase()
                        dismiss()
                    }
                }
            }
        }
    }

    // MARK: - Direct Purchase

    @ViewBuilder
    private func directPurchaseView(product: Product) -> some View {
        VStack(spacing: 24) {
            Image(systemName: "star.circle.fill")
                .font(.system(size: 64))
                .foregroundStyle(.accent)

            Text(product.displayName)
                .font(.title.weight(.bold))

            Text(product.description)
                .font(.body)
                .foregroundStyle(.secondary)
                .multilineTextAlignment(.center)

            Text(product.displayPrice)
                .font(.title2.weight(.semibold))

            purchaseButton(product: product)

            if let error = purchaseError {
                Text(error)
                    .font(.caption)
                    .foregroundStyle(.red)
            }
        }
        .padding(32)
    }

    // MARK: - Paywall

    @ViewBuilder
    private func paywallView(product: Product) -> some View {
        // Use SubscriptionStoreView for subscription products
        if product.type == .autoRenewable,
           let groupID = product.subscription?.subscriptionGroupID {
            SubscriptionStoreView(groupID: groupID)
        } else {
            directPurchaseView(product: product)
        }
    }

    // MARK: - Onboarding

    @ViewBuilder
    private func onboardingView(product: Product) -> some View {
        VStack(spacing: 24) {
            Text("Welcome!")
                .font(.largeTitle.weight(.bold))

            Text("Thanks for checking out \(product.displayName). Here's what you'll get:")
                .font(.body)
                .foregroundStyle(.secondary)
                .multilineTextAlignment(.center)

            // Feature list - customize for your app
            VStack(alignment: .leading, spacing: 16) {
                FeatureBullet(icon: "checkmark.circle.fill", text: "Feature 1")
                FeatureBullet(icon: "checkmark.circle.fill", text: "Feature 2")
                FeatureBullet(icon: "checkmark.circle.fill", text: "Feature 3")
            }
            .padding()

            Spacer()

            purchaseButton(product: product)

            Button("Try Free First") {
                handler.cancelPurchase()
                dismiss()
            }
            .foregroundStyle(.secondary)
        }
        .padding(32)
    }

    // MARK: - Shared Purchase Button

    @ViewBuilder
    private func purchaseButton(product: Product) -> some View {
        Button {
            isPurchasing = true
            Task {
                do {
                    _ = try await handler.completePurchase()
                    dismiss()
                } catch {
                    purchaseError = error.localizedDescription
                }
                isPurchasing = false
            }
        } label: {
            if isPurchasing {
                ProgressView()
                    .frame(maxWidth: .infinity)
            } else {
                Text("Buy for \(product.displayPrice)")
                    .frame(maxWidth: .infinity)
            }
        }
        .buttonStyle(.borderedProminent)
        .controlSize(.large)
        .disabled(isPurchasing)
    }
}

private struct FeatureBullet: View {
    let icon: String
    let text: String

    var body: some View {
        HStack(spacing: 12) {
            Image(systemName: icon)
                .foregroundStyle(.green)
            Text(text)
        }
    }
}