iOS

Ensure you have completed the Prerequisites section before continuing.

Installation

note

The minimum supported version for iOS is 13.0.

To set the Minimum SDK target:

1. Open your iOS project in Xcode
2. Select your Target > General > Deployment Info > Ensure that the version is set to 13.0+

Swift Package Manager

1. In your Xcode project, go to File > Add Package Dependencies…
2. Enter the repository URL:

https://github.com/dashxhq/dashx-ios.git

3. Add the DashX library to your app target. If you use push notifications / Firebase integration helpers, also add DashXFirebase.

Configuration

DashX needs to be initialized as early as possible in your application's lifecycle, which can be done in the AppDelegate class within the application(_:didFinishLaunchingWithOptions:) method:

import DashX

// ...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    DashX.configure(
        withPublicKey: "...", // required
        baseURI: "...", // optional
        targetEnvironment: "..." // optional
    )

    // ...

    return true
}

info

Your Public Key is not sensitive, and can be stored in code or within Info.plist. If you're using multiple Environments, we recommend creating separate targets for each Environment, and then creating *.xcconfig files for each combination of Target & Configuration.

• Learn more about xcconfig.
• Check out the Config folder in DashX Demo iOS App for an example.

Optional: lifecycle tracking

To automatically track app installed/updated/opened events and session length:

DashX.enableLifecycleTracking()

Optional: ad tracking

To request App Tracking Transparency permission and enable IDFA collection:

DashX.enableAdTracking()

note

This triggers the ATT permission prompt on iOS 14.5+. Make sure you have added the NSUserTrackingUsageDescription key to your Info.plist.

Permissions

dashx-ios SDK offers the following methods to manage notification permissions:

// Request permission to receive notifications
DashX.requestNotificationPermission { status in
    // status is a UNAuthorizationStatus value
}

// Check current permission status without prompting
DashX.getNotificationPermissionStatus { status in
    // status is a UNAuthorizationStatus value
}

If you manage push tokens manually, you can set them directly:

// Set the APNS device token (typically in didRegisterForRemoteNotificationsWithDeviceToken)
DashX.setAPNSToken(to: deviceToken)

// Set the FCM token (if using Firebase Cloud Messaging)
DashX.setFCMToken(to: fcmToken)

Additionally the SDK tracks network information about the current network connection, containing bluetooth, carrier, cellular, and wifi.

Troubleshooting

As an optional step, you can set the log level for debugging your integration:

DashXLog.setLogLevel(to: .debug)

By default, the log level is set to .error. You can set it to one of: .debug (most logs), .info, .error or .off (no logs).

Usage

tip

Most public methods have async/await variants for Swift concurrency. For example, try await DashX.identify(options:), try await DashX.subscribe(), try await DashX.fetchRecord(urn:), etc.

User Management

// Recommended when you have a signed-in user + identity token
DashX.setIdentity(uid: "123", token: "your-identity-token")

// Send user attributes
do {
    try DashX.identify(withOptions: [
        "uid": "123",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com"
    ])
} catch {
    // Error Handling
}

// Clear identity, generate new anonymous ID, and unsubscribe from push
DashX.reset()

Learn more

Analytics

DashX.track("Button Clicked", withData: [
    "label": "Click here",
    "placement": "top"
])

Track screen views:

DashX.screen("HomeScreen", withData: [
    "referrer": "deep_link"
])

Learn more

Messaging

note

Push notifications require your app to be configured for Firebase Cloud Messaging or APNs.

info

If you use DashXAppDelegate (from the DashXFirebase module), notification delivered, clicked, and dismissed events are tracked automatically. No manual trackMessage() calls are needed.

// Subscribe/unsubscribe for Push Notifications
DashX.subscribe()
DashX.unsubscribe()

// Manage User Preferences (requires DashX.setIdentity(uid:token:))
DashX.fetchStoredPreferences(
    successCallback: { preferences in
        // preferences is [String: Any?]
    },
    failureCallback: { error in
        // ...
    }
)

DashX.saveStoredPreferences(
    preferenceData: ["push": true, "email": false],
    successCallback: { result in
        // ...
    },
    failureCallback: { error in
        // ...
    }
)

Learn more

CMS

DashX.fetchRecord(
    urn: "email/welcome",
    language: "en_US",
    preview: true
) { result in
    switch result {
    case .success(let record):
        print(record)
    case .failure(let error):
        print(error)
    }
}

fetchRecord accepts the following optional arguments:

Name	Type	Example
preview	Bool	true
language	String	"en_US"
fields	[[String: Any]]
include	[[String: Any]]
exclude	[[String: Any]]

DashX.searchRecords(
    resource: "email",
    language: "en_US",
    order: [["created_at": "DESC"]],
    limit: 10,
    preview: true
) { result in
    switch result {
    case .success(let records):
        print(records)
    case .failure(let error):
        print(error)
    }
}

searchRecords accepts the following optional arguments:

Name	Type	Example
filter	[String: Any]	["status": "published"]
order	[[String: Any]]	[["created_at": "DESC"]]
limit	Int	10
page	Int	1
preview	Bool	true
language	String	"en_US"
fields	[[String: Any]]
include	[[String: Any]]
exclude	[[String: Any]]

Assets

DashX.uploadAsset(
    fileURL: localFileURL,
    resource: "users",
    attribute: "avatar"
) { result in
    switch result {
    case .success(let asset):
        print(asset)
    case .failure(let error):
        print(error)
    }
}

Fetch an asset's status and URL:

DashX.fetchAsset(assetId: "asset-id") { result in
    switch result {
    case .success(let asset):
        print(asset.url)
    case .failure(let error):
        print(error)
    }
}

info

Asset uploads poll for completion with exponential backoff (2 s base, capped at 60 s). You can configure DashXClient.maxAssetPollRetries (default: 5) and DashXClient.assetPollBaseInterval (default: 2.0 s).

Error Handling

Completion-based methods return Result types. The SDK defines the following error types via DashXClientError:

Error	Retryable	When
noArgsInIdentify	No	identify() called without options
notIdentified	No	Operation requires an identified user
graphQLErrors	No	Server returned GraphQL errors
networkError	Yes	Network-level failure
assetIsNotReady	Yes	Asset still being processed
assetIsNotUploaded	No	Asset upload failed
customError	No	Other SDK error

Use isRetryable to decide whether to retry:

DashX.fetchRecord(urn: "blog/abc") { result in
    if case .failure(let error) = result,
       let dashXError = error as? DashXClientError,
       dashXError.isRetryable {
        // retry later
    }
}

Each error also provides errorDescription and recoverySuggestion for user-facing messages.

Offline Event Queue

Failed track() calls are automatically queued and retried with exponential backoff (2 s base, capped at 5 min, up to 10 retries, with jitter). The queue holds up to 1,000 events, is persisted via UserDefaults, and flushes automatically after configure() or when the network becomes available.

To manually flush:

DashX.flushEventQueue()