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

_df.identify("user-123", {
  email: "[email protected]",
  plan: "premium"
});

Event Mapping

Datafly Signal maps standard events to Heap:

User Properties

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

_df.identify("user-123", {
  email: "[email protected]",
  company: "Acme Inc",
  plan: "enterprise"
});

This results in a Heap API call:

{
  "app_id": "1234567890",
  "identity": "user-123",
  "properties": {
    "email": "[email protected]",
    "company": "Acme Inc",
    "plan": "enterprise"
  }
}

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

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.