How do I install the iOS SDK?

Short answer

Register your bundle ID under App analytics › Configuration › SDK code, add the TapCub package with Swift Package Manager (or CocoaPods from the git source), call TapCub.preInit(TapCubConfig(siteKey: "YOUR_SITE_KEY")) in application(_:didFinishLaunchingWithOptions:) and TapCub.initialize() once the user has accepted your privacy policy. Launches, UIKit screens, taps, crashes and main-thread freezes are then collected automatically. Check App analytics › Overview › Realtime for the first start event.

The SDK supports iOS 13+ and tvOS 13+ with Swift 5.9; Objective-C apps use TapCubSDK. It does not use the IDFA and shows no App Tracking Transparency prompt.

1. Register the bundle ID

Open App analytics › Configuration › SDK code and click Add app identifier. Enter your bundle ID, for example com.example.shop. Data from a bundle ID that is not registered is dropped by the collector without any visible error. The page also prints the install snippet with your site key.

2. Add the package

Swift Package Manager: in Xcode choose File › Add Package Dependencies, enter the repository URL shown in the console snippet (https://github.com/tapcub/tapcub-ios) and add the TapCub product to your app target.

CocoaPods: the pod is installed from the git source, not from the CocoaPods trunk:

pod 'TapCub', :git => 'https://github.com/tapcub/tapcub-ios', :tag => '0.1.0'

3. Initialize

import TapCub

func application(_ app: UIApplication,
                 didFinishLaunchingWithOptions opts: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    TapCub.preInit(TapCubConfig(siteKey: "YOUR_SITE_KEY"))
    return true
}

// after the user accepts the privacy policy
TapCub.initialize()

• preInit only stores the config and binds the lifecycle: no collection, no device reads, no network. Call it on the main thread at launch.
• initialize starts collection. If your app does not need a consent step, call it right after preInit.
• appId, appVersion and appBuild default to Info.plist values. appId must match the bundle ID you registered.
• For China mode, pass region: "cn", call initialize after consent and then TapCub.grantConsent(["analytics"]).

Objective-C:

[TapCubSDK preInitWithSiteKey:@"YOUR_SITE_KEY" endpoint:nil appId:nil];
[TapCubSDK start];

4. What is collected automatically

SwiftUI views are not captured automatically: add the .wcScreen("Checkout") modifier or call TapCub.trackScreen("Checkout"). See Track screen views.

5. Send events and identify users

TapCub.track("purchase", props: ["revenue": 19.9, "currency": "USD"])

TapCub.login("USER_ID")          // after sign-in
TapCub.setProps(["plan": "pro"])
TapCub.logout()                  // on sign-out

login is ignored when the project is not in identified mode; events still flow. See Identify users.

6. Verify

Run the app in the simulator or on a device and open App analytics › Overview › Realtime. A start event should appear within seconds.

Privacy and App Store

The package ships a PrivacyInfo.xcprivacy manifest declaring device ID, product interaction, crash data and performance data, with NSPrivacyTracking = false. If you call login, add User ID to your app's own privacy manifest and App Store privacy answers. The device ID is based on the IDFV, with a copy in the keychain. The queue is stored under Application Support, excluded from iCloud backup (8 MB, 10,000 events or 7 days by default).

Crash stacks are recorded as image name and offset; upload or keep the matching dSYM files to symbolicate them.

Troubleshooting

• No data: the bundle ID is not registered, or initialize was never called.
• SwiftUI screens missing: add .wcScreen or trackScreen.
• precondition failure at launch: the site key is empty.
• Stop collection for a user: TapCub.optOut(); optIn() resumes.

Related

• Crash-free rate
• Track app versions
• Identify users
• What is an SDK? Meaning, SDK vs API, and how analytics SDKs work
• Install the Android SDK
• Install on Flutter
• Install on React Native