Swift

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

Repository

Here, you will find the GitHub iOS Appstack SDK documentation. Please use the latest available version of the SDK.

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"]
)

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 AppstackAttributionSdk.shared.configure() method supports the following parameters:

apiKey (String, required): Your Appstack API key.
logLevel (LogLevel, default: .info): Console log verbosity. One of .off, .error, .info, .debug.
customerUserId (String?, default: nil): Your own user identifier, attached to the event payload.

Configuration examples

// Minimum configuration — the API key is the only required parameter
AppstackAttributionSdk.shared.configure(apiKey: "your_api_key")

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

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

Level	Output
`.off`	No SDK logs.
`.error`	Actionable errors only, such as invalid API keys or incorrect SDK usage.
`.info`	Errors plus high-level SDK lifecycle confirmations.
`.debug`	Info logs plus sanitized integration troubleshooting details.

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. That can be before configure runs, at configure time via the customerUserId parameter, or later — most often once a login reveals it:

AppstackAttributionSdk.shared.setCustomerUserId("user_123")

customerUserId (String): your identifier for the signed-in user. Leading and trailing whitespace is trimmed.
Safe to call from any thread. It applies to every event sent from then on, including ones already buffered.
If you also pass a customerUserId to configure(...), that value wins; passing none leaves the ID you already set in place.
The call does not send anything by itself: make sure at least one event follows, or no mapping is ever formed.
Calling configure(...) again to set the ID does not work — a repeat configure(...) is a no-op and its customerUserId is ignored. Use setCustomerUserId instead.

Sending events

Important notes

Initialize the SDK during app startup before sending events
Event names must match those defined in the Appstack platform
Parameters are passed as a dictionary [String: Any] and can include any key-value pairs (e.g., revenue, currency, quantity)
Revenue parameters support automatic type conversion (Double, Int, Float, String)
Revenue ranges are configured in the Appstack platform and automatically synchronized

Predefined event valuesThe SDK provides better type safety with predefined event types:

// Standard events using EventType enum
AppstackAttributionSdk.shared.sendEvent(event: .LOGIN)
AppstackAttributionSdk.shared.sendEvent(
    event: .PURCHASE,
    parameters: ["revenue": 29.99, "currency": "USD"]
)
AppstackAttributionSdk.shared.sendEvent(
    event: .SUBSCRIBE,
    parameters: ["revenue": 9.99, "currency": "USD"]
)

// Custom events
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"
    ]
)

Available EventType valuesIt is recommended to use standard events for a smoother experience.

The INSTALL event is tracked automatically on SDK initialization. Do not send it manually — sendEvent(...) logs and drops it.

public enum EventType: String {
// Authentication & account
case LOGIN
case SIGN_UP
case REGISTER

// Monetization
case PURCHASE
case ADD_TO_CART
case ADD_TO_WISHLIST
case INITIATE_CHECKOUT
case START_TRIAL
case SUBSCRIBE

// Games / progression
case LEVEL_START
case LEVEL_COMPLETE

// Engagement
case TUTORIAL_COMPLETE
case SEARCH
case VIEW_ITEM
case VIEW_CONTENT
case SHARE

// Catch-all
case CUSTOM  // For custom events
}

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, we recommend sending:

revenue or price (number).
currency (string, e.g. EUR, USD).

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

To improve matching quality on Meta and TikTok, send events including the following parameters if you can fulfill them. Appstack automatically encrypts these matching parameters before using them for attribution matching.

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 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()

getAppstackId() — Appstack user identifier when a partner expects $appstackId or similar.
getAttributionParams() — Attribution payload (campaign, media source, click IDs, device identifiers where available) to forward to partners.

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.
Processes events in time-based windows (0-2 days, 3-7 days, 8-35 days).
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 data can take 24-48 hours to appear.
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.
Allow 24-48 hours for attribution data to appear.

Superwall

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

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

API reference

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

Superwall

Apple Ads

Verification checklist

Support

​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

​Superwall

​Apple Ads

​Verification checklist

​Support

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

Superwall

Apple Ads

Verification checklist

Support