Swift

Automated

Prefer to automate this? The Appstack CLI detects your project, installs and configures the SDK, then verifies the result:

npx appstack-cli integrate

Already integrated? npx appstack-cli review audits it without changing any files.

AI-assisted

Use Cursor, Claude Code, or another AI to help you integrate the Swift SDK.

Open in Cursor

Repository

Here, you will find the GitHub iOS Appstack SDK documentation. Please use the latest available version of the SDK. Current stable release: 4.7.2, published 22 September 2026. See the changelog for everything that changed.

Quickstart

Use this path when you only need the minimum production integration:

Add the Swift package from https://github.com/appstack-tech/ios-appstack-sdk.git.
Copy the Production API key from SDK in Appstack.
Call AppstackAttributionSdk.shared.configure(...) during app startup.
Send standard events such as .LOGIN, .SIGN_UP, .PURCHASE, and .SUBSCRIBE.
Confirm events appear in the Appstack SDK page before enabling downstream integrations.

import AppstackSDK

AppstackAttributionSdk.shared.configure(apiKey: "your_production_api_key")

AppstackAttributionSdk.shared.sendEvent(
    event: .PURCHASE,
    parameters: ["revenue": 29.99, "currency": "USD"]
)

Watch the video walkthrough

Claude

Codex

AI agent

Manual

Requirements

iOS 13.0+
Xcode 14.0+
Swift 5.0+

Initial setup

Installation

You can install the SDK via Swift Package Manager (SPM) by adding the following dependency to your Package.swift file:

dependencies: [
    // Set `from:` to the latest stable semver from the repo’s releases (do not leave a stale pin).
    .package(url: "https://github.com/appstack-tech/ios-appstack-sdk.git", from: "X.Y.Z")
]

Or directly from Xcode:

Go to File > Add Packages.
Enter the repository URL: https://github.com/appstack-tech/ios-appstack-sdk.git.
Select the desired version and click Add Package.

Initialization

Follow these steps to get the API key:

In Appstack, from the side menu, select SDK and ensure you are selecting the correct application.
Select the Production environment.
Copy the API key.

AppDelegate

import UIKit
import AppTrackingTransparency
import AppstackSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Configure Appstack SDK
        AppstackAttributionSdk.shared.configure(apiKey: "your_api_key")

        // Request tracking permission and enable Apple Ads Attribution
        if #available(iOS 15.0, *) {
            ATTrackingManager.requestTrackingAuthorization { status in
                AppstackASAAttribution.shared.enableAppleAdsAttribution()
            }
        }

        return true
    }
}

SwiftUI

import SwiftUI
import AppstackSDK

@main
struct MyApp: App {
    init() {
        AppstackAttributionSdk.shared.configure(apiKey: "your_api_key")
    }

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

Configuration parameters

The configure(...) call takes your API key plus optional logLevel and customerUserId. The API key is the only required parameter; see the Swift API reference for the full signature, parameter descriptions, and log levels.

// With optional parameters
AppstackAttributionSdk.shared.configure(
    apiKey: "your_api_key",
    logLevel: .info,
    customerUserId: "user_123"
)

logLevel only controls integrator-facing console output; it does not change what the SDK sends.

Customer user ID

The customer user ID is your own identifier for the signed-in user. Appstack attaches it to events so server-to-server events — which identify the user by this ID rather than by the install — can be joined back to the install that produced them.Set it as soon as it is known — at configure time via the customerUserId parameter, or later, most often once a login reveals it. It applies to every event sent from then on, including ones already buffered, and at least one event has to follow for it to take effect. See setCustomerUserId(_:) in the API reference for the full semantics.

AppstackAttributionSdk.shared.setCustomerUserId("user_123")

Sending events

Send standard events with the EventType enum, and custom events with .CUSTOM plus a name:

// Standard event
AppstackAttributionSdk.shared.sendEvent(event: .LOGIN)

// Revenue event
AppstackAttributionSdk.shared.sendEvent(
    event: .PURCHASE,
    parameters: ["revenue": 29.99, "currency": "USD"]
)

// Custom event
AppstackAttributionSdk.shared.sendEvent(
    event: .CUSTOM,
    name: "user_attributes",
    parameters: [
        "email": "test@example.com",
        "name": "first_name last_name",
        "phone_number": "+33060000000",
        "date_of_birth": "2026-02-01"
    ]
)

Initialize the SDK during app startup before sending events, and make sure event names match those defined in the Appstack platform. Revenue parameters are converted automatically from numbers or numeric strings. INSTALL is tracked automatically on SDK initialization. Do not send it manually. See the Swift API reference for the full signature, parameter details, and the complete list of EventType values.Enhanced app campaigns

When running enhanced app campaigns (EACs), it is highly recommended to send multiple parameters with the in-app event to improve matching quality.

For any event that represents revenue, send revenue or price (number) and currency (string, e.g. EUR, USD). To improve matching quality on Meta and TikTok, also send these when you can:

email.
name (first + last name in the same field).
phone_number — also accepted as phone or phoneNumber.
date_of_birth (recommended format: YYYY-MM-DD) — also accepted as birthdate, birthday, or dateOfBirth.
gender.

Appstack automatically encrypts these matching parameters before using them for attribution matching.

Appstack ID and attribution params

After configure, you can read the Appstack user ID and the attribution map for partner integrations (for example Superwall, RevenueCat).

let appstackId = AppstackAttributionSdk.shared.getAppstackId()
let attributionParams = await AppstackAttributionSdk.shared.getAttributionParams()

getAttributionParams() waits for the attribution match to finish, so you do not need a fixed delay after launch. For the full signatures and return values, see the Swift API reference. A matched install returns something like:

// [
//   "appstack_adnetwork": "meta",          // "google", "meta" or "tiktok"
//   "appstack_campaign": "summer_sale",
//   "appstack_adset": "lookalike_1pct",
//   "appstack_ad": "video_15s",
//   "appstack_id": "9f1c8b64-...",
//   "appstack_match_status": "matched"
// ]

appstack_adnetwork is google, meta or tiktok. It is absent when the click carried no recognised network param — for a standard link, read media_source instead. On Google the campaign, ad set and ad values are numeric IDs rather than names. appstack_id comes back on every result, including organic ones, so read appstack_match_status rather than testing whether the map is empty. For the meaning of each appstack_match_status value and how to read it, see the Swift API reference.

Development setup

If you want to test the SDK against the Appstack development environment before shipping, follow these extra steps:

In Appstack, from the side menu, select SDK, switch to the Development environment, and copy the Development API key. This key is separate from your production key.
In your configure(...) call, use the development key and raise the log level:

AppstackAttributionSdk.shared.configure(
    apiKey: "your_development_api_key",
    logLevel: .debug
)

The API key is what selects the environment — there is no flag to set. A development key routes to the development environment, a production key to production; both use the same endpoint.

Security and privacy

Never commit API keys to version control.
Use separate production and development keys, and make sure release builds ship the production key.
Do not put personally identifiable information in event names.
Only send matching parameters such as email, name, phone_number, and date_of_birth when your app has the right consent and compliance basis. Appstack automatically encrypts these fields before using them for attribution matching.
Prefer standard event types for common flows so event mapping remains consistent across Appstack and ad integrations.

Advanced configuration

SDK behavior

The SDK automatically:

Fetches configuration from Appstack servers.
Manages conversion value updates based on event tracking.
Handles revenue range matching for conversion optimization.
Queues events when the configuration is not ready.

Event processing

Events are processed asynchronously to avoid blocking the main thread.
The SDK queues events if the configuration is not yet loaded.
Revenue parameters are automatically validated and converted to numeric values.
Events are matched against configured revenue ranges in real-time.

Limitations

Attribution timing

Apple Ads attribution requires iOS 15.0+ (AppstackASAAttribution is annotated @available(iOS 15.0, *)).
Apple Ads attribution requires app installation from the App Store or TestFlight.
Attribution is matched within seconds of the app opening after install.
Some attribution behavior may not be available in development or simulator environments.

Event tracking

The SDK must be initialized during app startup before any tracking calls.
INSTALL is tracked automatically on SDK initialization. Do not send it manually — the SDK drops such calls.
Revenue events should include revenue or price and currency.
Event processing is asynchronous and can queue events while configuration is loading.

Troubleshooting

Configuration fails

Confirm the API key was copied from the correct app and environment in Appstack.
Check that the SDK package is installed from the correct repository URL.

Events do not appear

Confirm configure(...) runs before the first sendEvent(...) call.
Confirm the device has network connectivity.
Check that revenue events include a numeric revenue or price value and a valid currency.
Allow a few minutes for events to appear in the dashboard.

iOS install event does not appear

If you have a StoreKit test configuration enabled and are using a production API key, the SDK will not record the install.
For StoreKit test configuration runs, use the development API key.
For production-key validation, disable the StoreKit test configuration.

Apple Ads attribution does not appear

Confirm the app was installed from the App Store or TestFlight.
Confirm the device runs iOS 15.0+.
Call AppstackASAAttribution.shared.enableAppleAdsAttribution() after initialization and in the appropriate ATT flow.
Attribution is matched within seconds of the app opening.

Apple Ads

To start using the Apple Ads integration, click here to see the correct SDK documentation.

Verification checklist

Swift package installed from https://github.com/appstack-tech/ios-appstack-sdk.git.
App target meets iOS 13.0+, Xcode 14.0+, and Swift 5.0+ requirements.
Production API key is used in release builds.
Development API key is used only in development builds.
configure(...) runs once during app startup.
The customer user ID is set — via configure(...) or setCustomerUserId(...) — as soon as it is known, and at least one event follows it.
INSTALL is not sent manually.
Login, signup, purchase, subscription, and other key app events use standard event types where possible.
Revenue events include revenue or price and currency.
Custom events use .CUSTOM with a descriptive name.
Appstack ID and attribution params are available before wiring partner integrations.
Apple Ads attribution is enabled only on supported iOS versions and in the correct permission flow.
Events are visible in the Appstack SDK page before launch.

Support

For questions or issues:

Check the GitHub Repository.
Contact our support team at support@appstack.tech.
Open an issue in the repository.

Use Cursor, Claude Code, or another AI to validate your existing Appstack Swift SDK integration.

Open in Cursor

Getting started

Mobile SDKs

Integrations

Products

Developer tools

Automated

AI-assisted

Repository

Quickstart

Requirements

Initial setup

Appstack ID and attribution params

Development setup

Security and privacy

Advanced configuration

SDK behavior

Event processing

Limitations

Attribution timing

Event tracking

Troubleshooting

Configuration fails

Events do not appear

iOS install event does not appear

Apple Ads attribution does not appear

Apple Ads

Verification checklist

Support

​Automated

​AI-assisted

​Repository

​Quickstart

​Requirements

​Initial setup

​Appstack ID and attribution params

​Development setup

​Security and privacy

​Advanced configuration

​SDK behavior

​Event processing

​Limitations

​Attribution timing

​Event tracking

​Troubleshooting

​Configuration fails

​Events do not appear

​iOS install event does not appear

​Apple Ads attribution does not appear

​Apple Ads

​Verification checklist

​Support

Automated

AI-assisted

Repository

Quickstart

Requirements

Initial setup

Appstack ID and attribution params

Development setup

Security and privacy

Advanced configuration

SDK behavior

Event processing

Limitations

Attribution timing

Event tracking

Troubleshooting

Configuration fails

Events do not appear

iOS install event does not appear

Apple Ads attribution does not appear

Apple Ads

Verification checklist

Support