iOS SwiftUI quick start

👍

Target Platforms

This quick start guide shows you how to get Heap setup in a Swift application that primarily uses SwiftUI for creating the user interface.

After completing the setup process, you'll be able to:

• Take full advantage of the Heap API to track custom events and manage user identity.
• Automatically capture changes to the installed app version when recording starts.

📘

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, check the checkbox next to Contentsquare and confirm that it will be added to your app target.
6. Click Add Package.
7. After the dialog closes, you can optionally confirm that 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, 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

@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")
  
    return true  
  }
}

If your app doesn't have an app delegate and is using a SwiftUI App as the entry point, one place to start Heap would be in the init method of a state object:

import SwiftUI

final class StateStore: NSObject, ObservableObject {
    
  init() {
    ...
    Heap.shared.startRecording("YOUR_APP_ID")
  }
  
  ...
}

@main
struct ExampleApp: App {
    
    @StateObject var stateStore = StateStore()
    
    ...
}

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 app version changes without any additional code.

What next?

To find out how to take full advantage of the Heap API to enhance your data capture, check out our mobile tracking guides here.