Heap

Server-side event and user property delivery to Heap via the Server-Side API for product analytics and digital experience insights.

Prerequisites

Before configuring Heap in Datafly Signal, you need a Heap account, a project, and your App ID and API key.

API Endpoint

POST https://heapanalytics.com/api/track           (events)
POST https://heapanalytics.com/api/add_user_properties  (user properties)

Events and user properties are sent as JSON payloads to the Heap Server-Side API. Authentication is handled via the app_id field in the request body.

Configuration

Management UI Setup

1. Go to Integrations in the sidebar.
2. Open the Integration Library tab.
3. Find Heap or filter by Analytics.
4. Click Install and fill in the required fields:
   • Enter your App ID from Step 3.
   • Paste your API Key from Step 4.
5. Click Install Integration to create the integration with a ready-to-use default blueprint.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/heap/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Heap",
    "variant": "default",
    "config": {
      "app_id": "1234567890",
      "api_key": "your_api_key"
    },
    "delivery_mode": "server_side"
  }'

Identity

Heap uses a combination of identity and anonymous user IDs to track visitors.

Anonymous Users

When a visitor has not been identified, Datafly Signal sends the Datafly anonymous_id as Heap’s user identifier. This creates an anonymous user session in Heap.

Identified Users

When your application calls datafly.identify(userId), the user ID is forwarded to Heap as the identity field. Heap merges the anonymous and identified user profiles, attributing prior anonymous activity to the known user.

datafly.identify("user-123", {
  email: "jane@example.com",
  plan: "premium"
});

Event Mapping

The Retail variant maps the following events to Heap:

Identity

The default blueprint maps user_id to Heap’s identity field. Anonymous visitors are tracked using Signal’s anonymous identifier until datafly.identify() is called, at which point Heap merges the anonymous and identified profiles.

Consent

Default consent category: analytics.

User Properties

When datafly.identify() is called with traits, those traits are sent to Heap as user properties via the add_user_properties API endpoint:

datafly.identify("user-123", {
  email: "jane@example.com",
  company: "Acme Inc",
  plan: "enterprise"
});

This results in a Heap API call:

{
  "app_id": "1234567890",
  "identity": "user-123",
  "properties": {
    "email": "jane@example.com",
    "company": "Acme Inc",
    "plan": "enterprise"
  }
}

User properties persist on the user profile and are available for segmentation and analysis in the Heap dashboard.

Verify it’s working

1. In the Signal Management UI, open your Heap integration and watch the Live Events stream as you trigger events on your site.
2. Confirm 200 responses from heapanalytics.com/api/track.
3. In Heap, open Users and click into a recent visitor — the Event Feed should populate within 1-2 minutes.

Testing

Once your integration is active and events are flowing, verify in Heap:

1. In the Heap dashboard, go to Users and search by identity (user ID) or look for recent anonymous users.
2. Click on a user to view their Event Feed — events should appear in near real-time.
3. Verify that event properties are populated correctly on each event.
4. Check User Properties on the user profile to confirm traits from identify calls.
5. In Datafly Signal, check the Delivery Logs for the Heap integration to verify successful API responses.

Troubleshooting

Delivery

Events are delivered server-side from your Datafly Signal infrastructure directly to the Heap Server-Side API. No client-side Heap scripts are loaded for this integration.

Blueprint

The Heap blueprint version is 0.1.0 (alpha). It ships with a Retail variant covering page views, product views, and orders.

See also

• Mixpanel — alternative product analytics destination.
• Amplitude — alternative product analytics destination.