LogoLogo
Help CenterStatusContact
  • Chartbeat Documentation
  • Implement Tracking
    • Standard Websites
      • Adding chartbeat.js to Your Site
      • Customize Tracking Settings
      • Tracking Virtual Page Change
      • User Subscriber Status
      • Alternative Site Integrations
      • Integration QA Steps: Website
      • Additional Page Metadata
    • Google AMP
      • Chartbeat Code for AMP
      • AMP Configuration Variables
      • Alternative AMP Integration
      • Integration QA Steps: AMP
    • Mobile App SDKs
      • Intro to Mobile App Tracking
      • Android SDK
      • iOS SDK
      • Integration QA Steps: Mobile Apps
  • Feature Integrations
    • Headline and Image Testing
      • Adding chartbeat_mab.js to Your Site
      • Image Compatibility
      • Flicker & Flicker Control
      • mab.js Specifications
      • Integration QA Steps: Headline and Image Testing
    • Video Engagement
      • Adding chartbeat_video.js to Your Site
      • Supported OVP Integrations
      • Custom Player Integration SDK
      • Configure Video Tracking Settings
      • Integration QA: Video Tracking
    • Conversion
      • Adding subscriptions.js to Your Site
      • Conversion Events
      • Integration QA Steps: Conversion
      • Supported Conversion Flows
  • API Docs
    • Real-Time API
      • Getting Started with our Real-Time API
      • Traffic Data
      • Video Engagement Data
    • Historical API
      • Getting Started with our Historical API
      • One-time Queries
      • Recurring Queries
      • Metrics, Dimensions, and Filters
    • Headline Testing API
      • Getting Started with our Headline Testing API
      • Raw Data
      • Summary Report
      • Variant Report
    • Conversion API
      • Getting Started with our Conversion API
      • Top Articles
    • Data Lab API
      • Getting Started with Data Lab API
  • Help Center
  • Contact Support
  • Datastream Docs
  • Back to Chartbeat.com
Powered by GitBook
On this page
  • Add the SDK to your app
  • Using the SDK
  • Initialize the tracker
  • Swift Frameworks
  • Track user subscriber status
  • Track screen views
  • Stop the tracker
  • IP Truncation
  • Next steps

Was this helpful?

  1. Implement Tracking
  2. Mobile App SDKs

iOS SDK

Instructions to integrate Chartbeat's iOS SDK to your native app.

PreviousAndroid SDKNextIntegration QA Steps: Mobile Apps

Last updated 6 days ago

Was this helpful?

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.

CocoaPods

We recommend adding the SDK to your iOS project using . 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

  3. Run pod install from your Xcode project directory to install the SDK and its dependencies, creating a new Xcode workspace.

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.

Manual

Outside of using CocoaPods and Swift Package Manager, you can also download the and copy it into your project. Note: .

Tip: Make sure that the framework is added with the option "Embed and sign" in the menu "General" of "Target Settings"

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:

#import <Chartbeat/CBTracker.h>

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.

Tip: Remember to replace placeholder account ID and domain values 1234 and mysite.com with your organization's account ID and site ID.

Objective-C:

[[CBTracker sharedTracker] setupTrackerWithAccountId:1234 domain:@"mysite.com"];

Swift 2.x:

CBTracker.sharedTracker().setupTracker(withAccountId: 1234, domain: "mysite.com")

Swift 3.x:

CBTracker.shared().setupTracker(withAccountId: 1234, domain: "mysite.com")

Swift Frameworks

Chartbeat's iOS SDK requires an alternate install method for use with Swift Frameworks. To integrate with a Swift framework, import Chartbeat at the top of all swift files that use CBTracker.

import Chartbeat

Initialize the tracker by calling the method on the tracker singleton object via [CBTracker sharedTracker].

CBTracker.shared().setupTracker(withAccountId: 1234, domain: "mysite.com")

Tip: When integrating with a Swift Framework, don't import <Chartbeat/CBTracker.h>in your framework header file. Doing so while importing Chartbeat in swift files will cause compile errors.

Track user subscriber status

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 unregistered.

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.

Track screen views

Add the trackView code (below) to any view you want Chartbeat to track.

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.

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.

Objective-C:

[[CBTracker sharedTracker] trackView:self.view

viewId:@"https://blog.chartbeat.com/2025/01/01/product-release-announcement" title:@"Product Release Announcement"];

Swift:

CBTracker.shared().trackView(
self.view,
viewId:
"https://blog.chartbeat.com/2025/01/01/product-release-announcement",
title: "Product Release Announcement"
)

SwiftUI:

.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")
    }
}

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.

IP Truncation

Swift 3.0:

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.

Beginning with Chartbeat iOS SDK 1.4.0, the Chartbeat Mobile SDK supports tracking subscriber data similar to our 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.

Tip: When you run the tracker in , you can see log statements in the console to confirm the activity of the tracker.

When , add the following usePong method to point traffic to our proxy layer that de-identifies IP addresses within the EU:

CocoaPods
this listing
latest version of the iOS SDK from Github
JavaScript subscriber engagement integration
initializing the tracker
debug mode