iOS (UIKit + SwiftUI) quick start

👍

Target Platforms

This quick start guide shows you how to get Heap setup in a iOS, iPadOS, or Catalyst application that uses a mixture of the UIKit framework and SwiftUI for creating the user interface.

After completing the setup process, you will be able to:

• Take full advantage of the Heap API to track custom events and manage user identity.
• Automatically capture a wide variety of user interactions in the UIKit portions of your application with no additional code required.

📘

If you're using Heap Classic and thinking of switching to our latest offerings, check out the full breakdown of the differences between our SDKs here.

Before you begin

This guide assumes you are using Xcode with either Swift Package Manager or CocoaPods to manage external dependencies. If you are not currently using either, you can learn more at Apple's Package Manager documentation and CocoaPods.org.

Add the SDK to your application with Swift Package Manager

👍

Unified SDK

These instructions install our new Unified SDK which includes product analytics powered by Heap and digital experience analytics powered by Contentsquare.

1. In Xcode, open the package manager however you are accustomed to. The most direct path is navigating to File → Add Packages… in the menu.
2. Paste https://github.com/ContentSquare/apple-sdk.git into the Search or Enter Package URL text field at the top right corner of the dialog.
3. Select a Dependency Rule. We recommend Up to Next Major Version.
4. Click Add Package.
5. In the next dialog, confirm that the checkbox next to Contentsquare is checked and that it will be added to your app target.
6. Click Add Package.
7. After the dialog closes, you can optionally confirm that HeapIOSAutocapture, HeapSwiftCore, and SwiftProtobuf now appear in the Package Dependencies section of the Project Navigator.
8. Before continuing, build your app target to help Swift resolve the modules.

Add the SDK to your application with CocoaPods

1. Add pod 'ContentsquareSDK', '~> 0.1' to your app target in your Podfile.
2. Run pod install within your project directory.
3. Before continuing, build your app target to help Swift resolve the modules.

Start the SDK

To enable Heap and start automatically tracking supported user events, register the autocapture SDK and call startRecording. This can go anywhere in your app, but we recommend doing this in the application(_:,didFinishLaunchingWithOptions:) method of your app’s UIApplicationDelegate object to make sure tracking starts, no matter how your app is opened.

import HeapSwiftCore
import HeapIOSAutocapture

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication,  
                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // Replace YOUR_APP_ID with your Heap app ID of the environment you wish to send data to.  
    Heap.shared.startRecording("YOUR_APP_ID")
    Heap.iOSAutocaptureSource.register(isDefault: true)
  
    return true  
  }
}

Once recording has started, you’re able to take full advantage of Heap’s API to identify users, track custom events, and more. Heap will also automatically start tracking a wide range of user interactions in the UIKit parts of your app, UIKit and SwiftUI view controllers changes, and app version changes without any additional code.

What next?

Instrument your UI elements built with SwiftUI to make sure you are capturing a complete dataset of all user interactions. Learn all about Heap’s custom event tracking APIs here.