iOS Installation


In the instructions below, remember to replace your app ID with the ID of the environment to which you want to send data. You can find this ID on the Account > Manage > Projects page by clicking on the project and pulling it up in the side menu.


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

Base Installation

There are two options for installing the Heap iOS SDK. We recommend installing via CocoaPods as it is the quickest and easiest method.

Before you get started with the instructions below, we recommend you first review Before Installing: Key Considerations in our Help Center.

Requirements and Known Limitations

The Heap iOS SDK supports iOS 9 and up.

Option 1: Install via CocoaPods

CocoaPods is a Ruby-based dependency manager for iOS projects, similar to Carthage.

  1. To get started, follow the instructions for installing CocoaPods at
  2. Save the following line to your Podfile:
pod 'Heap', ‘~> 7.0’
  1. Run pod install within your project directory.
  2. Initialize Heap with your app ID. We recommend doing this in application:didFinishLaunchingWithOptions: within your application delegate as follows:
#import <Heap/Heap.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      [Heap initialize:@"YOUR_APP_ID"];
    return YES;

Alternatively, you can use this snippet to set specific install options:

#import "Heap.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    HeapOptions *options = [[HeapOptions alloc] init];
    options.debug = YES;
    options.disableTextCapture = YES;
    [Heap initialize:@"YOUR_APP_ID" withOptions:options];
    return YES;

Make sure you open the file with the .xcworkspace extension.



If you use CocoaPods and your data does not appear in the dashboard, please check that Other Linker Flags is set per the manual instructions below (step 4), and that all libraries below are correctly linked (step 5).

Option 2: Install Manually

Installing the Heap iOS SDK without CocoaPods takes a bit longer.

  1. Download the Heap iOS library (clicking this link will start the download).
  2. Unzip the downloaded file and drag libHeap.a and Heap.h into your Xcode project. Make sure to check Copy items if needed.
  3. Click on the project (blue project icon), and select “Build Settings”.
  4. In Build Settings, include -ObjC in Other Linker Flags.
  1. Link your app with the SystemConfiguration framework.
  2. Initialize Heap with your app ID per the code snippet above.

Using the Heap iOS SDK in Swift

Heap's iOS SDK is written in Objective-C code. This means a bridging header is required to import Heap's Objective-C code into the Swift app.

The Heap iOS SDK fully supports Swift if an Objective-C bridging header is included in your Xcode project. Ensure that Heap.h is imported in the bridging header so that the Heap iOS SDK is exposed to Swift.

In your bridging header (e.g., MyApp-Bridging-Header.h):

#import <Heap/Heap.h> // If you installed manually, import "Heap.h" instead

In your application delegate:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    return true

Alternatively, set specific install options using HeapOptions per the following example:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {    
    let options = HeapOptions()
    options.debug = true
    options.disableTextCapture = true
    Heap.initialize("YOUR_APP_ID", with: options)
    return true

Using Heap in iMessage Apps

Heap should work with standalone iMessage apps if you override didBecomeActive in your MSMessagesAppViewController.

func didBecomeActive(with conversation: MSConversation) {

Enable Event Visualizer Pairing

Heap’s Event Visualizer for iOS allows you to easily define iOS events from within Heap. You can then use these events in your analysis to look for opportunities to optimize your user experience on iOS.

As part of setting up Heap for iOS, we strongly recommend completing the step below.

Step 1: Register the URL Type


You will need to repeat this step for every Heap environment that you want to associate with your iOS app.

Navigate to the Info tab of your Xcode project settings page and look for the URL Types section. Add a new URL type matching the following parameters:

Identifier: This is simply a unique string. Your app’s bundle ID should suffice.

URL Scheme: This is based on your environment ID. Set this to exactly heap-<environment_id>.

For example, for Heap environment 89742597891, the URL Types section might look like this:

Feel free to leave the Role and Icon parameters as-is, as they won’t impact your setup.

Step 2: Handle Inbound URLs

Now that the URL type is set up, your application should be launched when iOS sees a URL matching the heap-<environment_id> scheme. The next (and final) step is to handle these URLs in your app delegate and pass them to the Heap library.


If your app delegate already contains an application:openURL:options: method, add the following line to it:

[Heap handleOpenURL:url options:options];

If not, create it:

- (BOOL)application:(UIApplication *)app
        openURL:(NSURL *)url
        options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
  [Heap handleOpenURL:url options:options];
  return true;


If your app delegate already contains an application(_:open:options:) method, add the following line to it:

Heap.handleOpen(url, options: options)

If not, create it:

func application(_ app: UIApplication,
      open url: URL,
      options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
  Heap.handleOpen(url, options: options)
  return true

Your app is now ready to receive a pairing request from the Heap Event Visualizer via a QR code.

We highly recommend defining a couple of test events to ensure this is set up properly. To do so, see Define Events with the Event Visualizer.

Verify Your Installation

Once installed, run your app to begin capturing data. In the Heap app, select the environment your data is being sent to and check the following to ensure your installation was successful.

Using Live View

  1. Navigate to the Live page within your Heap account.
  2. Filter for your IP address so you can see your specific data flowing into Heap.
  3. Start interacting with your iOS app and see the raw data come in!

Using the Event Visualizer

  1. Navigate to the Event Visualizer page within your Heap account.
  2. Pair your device with the iOS Event Visualizer.
  3. Begin performing actions within your app through the Event Visualizer and watch as Heap captures and displays the corresponding events in the web interface.

For full steps to use the Event Visualizer for iOS, review the iOS platform section of our Event Visualizer guide.

Graph Sessions by Source

  1. Navigate to the Graph analysis module (Analyze > Graph).
  2. Graph Count of Sessions and group by the Source property. Click the Run Query button.
  3. You should see the Source property populated with values ‘ios’, ‘android’, ‘web’, or ‘server’ depending on where Heap is receiving data from.

Note that interactions on mobile web will have Source set to web. To differentiate between desktop and mobile web browsers, add an additional group-by clause using the Platform or Browser property. Events originating from webviews embedded within iOS applications will have the Browser property set to a value such as Safari UIWebView. You can use this value to distinguish these events from Mobile Safari events.

What does your data look like?

As you take the time to test your installation, observe the data coming in. What kind of events are there? What properties are attached to them and what values are they populated with? This is important to note early on, as event definition relies on these property values. The key is to ensure the event can be defined by a set of properties that specifically refer to that particular interaction in the intended context.

Note: If you’re unable to define an event for a specific user action, or an event you’ve defined does not have all the properties you require, you will need to do one or both of the following:

  • Define additional element attributes in code. Review Autocaptured Data for the complete set of properties captured by Heap.
  • Review our docs on Autocaptured Data for iOS for the complete set of properties captured by Heap.
  • Enrich the autocaptured data using our APIs. For additional details, see the Enrich Your Dataset Via APIs page of the Setting Up Heap guide.

Ignoring Sensitive Data and PII


To hide elements, use defined runtime attributes to set heapIgnore to a boolean and make sure it’s enabled. For example:

passwordTextField.heapIgnore = YES;
passwordTextField.heapIgnore = true;

Alternatively, this helpful answer on StackOverflow outlines a clean, reusable approach using Swift property wrappers.

Note that you may need to set heapIgnore on the containing view if the element you’d like to ignore is nested in a deep hierarchy. We encourage you to check that values are ignored as expected before shipping changes to production


Setting disableTextCapture will prevent Heap from capturing target text. By default, Heap does not capture the contents of input fields, but does capture text from other rendered page elements. For limited disabling of text capture, heapIgnore may be sufficient.

For reference, this snippet can be used in your initialization code:

HeapOptions *options = [[HeapOptions alloc] init];
options.disableTextCapture = YES;
[Heap initialize:@"YOUR_APP_ID" withOptions:options];
let options = HeapOptions();
options.disableTextCapture = true;
Heap.initialize(“YOUR_APP_ID”, with: options);

For more information on Heap's data privacy options, see How do I use Heap to comply with data privacy legislation?


iOS SDK version 7.1.0+ allows you to give your end-users the option to opt-out of tracking. There are two ways to set this up.

Prior to initializing Heap, use a HeapOptions object, set the value of the disableTracking property to YES, then pass this object as an argument using + (void)initialize:(NSString *)envId withOptions:(HeapOptions *)options.

After Heap has been initialized, call the new + (void)setTrackingEnabled:(BOOL)trackingEnabled; method with an argument of NO.

Note: The tracking status does not persist between application launches, and your application is responsible for setting the proper enabled/disabled state for each user session.


Using the Heap iOS SDK is designed to be effortless, though occasionally installation issues arise for some installations.

If you’ve run into an issue, first update the SDK by pulling down the latest version. We adhere to the SemVer specification, so MINOR versions will always maintain backwards compatibility. We recommend keeping the SDK up to date with the MINOR version at all times, and the MAJOR version, if possible.

If a version update does not address your issue, please email us at [email protected].

CocoaPods Undefined symbols for architecture armv7s: _OBJCCLASS$_Heap

This compiler error means that the Heap static library isn’t being linked into your app. The most common cause of this is an overridden LIBRARY_SEARCH_PATHS in your build settings. If you have any values in this setting, make sure $(inherited) is the last entry.

Empty screen views and no events

This can occur when parts of the Heap iOS SDK library aren’t loaded at runtime. Add the -ObjC flag Other Linker Flags to resolve this issue.

Crash logs include heap_sendEvent

To capture all events, Heap installs a method swizzle on UIApplication that captures events before passing them to the original listener. If the event listener crashes, Heap will appear in the stack trace even if Heap is not responsible.

If you have reason to believe the Heap iOS SDK is causing a crash, send us a crash report and a reproducible test project to [email protected].

Performance Impact

  • Event size: There is no maximum event size on iOS.
  • SDK size: The Heap iOS SDK adds approximately 200 KB to app bundles.
  • Cross-platform testing: We test the Heap iOS SDK on all major iOS versions 9.0 and above, as well as on all iPhone/iPad and 32-bit/64-bit device combinations.
  • Network impact: The Heap iOS SDK batches all events and submits a request to our servers every 15 seconds. This interval can be adjusted. Events are cached locally if no network connection is present. We also cache the first 200 request batches, each of which can have one or multiple events. A cached event can be any one of:
    • 15 seconds of events
    • One pageview of events (the events in the pageview)
    • One “metadata” request (the new user / new session / new pageview request)
    • One identify request
    • One AUP call
  • Performance: The Heap iOS SDK adds virtually zero performance overhead. Because all processing is done off the main thread, user interactivity and UI rendering are remain unaffected.


For notable updates to the Heap iOS SDK, see the iOS Changelog.

Updated 2 days ago

iOS Installation

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.