Your First Pipeline

This guide walks you through creating a pipeline, installing your first integration, and adding the Datafly.js collector to your website. By the end, you’ll have events flowing from your site through to a vendor destination.

Step 1: Create a Pipeline

1. Navigate to Pipelines in the sidebar.
2. Click Create Pipeline.
3. Fill in the details:
   • Name — a descriptive name like “My Website” or “shop.example.com”
   • Domain — the domain where you’ll collect events (e.g. shop.example.com)
4. Click Create.

Signal generates a pipeline key (dk_...) for this pipeline. You’ll use this key to configure the JS collector on your site. You can find it in the pipeline’s settings at any time.

Pipeline Parameters

Pipelines support parameters — shared values that are injected into integration configurations at processing time. For example, a GA4 integration needs a measurement_id and api_secret. Rather than hardcoding these in the integration config, you set them as pipeline parameters so they can be managed in one place.

You’ll add parameters in the next step when you install an integration.

Step 2: Install an Integration

Now add a vendor destination to your pipeline. We’ll use Google Analytics 4 as an example, but the process is the same for any vendor.

1. From your pipeline’s page, click Add Integration (or navigate to Integrations in the sidebar).
2. You’ll see the Integration Library — a catalog of 150+ pre-built vendors. Search for “Google Analytics 4” or browse the Analytics category.
3. Click Install on the GA4 card.
4. Configure the integration:
   • Name — e.g. “GA4 Production”
   • Blueprint — select the Retail blueprint (or whichever matches your site) for pre-built event mappings, or choose None to build from scratch
   • Credentials — enter your GA4 measurement_id and api_secret
5. Click Install Integration.

The integration is now attached to your pipeline. If you selected a blueprint, it comes pre-configured with common event mappings (page_view, purchase, add_to_cart, etc.). You can customise these at any time.

Understanding the Integration Config

After installing, click on the integration to open the V2 schema-mapping builder. Here you’ll see:

• Parameters — Connection credentials like measurement_id and api_secret
• Global — Fields sent with every event (e.g. client_id mapped from the anonymous ID)
• Events — Per-event-type mappings (e.g. purchase maps transaction_id, value, currency, and items[])
• Defaults — Fallback values for when source data is missing

If you used a blueprint, all of this is pre-configured. If not, see Adding Integrations for how to set up mappings from scratch.

Step 3: Add Datafly.js to Your Website

With the pipeline and integration configured, add the collector script to your website.

Get the Snippet

From your pipeline’s Collector tab in the Management UI, copy the install snippet. The JS Builder bakes your pipeline key, endpoint, consent provider config and any vendor identity syncs into the script body, so the install itself is a single async tag — no inline bootstrap or .load() call needed:

<script src="https://data.yourdomain.com/df_your_pipeline.js" async></script>

Replace the src URL with the one shown in the Collector tab — it includes the script filename you chose in the JS Builder (defaults to df_<pipeline_name>.js).

The script auto-initialises and fires the first page() event on load. You can change the script filename, JS namespace (defaults to datafly) and auto-page-tracking mode in the JS Builder before downloading.

Add Tracking Calls

Add tracking calls to your pages:

// Track a page view (call on every page)
datafly.page();
 
// Track a custom event
datafly.track("Purchase", {
  transaction_id: "TXN-123",
  value: 149.99,
  currency: "GBP",
  items: [
    { item_id: "SKU-001", item_name: "Blue Widget", price: 49.99, quantity: 2 },
    { item_id: "SKU-002", item_name: "Red Widget", price: 50.01, quantity: 1 }
  ]
});
 
// Identify a user (call when they log in or you know who they are)
datafly.identify("user-123", {
  email: "jane@example.com",
  name: "Jane Smith"
});

Step 4: Verify Events Are Flowing

1. Open your website with the Datafly.js snippet installed.
2. In the Management UI, open the Real-time Debugger from the sidebar.
3. You should see events appearing in real time as you browse your site.

The debugger shows each event as it passes through the processing pipeline, including:

• The raw event as received by Signal
• The enriched event after organisation-level processing
• The transformed event as sent to each integration

If events aren’t appearing, check:

• The pipeline key in your snippet matches the one in the Management UI
• The endpoint URL is correct and reachable
• The browser’s developer console (Network tab) shows successful POST requests to the endpoint

What’s Next?

• Adding Integrations — Add more vendor destinations and learn how to customise field mappings.
• Going Live — Set up your production domain and go live with real traffic.
• Datafly.js SDK — Full reference for all collector methods and configuration options.
• Processing — Deep dive into the organisation processing and per-vendor transformation.