Developer GuidesAPI ReferenceHelp CenterEngineering BlogCommunity
Open App

iOS Autocapture Installation

Suggest Edits

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, please refer to our Swift Core documentation.

📘

For notes on the latest SDK versions, see our iOS changelog.

Installation

Heap IOS Autocapture can be installed using Swift Package Manager or CocoaPods.

Swift Package Manager Installation

  1. Add Package (File > Add Packages… or Project > Package Dependencies)

  1. In the top right corner of the control, paste https://github.com/heap/heap-ios-autocapture-sdk into the Search or Enter Package URL text field.

  1. Use the Dependency Rule Up to Next Major Version and use the suggested version.

  1. Click Add Package in the lower right corner of the dialog.

  1. Confirm you're adding to the app target and click Add Package.

CocoaPods Installation

CocoaPods is a Ruby-based dependency manager for iOS projects. Heap requires CocoaPods 1.11.0 or later.

  1. To get started, follow the instructions for installing CocoaPods at https://cocoapods.org.
  2. Save the following line to your Podfile:
pod 'HeapIOSAutocapture', '~> 0.1.2'
  1. Run pod install within your project directory.
  2. If you were not already using CocoaPods or a Workspace, close your project and open the new file with the .xcworkspace extension.
  3. Before continuing to Initializing Heap iOS Autocapture, build the app to help Swift resolve the modules.

Initializing Heap iOS Autocapture

When you want to start recording, call Heap.iOSAutocaptureSource.register(isDefault: true) in the manner shown in the code snipped below.

We typically recommend invoking this in application(_:,didFinishLaunchingWithOptions:) within your application delegate to capture the whole lifecycle of the app, but this can be called at a later point if you need to wait for conditions to be met.

import HeapSwiftCore
import HeapIOSAutocapture
...

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
}

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.

Updated 16 days ago