Swift and UIKit SDK reference
This is a reference guide for all Swift and UIKit SDK requirements, known limitations, API reference, and performance impact information.
The Swift and UIKit SDKs are distributed through Swift Package Manager and Cocoapods.
For notes on the latest SDK versions, see our iOS changelog.
If you're using Heap's Classic iOS SDK and thinking about switching to our newest offerings, please note that some event definitions might need to be repaired after upgrade.
Need help with this process? Please post in Community or contact us via the Get support page in Heap.
This reference is exclusive to Heap's current Swift and UIKit SDK offerings. For information about Heap's Classic iOS SDK, you can visit its documentation here.
Heap Swift Core Reference
Requirements + Known Limitations
- This SDK requires the following minimum OS versions:
- macOS 10.14
- iOS 12.0
- watchOS 5.0
- tvOS 12.0
- The SDK requires Xcode 14.0 or later.
- The SDK depends on SwiftProtobuf, a Swift package developed by Apple.
- watchOS support is currently limited to Swift Package Manager implementations.
- watchOS devices will have separate sessions and user IDs from the paired iOS device. Tracking a user across both will require the use of
Heap.shared.identify
to combine the users under a single identity. - macOS apps require the "Outgoing Connections (Client)" permission in the App Sandbox settings.
Installation
Add the Heap SDK to your application with Swift Package Manager
- In Xcode, open the package manager however you are accustomed to. The most direct path is navigating to File → Add Packages… in the menu.
- 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.
- Select a Dependency Rule. We recommend Up to Next Major Version.
- Click Add Package.
- In the next dialog, check the checkbox next to HeapSwiftCore and confirm that it will be added to your app target.
- Click Add Package.
- After the dialog closes, you can optionally confirm that HeapSwiftCore and SwiftProtobuf now appear in the Package Dependencies section of the Project Navigator.
- Before continuing, build your app target to help Swift resolve the modules.
Add the Heap SDK to your application with CocoaPods
- Add
pod 'HeapSwiftCore', '~> 0.6'
to your app target in yourPodfile
. - Run
pod install
within your project directory. - Before continuing, build your app target to help Swift resolve the modules.
API Reference
HeapSwiftCore.Heap
HeapSwiftCore.Heap
The publicly-facing API for the Heap Swift Core SDK.
Note: The Heap object follows the singleton convention and all methods are accessible through Heap.shared
in Swift and Heap.sharedInstance
in Objective-C.
startRecording(_ environmentId: String, with options: [Option: Any] = [:])
startRecording(_ environmentId: String, with options: [Option: Any] = [:])
Description
Initializes the Heap SDK and enables Heap to start recording data.
If Heap is already recording and the options have changed, Heap will restart tracking with the new options, creating a new session. Otherwise, calling this method multiple times with the same value has no effect.
Parameters
environmentId
: The environment ID to which data should be attributed.options
: (optional) A dictionary of configuration options for use starting the SDK. See Swift Custom Configuration for available options.
Objective-C method signatures
- (void)startRecording:(NSString * _Nonnull)environmentId;
- (void)startRecording:(NSString * _Nonnull)environmentId
withOptions:(NSDictionary<HeapOption *, id> * _Nonnull)options;
Examples
// Without options
Heap.shared.startRecording("YOUR_APP_ID")
// With options
Heap.shared.startRecording("YOUR_APP_ID", with: [
.uploadInterval: 60, // Upload every 60 seconds instead of every 15.
])
// Without options
[Heap.sharedInstance startRecording:@"YOUR_APP_ID"];
// With options
[Heap.sharedInstance startRecording:@"YOUR_APP_ID" withOptions:@{
HeapOption.uploadInterval: @60, // Upload every 60 seconds instead of every 15.
}];
stopRecording()
stopRecording()
Description
Shuts down the Heap SDK and prevents any further data collection.
Examples
Heap.shared.stopRecording()
[Heap.sharedInstance stopRecording];
track(_ event: String, properties: [String: HeapPropertyValue] = [:], timestamp: Date = Date(), sourceInfo: SourceInfo? = nil, pageview: Pageview? = nil)
track(_ event: String, properties: [String: HeapPropertyValue] = [:], timestamp: Date = Date(), sourceInfo: SourceInfo? = nil, pageview: Pageview? = nil)
Description
Creates an event message to be tracked and sent to the Heap API.
Parameters
event
: The string name of the event.properties
(optional): TheDictionary
of properties to associate with the event. Keys are represented by strings and values can be any type described in Supported Property Values.timestamp
(optional): The non-nullDate
of when the event occurs. Defaults to the current time. Customer implementations should not assign values for this parameter.sourceInfo
(optional): The nullableSourceInfo
object if this event was generated by an autocapture SDK. Defaults tonull
. Customer implementations should not assign values for this parameter.pageview
(optional): ThePageview
to associate with the tracked event. This is most commonly the case if the event was generated by an autocapture SDK. Defaults tonull
. Customer implementations should not assign values for this parameter.
Objective-C method signatures
- (void)track:(NSString * _Nonnull)event;
- (void)track:(NSString * _Nonnull)event
properties:(NSDictionary<NSString *, id <HeapObjcPropertyValue>> * _Nonnull)properties;
The Objective-C method accepts NSString
and NSNumber
property values, as well as any type that conforms to the HeapObjcPropertyValue
protocol.
Due to runtime limitations, booleans of
@YES
and@NO
are stored as “true” and “false”, while non-Objective-C boolean types are rendered as1
and0
. If this affects analysis, the booleans should be converted to strings before calling the method. For example:@{ @"isDiscounted": isDiscounted ? @"true" : @"false" }
Examples
// Without properties
Heap.shared.track("Added to cart")
// With properties
Heap.shared.track("Added to cart", properties: [
"product_category": self.product.category,
])
// Without properties
[Heap.sharedInstance track:@"Added to cart"];
// With properties
[Heap.sharedInstance track:@"Added to cart" properties: @{
@"product_category": self.product.category,
}];
identify(_ identity: String)
identify(_ identity: String)
Description
Assigns an identity to be associated with the current user ID, used for combining users across multiple implementations.
If the identity is already set and different from the past identity, this will have the effect of resetting the user ID and session while setting the identity.
Parameters
identity
: The string value representing the identity to associate with events. This should uniquely identify the person using the app and never a hard-coded value.
Examples
In this example, the app has a method userAuthenticated
which is called when the user logs into the app.
Heap.shared.identify("some_identity")
[Heap.sharedInstance identify:@"some_identity"];
resetIdentity()
resetIdentity()
Description
Resets the state for a user that was previously identified with identify
, creating a new user and session while clearing event properties. If the user was not previously identified, this method has no effect.
Examples
In this example, the app has a method userLoggedOut
which is called when the user logs out of the app.
func userLoggedOut() {
...
Heap.shared.resetIdentity()
}
- (void)userLoggedOut
{
...
[Heap.sharedInstance resetIdentity];
}
addUserProperties(_ properties: [String: HeapPropertyValue])
addUserProperties(_ properties: [String: HeapPropertyValue])
Description
Add a collection of properties to be associated with the current user.
Parameters
properties
: TheDictionary
of properties to associate with the current user. Keys are represented by strings and values can be any type described in Supported Property Values.
Objective-C method signatures
- (void)addUserProperties:(NSDictionary<NSString *, id <HeapObjcPropertyValue>> * _Nonnull)properties;
The Objective-C method has the same considerations as track
. It accepts NSString
and NSNumber
property values, as well as any type that conforms to the HeapObjcPropertyValue
protocol.
Examples
In this example, the app has a method userAuthenticated
which is called when the user logs into the app.
func userAuthenticated(user: AppUser) {
...
Heap.shared.addUserProperties([
"membership_tier": user.membershipTier,
"team_name": user.team.name,
])
}
- (void)userAuthenticated:(AppUser * _Nonnull)user
{
...
[Heap.sharedInstance addUserProperties:@{
@"membership_tier": user.membershipTier,
@"team_name": user.team.name,
}];
}
addEventProperties(_ properties: [String: HeapPropertyValue])
addEventProperties(_ properties: [String: HeapPropertyValue])
Description
Add a collection of properties to be associated with all future events from the current user.
Parameters
properties
: TheDictionary
of properties to associate with future events. Keys are represented by strings and values can be any type described in Supported Property Values.
Objective-C method signatures
- (void)addEventProperties:(NSDictionary<NSString *, id <HeapObjcPropertyValue>> * _Nonnull)properties;
The Objective-C method has the same considerations as track
. It accepts NSString
and NSNumber
property values, as well as any type that conforms to the HeapObjcPropertyValue
protocol.
Examples
In this example, the app has a method contentLoaded
which is called when a view controller loads data and we want to group future events based on the hero banner that was displayed.
func contentLoaded(content: HomeScreenContent) {
...
if let heroName = content.hero?.name {
Heap.shared.addEventProperties([
"home_screen_hero": heroName,
])
}
}
- (void)userAuthenticated:(AppUser * _Nonnull)user
{
...
NSString *heroName = content.hero.name;
if (heroName != nil) {
[Heap.sharedInstance addEventProperties:@{
@"home_screen_hero": heroName,
}];
}
}
removeEventProperty(_ name: String)
removeEventProperty(_ name: String)
Description
Removes a single event-wide property that was previously added with addEventProperties
.
Parameters
event
: The string name of the event.
Examples
In this example, we want to track a property on all events while a view controller is on screen:
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
Heap.shared.addEventProperties([
"chat_popup_is_visible": true,
])
}
override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
Heap.shared.removeEventProperty("chat_popup_is_visible")
}
- (void)viewDidAppear:(BOOL)animated
{
[super viewDidAppear: animated];
[Heap.sharedInstance addEventProperties:@{
@"chat_popup_is_visible": @YES,
}];
}
- (void)viewDidDisappear:(BOOL)animated
{
[super viewDidDisappear: animated];
[Heap.sharedInstance removeEventProperty:@"chat_popup_is_visible"];
}
clearEventProperties()
clearEventProperties()
Description
Removes all event-wide properties that were previously added with addEventProperties
.
Examples
In this example, the app has a method checkoutComplete
which is called when the finishes a purchase.
func checkoutComplete() {
...
Heap.shared.clearEventProperties()
}
- (void)checkoutComplete
{
...
[Heap.sharedInstance clearEventProperties];
}
userId: String? { get }
userId: String? { get }
Description
Returns the current user ID if Heap is recording, otherwise nil
.
Return Value
The current Heap-generated user ID used for tracking events, or nil
if Heap is not recording.
Examples
let heapUserId = Heap.shared.userId
NSString *heapUserId = Heap.sharedInstance.userId;
identity: String? { get }
identity: String? { get }
Description
Returns the identity if Heap is recording and the user has been identified, otherwise nil
.
Return Value
The value that was provided to identify
for the current user, or nil
if Heap is not recording or identify
has not been called.
Examples
let heapIdentity = Heap.shared.identity;
NSString *heapIdentity = Heap.sharedInstance.identity;
sessionId: String? { get }
sessionId: String? { get }
Description
Returns the current session ID if Heap is recording and the session has not expired, otherwise nil
.
This method is useful for reading the current state for purposes such as logging. If you are using the session ID for server-side events, it is recommended that you use fetchSessionId()
, which will create a new session if needed.
Return Value
The current Heap-generated session ID, or nil
if Heap is not recording.
Examples
let heapSessionId = Heap.shared.sessionId;
NSString *heapSessionId = Heap.sharedInstance.sessionId;
fetchSessionId() -> String?
fetchSessionId() -> String?
Description
Returns the current session ID if Heap is recording, otherwise nil
.
If the previous session has expired, this will start a new session.
Return Value
The current Heap-generated session ID, or nil
if Heap is not recording.
Examples
let heapSessionId = Heap.shared.sessionId;
NSString *heapSessionId = Heap.sharedInstance.sessionId;
Supported property values
By default, track
, addUserProperties
and addEventProperties
accept properties of the following types in Swift:
Bool
Int
,Int64
,Int32
,Int16
,Int8
Double
,Float
String
,Substring
- Literals of the above types.
NSString
,NSNumber
Objective-C accepts just NSString
and NSNumber
because its dictionaries only accept objects.
If you have a custom type you would like to pass as a property value, you can learn more about the HeapPropertyValue
and HeapObjcPropertyValue
types in Swift Custom Configuration.
Heap UIKit Autocapture Reference
Requirements + Known Limitations
- This SDK requires iOS 13.0 or later.
- The SDK is built with the Swift 5.7 toolchain with module stability and requires Xcode 14.0 or later.
- The SDK depends on HeapSwiftCore 0.1.2 or later.
- HeapIOSAutocapture methods that reference Heap directly, like registration, are not available from Objective-C and will need to be called from Swift. A small bridging file can be used to expose the methods.
- The HeapIOSAutocapture SDK does not currently support automatically capturing interactions from UI elements built with SwiftUI. To capture interactions on UI elements built with SwiftUI, use the
track
method described above.
Installation
Add the Heap Autocapture SDK to your application with Swift Package Manager
- In Xcode, open the package manager however you are accustomed to. The most direct path is navigating to File → Add Packages… in the menu.
- Paste https://github.com/heap/heap-ios-autocapture-sdk.git into the Search or Enter Package URL text field at the top right corner of the dialog.
- Select a Dependency Rule. We recommend Up to Next Major Version.
- Click Add Package.
- In the next dialog, check the checkbox next to HeapIOSAutocapture and HeapSwiftCore and confirm that it will be added to your app target.
- Click Add Package.
- After the dialog closes, you can optionally confirm that HeapIOSAutocapture, HeapSwiftCore, and SwiftProtobuf now appear in the Package Dependencies section of the Project Navigator.
- Before continuing, build your app target to help Swift resolve the modules.
Add the Heap Autocapture SDK to your application with CocoaPods
- Add
pod 'HeapIOSAutocapture', '~> 0.6'
to your app target in yourPodfile
. - Run
pod install
within your project directory. - Before continuing, build your app target to help Swift resolve the modules.
API Reference
Registration
When the UIKit autocapture library is added to an app, it doesn't automatically start instrumenting the app or capturing events. For touch events and pageviews to be captured, you first need to register the source and start recording. This is done using Heap.iOSAutocaptureSource
in Swift and HeapIOSAutocapture
in Objective-C.
fun register(isDefault: Boolean = false)
fun register(isDefault: Boolean = false)
Description
Registers the Heap iOS Autocapture SDK. Once registered, the SDK will autocapture UI interactions and source pageviews.
Parameters
isDefault
(optional): Whether or not the Heap UIKit Autocapture SDK should be the default source. This setting informs the Heap Swift Core SDK to use the Heap UIKit Autocapture SDK as a fallback for assigning pageview information to events if those events do not have a currently registered source or if their source fails to return a valid pageview. Defaults tofalse
.
Examples
Heap.iOSAutocaptureSource.register(isDefault: true)
[HeapIOSAutocapture registerAsDefault:YES];
Track enhancements
In an app with multiple visible view controllers, like an iPad app with a UISplitViewController
, custom events triggered by track
will typically be assigned to the last active pageview rather than the view controller it originated from. To support this use case, the Heap UIKit Autocapture SDK adds an additional overload to track
that allows you to set a sender
. If this sender is an on-screen view, the sender will be used to select the most appropriate pageview for the event.
track(_ event: String, properties: [String: HeapPropertyValue] = [:], timestamp: Date = Date(), sender: Any?)
track(_ event: String, properties: [String: HeapPropertyValue] = [:], timestamp: Date = Date(), sender: Any?)
Description
Creates an event message to be tracked and sent to the Heap API.
Parameters
event
: The string name of the event.properties
(optional): TheDictionary
of properties to associate with the event. Keys are represented by strings and values can be any type described in Supported Property Values.timestamp
(optional): The non-nullDate
of when the event occurs. Defaults to the current time. Customer implementations should not assign values for this parameter.sender
(optional): TheUIView
orUIViewController
that originated the event, used for selecting the appropriate pageview. If called from an@IBAction
, the action's sender or view controller can be used.
Examples
// With a sender
@IBAction func addToCart(_ sender: UIButton) {
Heap.shared.track("Added to cart", sender: sender)
}
// Without a sender
@IBAction func addToCart() {
Heap.shared.track("Added to cart", sender: self)
}
View Extensions for Suppressing Sensitive Data
By default, Heap attempts to capture most non-input text from an interaction, including things like button labels, accessibility properties, and the full hierarchy from the touched view. Depending on how your app is designed, some sensitive information may be exposed to events:
- Pageview titles or on-screen labels may contain usernames or email addresses.
- Custom inputs like a pin input or calendar can receive individual touches.
In apps with a higher amounts of sensitive data or more restrictive requirements, there are global settings available through autocapture configuration options in startRecording
. For apps with certain views or controls that need to be restricted, there are view-specific options below.
For example, in the case of a custom pin input, the following would change events from SecretPinView UIButton[tt=1]
to SecretPinView[tt=****]
:
pinView.heapIgnoreInnerHierarchy = true
pinView.heapRedactText = true
heapIgnoreInteractions
(Bool
)
heapIgnoreInteractions
(Bool
)If set on a view or view controller, all touches inside that control will be ignored.
Examples
secretButton.heapIgnoreInteractions = true
secretViewController.heapIgnoreInteractions = true
heapIgnoreInteractionsDefault
(Class property, Bool
)
heapIgnoreInteractionsDefault
(Class property, Bool
)This has the same effect as heapIgnoreInteractions
but is applied at the class level through an overridable class property. If defined, heapIgnoreInteractions
can still be used to override an individual instance.
Examples
class SecretButton: UIButton {
override class var heapIgnoreInteractionsDefault: Bool { true }
}
heapIgnoreInnerHierarchy
(Bool
)
heapIgnoreInnerHierarchy
(Bool
)If set on a view or view controller, all touches inside that control will be attributed to it rather than child views. This can be helpful in blocking sensitive parts of an interaction and keeping implementation details out of a view hierarchy. For example, Heap uses this property internally to suppress inner touches on UIDatePicker
.
Examples
viewWithSecrets.heapIgnoreInnerHierarchy = true
heapIgnoreInnerHierarchyDefault
(Class property, Bool
)
heapIgnoreInnerHierarchyDefault
(Class property, Bool
)This has the same effect as heapIgnoreInnerHierarchy
but is applied at the class level through an overridable class property. If defined, heapIgnoreInnerHierarchy
can still be used to override an individual instance.
Examples
class ViewWithSecrets: UIView {
override class var heapIgnoreInnerHierarchyDefault: Bool { true }
}
heapRedactText
(Bool
)
heapRedactText
(Bool
)If set on a view or view controller, all views inside that element will have their target text redacted, appearing as "****" in events. When building view text recursively, if a child has heapRedactText == true
while the parent has heapRedactText == false
Examples
userNameLabel.heapRedactText = true
Because text can be copied over to accessibility labels when accessibility services are enabled, you may also want to set
heapRedactAccessibilityLabel
if using this property.
heapRedactAccessibilityLabel
(Bool
)
heapRedactAccessibilityLabel
(Bool
)If set on a view or view controller, all views inside that element will have their accessibility label redacted, appearing as "****" in events.
Examples
userNameLabel.heapRedactAccessibilityLabel = true
Performance Impact FAQ
Performance
- Question: What is the performance impact of Heap on a Mobile app?
- Answer: Heap adds virtually zero performance overhead. Heap never blocks the UI thread of the application and memory is only allocated to process events right before they’re persisted or sent to the server.
- Question: Does Heap do a ton of main thread writes that could impact the responsiveness of the application?
- Answer: Heap does not perform any data persistence or networking activity on the main thread. All data persistence and networking operations take place on a background thread.
- Answer: Heap does perform a very small amount of view traversal on the UI thread to fetch event properties from the corresponding UI objects. This operation is very fast and only involves simple property access. All data that is gathered on the UI thread is sent to a background thread for processing.
Network
- Question: Are events stored if there is no internet connection or are they dropped? and how many events get stored?
- Answer: All event data is stored in an SQLite database in application private storage. While online, this database should never grow to more than a few dozen events. While offline, all events are stored in the database until they’re able to be uploaded to the server. However, all data more than 6 days old will be routinely pruned from the database to prevent the database from growing endlessly.
- Question: Does this behavior differ between core & autocapture SDKs?
- Answer: No. Autocapture data is sent to Core for storage.
- Question: How does Heap's event tracking impact network bandwidth?
- Answer: Heap sends event data in small batches every 15 seconds while connected to the internet. While offline, network data remains in storage and no uploads are attempted.
- Question: What about network data consumption?
- Answer: Events on Swift/iOS are roughly 0.5KB in size. Even if we estimate that a typical user produces 2,000 events per day, this only amounts to a single megabyte of data consumption.
- Question: How does Heap mitigate impacting bandwidth?
- Answer: Heap batches event data to be sent to the server every 15 seconds to prevent constant network access. Heap also only sends a maximum of 100 events at a time, amounting to roughly 100KB of data per upload. Additionally, if any network errors occur, Heap pushes back the upload process for a full minute to wait for network conditions to improve.
Device
- Question: Is the user battery life impacted because Heap is running?
- Answer: Heap should not impact battery life in any meaningful way. Events are batched to be sent periodically to prevent constant network access. This upload frequency should closely match the frequency of network activity of regular app usage for connected applications. If the target application doesn’t not routinely access the network, Heap’s upload interval can be increased to reduce network access and mitigate any unnecessary battery usage.
Storage
- Question: How much memory does the Heap SDK add to app IPA’s?
- Answer: Swift Core adds about 860KB to app bundles. iOS Autocapture adds an additional 105KB.
- Question: Where does Heap store user ID and session ID information?
- Answer: Heap stores all event data in a SQLite database in private application storage. Some event metadata, such as environment ID, is stored in a file in private application storage.
Build Features
- Question: What is the expected build-time impact of adding the Heap SDK?
- Answer:
- Swift Core adds around 4 seconds of build time on clean builds
- iOS Autocapture adds around 0.25 seconds of build time on clean builds
- Swift Core + iOS AutoCapture together add around 4.25 seconds of build time on clean builds.
- Answer:
Updated about 1 month ago