Swift quickstart

Install the SDK

Add the SDK package to your app target. In Xcode, open File → Add Package Dependencies…, enter https://github.com/voidhashcom/voidhash, set the dependency rule to the main branch, and add the Voidhash library to your app target.

If you manage dependencies in a Package.swift, add the package there instead:

dependencies: [
    .package(url: "https://github.com/voidhashcom/voidhash", branch: "main")
],
targets: [
    .target(name: "App", dependencies: [.product(name: "Voidhash", package: "voidhash")])
]

The repository has no release tags yet, so the dependency follows the main branch. Pin a commit with revision: when you need a reproducible build.

The package ships two products. Voidhash is the SDK you integrate against. VoidhashCore is the shared native core it depends on. Add VoidhashCore to your target as well when your code names one of its types, such as SdkPerson or VoidhashStoreError, and import it where you do. To install with CocoaPods instead, see Compatibility.

Configure the client

Configure the client once, while the app launches, with your project's publishable key. In a SwiftUI app, do it in the App initializer.

import SwiftUI
import Voidhash

@main
struct MyApp: App {
    init() {
        Voidhash.configure(publishableKey: "vh_pk_...")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

In a UIKit app, call Voidhash.configure from application(_:didFinishLaunchingWithOptions:). Everywhere else, reach the client through Voidhash.shared. The steps below call it voidhash.

guard let voidhash = Voidhash.shared else { return }

Configure the client at launch rather than in a let at file scope. Swift creates such a global the first time code reads it, so the SDK would not observe transactions or record app launches until then.

The publishable key is safe to include in the app. Never ship vh_sk_... secret keys.

configure starts initialization in the background. Initialization connects to the store, fetches the project schema, and syncs transactions that happened while the app was away. The first call that needs initialization waits for it implicitly. To wait explicitly, for example on a loading screen, call await voidhash.waitForInitialization().

Configure one product in Studio

Set up the smallest catalog that can grant access.

1. Connect App Store Connect so Voidhash can verify your purchases. See Store setup for the steps.
2. Create a perk such as premium.
3. Create a product, attach the perk, and connect the App Store product your app sells.

For the model behind the catalog, see Products and perks.

Make a purchase

Load the products from Voidhash and buy one through the SDK. Use the slug of the product you created in Studio.

import Voidhash
import VoidhashCore

func buyPremium() async throws {
    let products = try await voidhash.getProducts()
    guard let product = products.first(where: { $0.slug == "premium-monthly" }) else {
        return
    }

    do {
        try await voidhash.purchase(product: product)
    } catch let error as VoidhashStoreError where error.code == "USER_CANCELLED" {
        // The customer dismissed the store sheet.
    }
}

purchase(product:) shows the App Store sheet, syncs the transaction with Voidhash, and only then finishes it with StoreKit. The SDK also watches StoreKit for renewals, approved Ask to Buy requests, and purchases made while the app was away, and syncs and finishes them on its own. Do not finish transactions in your own code as well. See Make and restore purchases for pending purchases, restores, and promotional offers.

Check access

Gate a feature on an active perk grant from the person snapshot. Pass the perk slug you set in Studio.

let person = try await voidhash.getCurrentPerson()

let hasPremium = person?.hasActivePerk("premium") ?? false

The SDK refreshes the snapshot once Voidhash accepts a purchase, and after a restore. See Check access for caching behavior and failure handling.

Run a test purchase

Build and run the app on a device signed into a Sandbox Apple account, and buy the product. Once Voidhash accepts the purchase, getCurrentPerson() returns the new grant and the purchase appears in the dashboard.

Purchases from a local StoreKit configuration file in Xcode are not sent to Voidhash, because the App Store cannot verify them. The SDK reports the skip as the STOREKIT_TESTING_TRANSACTION_SKIPPED diagnostic. To test before you set up App Store Connect, use development purchase mode.