LaunchDarkly

Datafly Signal delivers your server-side events to LaunchDarkly as custom metric events using the metric event import API. This lets conversions, sign-ups, and revenue tracked through Signal power your LaunchDarkly experiments and feature-flag metrics without instrumenting the LaunchDarkly SDK on your servers.

Each Signal event becomes a LaunchDarkly custom event. The event key must match a metric you have already created in LaunchDarkly, and the canonical visitor identifier is sent as the LaunchDarkly user context key so experiment attribution lines up with your flag evaluations.

Why route LaunchDarkly through Datafly Signal

• Profiles are updated from the server, not the browser. Events reach LaunchDarkly even when a tracker blocker or a failed page unload would have dropped a client-side call, so the profile reflects what actually happened.
• One consent decision governs every destination. LaunchDarkly is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

Prerequisites

• A LaunchDarkly account with Experimentation and at least one custom metric created.
• A personal or service access token with the importEventData permission. Create one under Account settings > Authorization.
• Your LaunchDarkly project key and environment key (for example default and production).
• One or more custom metrics whose event keys match the events you intend to send (for example order_completed, sign_up, page_view). Events whose key has no matching metric are accepted but not counted.

Configuration

Configure in Signal

1. In Signal, open Integrations and add LaunchDarkly.
2. Paste your access token and enter the project key and environment key.
3. Set Events Host: events.launchdarkly.com, or the EU or US federal host if your account is there.
4. Attach the integration to a pipeline and select the Default preset.
5. Confirm that the event keys in the preset (order_completed, sign_up, page_view, and the funnel events) match the metric event keys in LaunchDarkly. Rename them in the blueprint editor if your metrics use different keys.
6. Save and enable the pipeline.

API Endpoint

Signal sends a POST request to the server-side metric event import endpoint:

POST https://events.launchdarkly.com/v2/event-data-import/{project_key}/{environment_key}

Required headers:

The request body is a JSON array of custom events. Signal batches events into a single array per request (the body must stay under 10 MB). A successful import returns 202 Accepted.

Identity Signals

LaunchDarkly attributes experiment events using the context key. Signal maps the canonical identifier to contextKeys.user:

• user_id is used when the visitor is identified.
• anonymous_id is used otherwise.

For experiment results to line up, this context key must be the same key your LaunchDarkly SDK uses when it evaluates flags for the user. If your SDK uses a different context kind or key, edit the mapping in the blueprint editor so the keys match.

Event Mapping

The Default preset maps Signal’s canonical events to LaunchDarkly custom event keys; the SaaS preset covers the subscription funnel. Each event key must match the event key of a metric in LaunchDarkly.

A Datafly.js call:

datafly.track("purchase", {
  transaction_id: "ORD-1001",
  value: 279.98,
  currency: "gbp",
  items: [{ item_id: "SKU-1", price: 129.99, quantity: 2 }, { item_id: "SKU-2", price: 20, quantity: 1 }]
});

is delivered as (one element per event; events are batched into one array per request):

[
  {
    "kind": "custom",
    "key": "order_completed",
    "creationDate": 1758500000123,
    "contextKeys": { "user": "crm-user-7" },
    "metricValue": 279.98,
    "data": { "transaction_id": "ORD-1001", "currency": "GBP" }
  }
]

For numeric metrics, metricValue carries the value or revenue. Conversion metrics ignore metricValue and count the event. No personal data is sent.

Testing

1. Create a custom metric in LaunchDarkly whose event key matches one you are sending (for example order_completed).
2. Attach that metric to a running experiment iteration, and make sure the test context has already encountered the experiment.
3. Fire the matching event through your site or app.
4. In Signal’s Event Debugger, confirm the request to events.launchdarkly.com/v2/event-data-import/... returned 202 Accepted.
5. In LaunchDarkly, open the experiment’s results. Counted events appear after the next results refresh; they are only counted while the experiment iteration is running.

Troubleshooting

• 401 or 403 — the access token is invalid or lacks the importEventData permission. Issue a new token with that permission.
• 404 — the project key or environment key in the path is wrong. Check them under Account settings.
• 400 — malformed payload or an event whose kind is not custom. Re-check the blueprint mappings.
• 202 but no results in LaunchDarkly — the event key does not match any metric, the context never encountered the experiment, or the creationDate falls outside the running iteration window. Events outside the iteration window are silently discarded.
• Wrong cell — EU or US-federal accounts must set Events Host to events.eu.launchdarkly.com or events.launchdarkly.us; sending to the default US host returns 404 or is dropped.