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 120+ 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 settings in the Management UI, copy the installation snippet. It looks like this (replace YOUR_PIPELINE_KEY with your actual pipeline key):

<script>
  !function(){var d=window._df=window._df||[];if(!d.initialize){
  d.methods=["page","track","identify","group","reset"];
  d.factory=function(m){return function(){var a=Array.prototype.slice.call(arguments);
  a.unshift(m);d.push(a);return d}};
  for(var i=0;i<d.methods.length;i++){var m=d.methods[i];d[m]=d.factory(m)}
  d.load=function(k,o){d._pipelineKey=k;d._options=o||{};
  var s=document.createElement("script");s.type="text/javascript";s.async=true;
  s.src=d._options.endpoint?d._options.endpoint+"/d.js":"http://localhost:8080/d.js";
  var f=document.getElementsByTagName("script")[0];f.parentNode.insertBefore(s,f)};
  d.initialize=true}}();
 
  _df.load("YOUR_PIPELINE_KEY", {
    endpoint: "https://data.yourdomain.com"
  });
</script>

Add Tracking Calls

Add tracking calls to your pages:

// Track a page view (call on every page)
_df.page();
 
// Track a custom event
_df.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)
_df.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 the Ingestion Gateway
• The enriched event after the Org Data Layer
• 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 Org Data Layer and Pipeline Transformation Engine.