> For the complete documentation index, see [llms.txt](https://docs.chartbeat.com/cbp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chartbeat.com/cbp/tracking/mobile-app-sdks/ios-sdk.md). # iOS SDK ## Add the SDK to your app The Chartbeat iOS SDK is a framework written in Swift and Objective-C providing Chartbeat tracking functionality to native iOS apps. Like any other framework added to your project, the Chartbeat SDK provides a programming interface usable from your app code. ### Overview The Chartbeat iOS SDK is a native Objective-C library that sends real-time engagement beacons ("pings") to Chartbeat so iOS apps can be measured in the same dashboards as the publisher's web content. The SDK exposes a single `CBTracker` singleton that you start once at app launch and feed view/engagement/conversion events throughout the app's lifetime. * **SDK name:** `Chartbeat` * **Language:** Objective-C (Swift-interoperable via `import Chartbeat`) * **Public interface header:** `CBTracker.h` *** ### Requirements | Item | Minimum | | --------------------- | --------------------------------------------------------------------------------------- | | iOS deployment target | 13.0 (per podspec of the RN bridge that consumes it; project itself supports older iOS) | | Xcode | Project is maintained against current Xcode releases (As of today, Xcode 26 version) | **Swift support:** `import Chartbeat` works from any Swift file once the framework is integrated. *** ### Installation There are three supported installation paths. #### 1. CocoaPods (recommended) We recommend adding the SDK to your iOS project using [**CocoaPods**](https://cocoapods.org/pods/Chartbeat). To start using the Chartbeat iOS SDK in your XCode iOS project, follow these steps: 1. Add a line referencing the SDK to your project's Podfile: `pod ‘Chartbeat’, '~> 1.5.0'` 2. Replace the version specifier in this Podfile line with the version of the latest release from [**this listing**](https://github.com/chartbeat-labs/chartbeat-ios-sdk/releases) 3. Run `pod install` from your Xcode project directory to install the SDK and its dependencies, creating a new Xcode workspace. #### 2. Swift Package Manager Beginning with Chartbeat iOS SDK 1.5.0, the Chartbeat iOS SDK supports an installation via Swift Package Manager 1. Select "Add package" in the Package Dependencies menu of Project settings. 2. In the Search bar, search for the Chartbeat SDK Github URL: 
https://github.com/chartbeat-labs/chartbeat-ios-sdk
3. Select `chartbeat-ios-sdk`. #### 3. Manual Outside of using CocoaPods and Swift Package Manager, you can also download the [latest version of the iOS SDK from Github](https://github.com/chartbeat-labs/chartbeat-ios-sdk) and copy it into your project. {% hint style="success" %} **Tip:** Make sure that the framework is added with the option `"Embed and sign"` in the menu "General" of "Target Settings" {% endhint %} ## Using the SDK Chartbeat tracks each app visit by calling corresponding functions as the user interacts with your app. Implement the following steps for integrating the Chartbeat Mobile SDK for iOS. ### Initialize the tracker At app startup, import the `CBTracker.h` file in your app’s delegate. #### Objective-C: ```objectivec #import ``` #### Swift: ```swift import Chartbeat ``` Initialize the tracker by calling the method on the tracker singleton obtained via `[CBTracker sharedTracker]`. Call this method directly in the `applicationDidBecomeActive` method of your app delegate. {% hint style="success" %} **Tip:** Remember to replace placeholder account ID and domain value (`1234` and `mysite.com`) with your organization's account ID and site ID. {% endhint %} #### Objective-C: ```objectivec [[CBTracker sharedTracker] setupTrackerWithAccountId:1234 domain:@"mysite.com"]; ``` #### Swift: ```swift CBTracker.shared().setupTracker(withAccountId: 1234, domain: "mysite.com") ``` #### Swift 2.x: ```swift CBTracker.sharedTracker().setupTracker(withAccountId: 1234, domain: "mysite.com") ``` #### Swift 3.x: ```swift CBTracker.shared().setupTracker(withAccountId: 1234, domain: "mysite.com") ``` {% hint style="success" %} **Tip:** When integrating with a Swift Framework, don't import ``in your framework header file. Doing so while importing Chartbeat in swift files will cause compile errors. {% endhint %} *** ### Track screen views Add the `trackView` call (see below) to any view you want Chartbeat to track. **Page Metadata** If you have views in your app that do not correspond to a page on your website, you can track user interactions on that screen by setting a `viewId` that does not conflict with other page paths from your site. Traffic for this view will then be tracked as a separate page in your dashboard. For example, you can track users in your app’s table of contents by setting the `viewId` to something like `https://mysite.com/nativeapp/main-toc`. Pass section and author data for every view you track to ensure consistency between different views. Call `setSections` and `setAuthors` with an array of strings for each **before** calling `trackView`. Any sections and authors you set will stay set until you set a different set of values. If the user is navigating from a view with sections or authors to another view with no applicable sections or authors, you should set the sections or authors to an empty array. {% hint style="warning" %} **Tip:** Chartbeat uses the "|" character for a splitting process when organizing section and author values, so it is recommend to avoid this character when defining these variables. {% endhint %} #### Track each view In each view controller's `viewDidAppear:`: 1. Set metadata (`setAuthors`, `setSections`, etc.) — pass empty arrays when a view has no section/author metadata. 2. Call `trackView:viewId:title:` **Objective-C** ```objective-c - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [[CBTracker sharedTracker] setAuthors:@[@"Jane Doe", @"John Smith"]]; [[CBTracker sharedTracker] setSections:@[@"tech", @"news"]]; [[CBTracker sharedTracker] trackView:self.view viewId:@"/article/driverless-cars" title:@"Driverless cars will overpower humanity"]; } ``` **Swift** ```swift override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) CBTracker.shared().setAuthors(["Jane Doe", "John Smith"]) CBTracker.shared().setSections(["tech", "news"]) CBTracker.shared().trackView(view, viewId: "/article/driverless-cars", title: "Driverless cars will overpower humanity") } ``` **SwiftUI**: ```swift .onAppear { if let rootView = UIApplication.shared.windows.first?.rootViewController?.view { CBTracker.shared().trackView(rootView, viewId: "https://blog.chartbeat.com/2025/01/01/product-release-announcement", title: "Product Release Announcement") } } ``` ### Track user subscriber status Beginning with Chartbeat iOS SDK 1.4.0, the Chartbeat Mobile SDK supports tracking subscriber data similar to our [JavaScript subscriber engagement integration](/cbp/tracking/standard-websites/subscriber-engagement.md) for standard websites. These functions are optional and can be skipped if your corresponding website does not utilize our JavaScript subscriber status integration linked above. For proper tracking, it is important to call these functions **before** the first call to `trackView()`: Call `setUserPaid()` to specify a user as a paid subscriber. Call `setUserLoggedIn()` to specify a user as a registered user. Call `setUserAnonymous()` to specify a user as a guest. No additional information needs to be passed to these methods or functions. If at any time the user’s subscription status changes, simply call one of the above functions to ensure proper tracking. ### Stop the tracker Call the `stopTracker` function if you want to pause tracking on certain views. Restart the tracker when the user navigates to a view you do want to track, by calling `trackView` again with the appropriate new arguments. The tracker should automatically stop tracking when the app is backgrounded by a user. If tracking does not stop automatically, consider calling `stopTracker` *before* the app is backgrounded. The same applies for when the app is foregrounded. The tracker should automatically resume, but if this does not happen, you can restart the tracker by calling `trackView` again with the appropriate new arguments. ```objective-c [[CBTracker sharedTracker] stopTracker]; ``` {% hint style="success" %} **Tip:** When you run the tracker in [**debug mode**](/cbp/tracking/mobile-app-sdks/qa-mobile-sdk-integration.md#using-debug-mode), you can see log statements in the console to confirm the activity of the tracker. {% endhint %} ### IP Truncation When [initializing the tracker](#initialize-the-tracker), add the following `usePong` method to point traffic to our proxy layer that de-identifies IP addresses within the EU: **Swift 3.0:** ```swift CBTracker.shared().setupTracker(withAccountId: accountId, domain: domain) CBTracker.shared().usePong = true ``` *** ## Next steps Review your integration for data accuracy using our integration QA steps for mobile apps, up next. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.chartbeat.com/cbp/tracking/mobile-app-sdks/ios-sdk.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.