Amplitude

Server-side event tracking to Amplitude via the HTTP V2 API for product analytics, user behavior, 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 _df.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 _df.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:

User Properties

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

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

This sets the following user properties in Amplitude:

{
  "user_properties": {
    "$set": {
      "email": "[email protected]",
      "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:

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

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

_df.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"
    }
  ]
}

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.

Delivery

Events are delivered server-side from your Datafly Signal infrastructure directly to the Amplitude HTTP V2 API. No client-side Amplitude scripts are loaded for this integration.