Amplitude

Server-side event tracking to Amplitude via the HTTP V2 API for product analytics, user behaviour, and conversion analysis.

Prerequisites

Before configuring Amplitude in Datafly Signal, you need an Amplitude account, a project, and your API key. Follow the steps below to set these up.

API Endpoint

POST https://api2.amplitude.com/2/httpapi        (US)
POST https://api.eu.amplitude.com/2/httpapi       (EU)

Events are sent as JSON payloads to the HTTP V2 API. Authentication is handled via the api_key field in the request body.

Configuration

Management UI Setup

1. Go to Integrations in the sidebar.
2. Open the Integration Library tab.
3. Find Amplitude or filter by Analytics.
4. Click Install, select a variant if available, and fill in the required fields:
   • Paste your API Key from Step 3.
   • Select your Data Region (US or EU).
   • Optionally set a Minimum ID Length if your identifiers are shorter than 5 characters.
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/amplitude/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amplitude",
    "variant": "default",
    "config": {
      "api_key": "your_amplitude_api_key",
      "api_endpoint": "https://api2.amplitude.com/2/httpapi"
    },
    "delivery_mode": "server_side"
  }'

Variants

Amplitude is available in multiple pre-configured variants to match your industry:

Each variant provides a tuned default blueprint. You can customise any setting after installation.

Identity

Amplitude uses a two-part identity model based on device_id and user_id.

device_id

The device_id is the primary identifier for anonymous visitors. Datafly Signal maps the Datafly anonymous_id (a first-party identifier generated by Datafly.js and persisted in the visitor’s browser) to Amplitude’s device_id field.

This means every event sent to Amplitude includes a stable device_id from the first page view, even before the user has identified themselves.

user_id

When your application calls datafly.identify(userId), the user_id is forwarded to Amplitude. Once both device_id and user_id are present on an event, Amplitude merges the anonymous and known user profiles into a single identity.

How Amplitude Resolves Identity

1. Anonymous visitor: Events arrive with device_id only. Amplitude creates an anonymous user profile.
2. User identifies: A call to datafly.identify("user-123") causes subsequent events to include both device_id and user_id.
3. Merge: Amplitude automatically merges the anonymous profile (by device_id) with the known profile (by user_id), attributing prior anonymous activity to the identified user.
4. Cross-device: If the same user_id appears from a different device_id, Amplitude links both devices to the same user.

Event Mapping

Datafly Signal maps standard event names to their Amplitude equivalents:

Amplitude’s blueprint uses pass-through event names — Signal’s GA4-style event names are sent unchanged so they line up with the Amplitude browser SDK if you also run it.

User Properties

When your application calls datafly.identify() with traits, those traits are forwarded to Amplitude as user properties via the user_properties field in the HTTP V2 API payload.

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

This sets the following user properties in Amplitude:

{
  "user_properties": {
    "$set": {
      "email": "jane@example.com",
      "plan": "premium",
      "company": "Acme Inc"
    }
  }
}

Amplitude’s $set operator creates the property if it does not exist, or updates it if it does. User properties persist across sessions and are attached to the user’s profile in Amplitude.

Revenue Events

Amplitude has a dedicated revenue tracking system. When Datafly Signal receives an Order Completed event, it maps the transaction data to Amplitude’s revenue fields:

Datafly.js call:

datafly.track("Order Completed", {
  order_id: "ORD-5521",
  total: 89.99,
  currency: "GBP",
  products: [
    { product_id: "SKU-100", name: "Running Shoes", price: 59.99, quantity: 1 },
    { product_id: "SKU-205", name: "Sport Socks", price: 15.00, quantity: 2 }
  ]
});

In Amplitude, this appears as a revenue event with the total value attributed to the user, and is visible in the Revenue Analysis chart.

Example: Track Event

Datafly.js call:

datafly.track("Feature Activated", {
  feature_name: "dark_mode",
  source: "settings_page"
});

Amplitude HTTP V2 API payload sent by Datafly Signal:

{
  "api_key": "your_amplitude_api_key",
  "events": [
    {
      "event_type": "Feature Activated",
      "user_id": "user-123",
      "device_id": "df_abc123def456",
      "time": 1711296000000,
      "event_properties": {
        "feature_name": "dark_mode",
        "source": "settings_page"
      },
      "user_properties": {},
      "platform": "Web",
      "ip": "203.0.113.42",
      "library": "Datafly Signal"
    }
  ],
  "options": {
    "min_id_length": 5
  }
}

Example: Page View

Amplitude HTTP V2 API payload:

{
  "api_key": "your_amplitude_api_key",
  "events": [
    {
      "event_type": "Page Viewed",
      "user_id": "user-123",
      "device_id": "df_abc123def456",
      "time": 1711296000000,
      "event_properties": {
        "page_url": "https://example.com/products/widgets",
        "page_title": "Widgets | Example Store",
        "page_referrer": "https://www.google.com/"
      },
      "platform": "Web",
      "ip": "203.0.113.42",
      "library": "Datafly Signal"
    }
  ]
}

Custom Events

Any event not in the mapping table is sent to Amplitude with its original name. All event properties are forwarded as Amplitude event_properties.

datafly.track("newsletter_signup", { method: "footer_form" });

{
  "api_key": "your_amplitude_api_key",
  "events": [
    {
      "event_type": "newsletter_signup",
      "device_id": "df_abc123def456",
      "time": 1711296000000,
      "event_properties": {
        "method": "footer_form"
      },
      "platform": "Web",
      "library": "Datafly Signal"
    }
  ]
}

Consent

Default consent category: analytics. Events are suppressed for visitors who have not consented to analytics tracking.

Verify it’s working

1. In the Signal Management UI, open your Amplitude integration and watch the Live Events stream as you trigger events on your site.
2. Confirm 200 responses from the Amplitude endpoint.
3. In Amplitude, open User Look-Up and search by device_id (your anonymous_id value) — events should appear within seconds.

Testing

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

1. Go to the Amplitude dashboard and open User Look-Up (under the Search icon or via the left sidebar).
2. Search by device_id or user_id to find the user profile.
3. Click on the user to see their Event Stream — events should appear in near real-time (typically within seconds).
4. Verify that event properties, user properties, and revenue data are populated correctly.

Debugging

Amplitude Ingestion Debugger

Amplitude provides a built-in ingestion debugger:

1. Go to Settings > Projects > select your project.
2. Click the Ingestion Debugger tab.
3. This shows a real-time feed of events arriving at Amplitude, including any validation errors.

Common Validation Errors

HTTP Response Codes

Rate Limits

Amplitude allows up to 1,000 events per second and 500,000 events per day per project for the HTTP V2 API on the free plan. Growth and Enterprise plans have higher limits.

Dual-tagging with the Amplitude browser SDK

If you already run the Amplitude browser SDK on your site, you can keep it running alongside Signal’s server-side delivery and let Amplitude dedupe the two sources. This is the recommended migration pattern: keep the existing pixel live, deploy Signal in parallel, verify match-rate, then remove the pixel when you’re ready.

Amplitude dedupes on device_id + insert_id within a 7-day window. To make dedup work, three values must match between your browser SDK call and Signal’s server-side event:

1. insert_id — same per logical event

Pick a stable identifier per event (order ID, lead ID, page-view UUID). Pass it as event_id to Signal and as insert_id to the Amplitude SDK:

const eventId = order.id;  // or crypto.randomUUID() for non-transactional events
 
amplitude.track('Order Completed', {
  revenue: 89.99,
  insert_id: eventId,
});
 
datafly.track('Order Completed', {
  total: 89.99,
  currency: 'GBP',
  event_id: eventId,
});

Signal extracts event_id from properties and promotes it to the envelope. The Amplitude default blueprint (v1.2.0+) includes the mapping source: event_id → target: insert_id in its defaults, which routes the resolved value into Amplitude’s dedup field. If you’ve customised your blueprint, confirm this mapping is present in the Mapping tab.

2. device_id — align Amplitude to Datafly’s anonymous_id

By default the Amplitude SDK generates its own device_id and Datafly uses its own anonymous identifier. Set Amplitude’s deviceId to Datafly’s anonymousId so both sources resolve to the same user:

amplitude.init('YOUR_AMPLITUDE_API_KEY', {
  deviceId: datafly.getAnonymousId(),
});

Or, after both SDKs have initialised:

amplitude.setDeviceId(datafly.getAnonymousId());

3. user_id — same on both sides for identified users

datafly.identify('user-123', { email: 'jane@example.com' });
amplitude.setUserId('user-123');

Verifying dedup

1. Trigger a test event from a real browser session.
2. Open Amplitude User Look-Up and search by device_id (the value from datafly.getAnonymousId()).
3. You should see one event for that interaction, not two. If you see two, check that insert_id is identical (string equality), device_id matches, and both events arrived within the 7-day window.

See Cross-Platform Deduplication for the same pattern across other vendors.

Delivery

Events are delivered server-side from your Datafly Signal infrastructure directly to the Amplitude HTTP V2 API.

If you also run the Amplitude browser SDK on your site (dual-tagging), Signal does not load it for you — the customer integrates it directly. Signal’s role is to ensure the server-side events carry the right insert_id / device_id / user_id to dedupe against the browser source. See Dual-tagging with the Amplitude browser SDK above.

Blueprint

The Amplitude blueprint version is 1.2.0 (ga). It ships with Retail, B2B / SaaS, and Media variants covering the GA4-style event taxonomy. The insert_id mapping for dedup against the browser SDK was added in 1.2.0.

See also

• Mixpanel — alternative product analytics destination.
• Heap — autocapture product analytics.
• Cross-Platform Deduplication — run alongside the Amplitude browser SDK without double-counting.