Installation

IMPORTANT

If you have not yet installed Heap, you'll find your snippet here. In the snippets 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 within your Account Settings under the Project tab.

Web

To get started with Heap, paste the following code snippet before your website's closing </head> tag:

<script type="text/javascript">
    window.heap=window.heap||[],heap.load=function(e,t){window.heap.appid=e,window.heap.config=t=t||{};var r=t.forceSSL||"https:"===document.location.protocol,a=document.createElement("script");a.type="text/javascript",a.async=!0,a.src=(r?"https:":"http:")+"//cdn.heapanalytics.com/js/heap-"+e+".js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(a,n);for(var o=function(e){return function(){heap.push([e].concat(Array.prototype.slice.call(arguments,0)))}},p=["addEventProperties","addUserProperties","clearEventProperties","identify","resetIdentity","removeEventProperty","setEventProperties","track","unsetEventProperty"],c=0;c<p.length;c++)heap[p[c]]=o(p[c])};
    heap.load("YOUR_APP_ID");
</script>

iOS

Via Cocoapods

We recommend using Cocoapods to quickly and easily add Heap:

  1. Install Cocoapods by running sudo gem install cocoapods.
  2. Create a file in your Xcode project directory called Podfile.
  3. Add the following line to your Podfile: pod 'Heap'
  4. Run pod install within your Xcode project directory.
  5. Initialize Heap with your app ID. We recommend doing this in applicationDidFinishLaunching: or application:didFinishLaunchingWithOptions: in your Application delegate as follows:
#import "Heap.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   [Heap setAppId:@"YOUR_APP_ID"];
#ifdef DEBUG
   [Heap enableVisualizer];
#endif

   /* Other launch code goes here */

   return YES;
}
  1. Make sure you open the file with the extension .xcworkspace

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).

Manual iOS Installation

  1. Download the Heap iOS library.
  2. Unzip the downloaded file and drag libHeap.a and Heap.h into your XCode project. Make sure to select Copy items if needed.
  3. Click on the project (blue project icon), and select "Build Settings".
  4. Within Build Settings, change "Other Linker Flags" to include -all_load -ObjC as a flag.
  5. Link your app to these libraries:
    • CFNetwork.framework
    • Foundation.framework
    • libicucore.tbd
    • Security.framework
    • SystemConfiguration
    • UIKit
  6. Initialize Heap with your app ID, as illustrated in the code snippet above.

Using Heap with Swift

The Heap library should work fine if you use an Objective-C bridge header with your Swift project.

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    // Override point for customization after application launch.

    Heap.setAppId("YOUR_APP_ID");
    #if DEBUG
        Heap.enableVisualizer();
    #endif

    return true
}

Using Heap with iMessage Apps

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

func didBecomeActive(with conversation: MSConversation) {

    Heap.setAppId("YOUR_APP_ID");
    #if DEBUG
        Heap.enableVisualizer();
    #endif
}

Android

Requirements and Known Limitations

  • You'll need to be using Android Studio.
  • The integration only works with Gradle.
  • The build plugin only works on macOS and Linux.
  • The build plugin requires a system-level Python installation. This will be available on macOS by default but may need to be installed separately on Linux. Either Python 2 or 3 will work.
  • The integration does not support React Native.
  • The build plugin supports versions 2.3.x, 3.0.x, 3.1.x and 3.2.1+ of the Android Gradle plugin
  • The integration supports Android build tool version 24.0.3+ except for version 26.0.0 (26.0.1+ is fine).
  • The integration currently only captures sessions, screenviews and clicks/taps.
  • When developing apps with Instant Run, Heap will only record sessions and screenviews—interaction events like taps will not be captured. To test interaction event capture during development, you should disable Instant Run.

Installation Instructions

The following instructions should support any Android app, though we assume a project structure with two build.gradle files, one at the root level and one in the same folder as the app's code.

  1. Create a new test environment in Heap and note the environment ID for initial Android testing. You're welcome to use your existing development environment though we recommend a fresh environment for ease of testing iterations.
  2. In build.gradle at the root level of your project, modify the buildscript section as follows:
buildscript {
  // At the top of the buildscript block, add a property for the SDK version.
  ext.heapVersion = '0.8.1'
  // ...

  dependencies {
    // Within buildscript.dependencies, add the classpath dependency below.
    // Note the double quotes, which are required to interpolate the version.
    classpath "com.heapanalytics.android:heap-android-gradle:${heapVersion}"
  }
}
  1. Modify the app’s build.gradle, within whichever folder your app code lives (for example, /app/build.gradle):

    • Apply the Heap build plugin after the Android plugin:
apply plugin: 'com.android.application'
// Insert line below to apply our plugin
apply plugin: 'com.heapanalytics.android'
  • Add the client library as a dependency:
dependencies {
  // Insert line below to include our client library as a dependency. Note the
  // double quotes, which are required to interpolate the version.
  implementation "com.heapanalytics.android:heap-android-client:${heapVersion}"

  // If you are on an older version of the Gradle build plugin (pre-3.1) you should
  // use the commented line below instead of the one above. The "compile" directive
  // is deprecated as of 3.1.
  // compile "com.heapanalytics.android:heap-android-client:${heapVersion}"
  // ...
}
  • Configure build types to enable the Heap integration:
buildTypes {
    debug {
        // Add this line to a build type to enable Heap event capture.
        ext.heap = ["enabled": true]
        // ...
    }
    // ...
}
    1. Modify the onCreate method of your app's entry point, either an Application subclass or the activity with the android.intent.action.MAIN action in its intent filter:
// Include this import line up top
import com.heapanalytics.android.Heap;
// ...

class MyMainActivity extends BaseActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // Insert line below replacing "MY ENV ID" with your test env from step 1
    Heap.init(getApplicationContext(), "MY ENV ID");
    // ...
}
  1. Add internet permission for the app so it can send data to Heap's servers. In the manifest, add:
    <uses-permission android:name="android.permission.INTERNET" />
  2. Launch the application in the emulator or on a device. To see interaction events while developing, you must disable Instant Run.
  3. Data should be sent to Heap upon interactions! After a few minutes, navigate to Heap's users view to see your recent data and validate that event data is being sent properly.

You can find java documentation available in our API docs if you'd like to identify your users or send custom events and properties to Heap.

Licenses

  • To print license information included in the Heap Gradle plugin, please run gradlew tasks and refer to the "Heap tasks" section.

Electron Applications

Electron support is a work in progress and not yet officially supported by Heap!

If you run into any issues, please contact us, we would love to work with you to improve our support for Electron apps.

Electron doesn't natively support cookies, so Heap's JavaScript web snippet won't work out of the box.

We're currently working on a fork of the electron-cookies package that allows Heap to function within Electron apps, if you'd like to give it a try, it's available here.

To use the forked electron-cookies package in your Electron app, add it to your package.json dependencies like so:

{
  "dependencies": {
    "electron-cookies": "heap/electron-cookies"
  }
}

After you npm install the package, you should be able to add require('electron-cookies'); to your application's renderer.js, and include the web snippet above in your application's HTML.

If your application has nodeIntegration: false in its configuration (this is the most common setup), instead of adding require('electron-cookies'); include the following script tag to your application's HTML after running npm install:

<script src='./node_modules/electron-cookies/dist/electron-cookies.js'></script>