Swift Ecosystem quick start

👍

Target Platforms

This quick start guide shows you how to get Heap setup in a Swift or Objective-C application that runs on iOS, iPadOS, macOS, watchOS, or tvOS.

If you are using UIKit or SwiftUI, please refer to their specific quick start guides:

• UIKit Quick Start
• SwiftUI Quick Start

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 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. f you are not currently using either, you can learn more at Apple's Package Manager documentation and CocoaPods.org.

Add the Heap SDK to your application with Swift Package Manager

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/heap/heap-swift-core-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 HeapSwiftCore 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 Heap SDK to your application with CocoaPods

1. Add pod 'HeapSwiftCore', '~> 0.5' 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 Heap SDK

To enable Heap, call startRecording. This can go anywhere in your app, but we recommend doing this during app launch to make sure tracking starts, no matter how your app is opened. ‌The recommended insertion points are:

• A UIKit app delegate's application(_,:didFinishLaunchingWithOptions:) method.
• A Cocoa app delegate's applicationDidFinishLaunching method.
• A SwiftUI app's @StateObject's initializer.
• A command line app's main.swift.

Whichever is the appropriate entry point, the following line should be included.

import HeapSwiftCore

...

// Replace YOUR_APP_ID with your Heap app ID of the environment you wish to send data to. 
Heap.shared.startRecording("YOUR_APP_ID")

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.