Vendor IDs

Datafly.js collects and generates vendor-compatible identifiers so that server-side event delivery maintains the same user matching quality as client-side vendor pixels. This is a key feature that enables Datafly to replace vendor tags without losing attribution accuracy.

How vendor IDs work

When a user first visits your site, Datafly.js:

1. Captures click IDs from the URL query parameters (e.g., gclid from a Google Ads click)
2. Reads existing vendor cookies if present (e.g., _ga from a previous Google Analytics installation)
3. Self-generates vendor IDs in the correct format where the vendor’s own cookie is not present
4. Sends all IDs with the first event to the Ingestion Gateway
5. The server stores IDs in Redis and sets them as server-side cookies via Set-Cookie headers

On subsequent visits, vendor IDs are recovered from the server-set cookies, which are first-party and ITP-exempt.

Self-generated IDs

Datafly.js generates vendor-compatible identifiers locally when the vendor’s own cookie is not already present. These IDs use the exact same format as the vendor would generate, so they are accepted by vendor APIs.

How self-generation works

Each vendor’s ID format is publicly documented. Datafly.js replicates the exact format:

// Meta _fbp format: fb.{subdomainIndex}.{creationTime}.{random10Digits}
// Example: fb.1.1709312400000.1234567890
 
// GA4 client_id: extracted from _ga cookie
// Format: GA1.2.{randomPart1}.{randomPart2}
 
// TikTok _ttp: standard UUID v4
// Example: 550e8400-e29b-41d4-a716-446655440000

These IDs are sent to the server on the first event and stored in Redis. The Ingestion Gateway sets them back as first-party cookies via Set-Cookie headers on the response, ensuring they persist across sessions with full first-party cookie lifetime.

Click ID capture

When a user arrives at your site from a paid ad, the ad platform appends a click ID to the URL. Datafly.js automatically extracts these on first visit:

Click IDs are critical for conversion attribution. They link a specific ad click to subsequent conversion events, enabling accurate ROAS reporting.

Click ID lifecycle

1. User clicks ad on Google
   └─> Lands on: example.com/?gclid=EAIaIQobChMI...

2. Datafly.js extracts gclid from URL parameters

3. gclid is sent with the first event to Ingestion Gateway

4. Server stores gclid in Redis (keyed by anonymous_id)
   └─> Also set as first-party cookie via Set-Cookie header

5. User later completes a purchase
   └─> _df.track('Order Completed', { revenue: 99.99 })

6. Delivery Worker retrieves stored gclid for this user
   └─> Sends to Google Ads API with the conversion event

7. Google Ads matches the conversion to the original click

Server-proxied enrichment

For vendors that require authenticated API access to resolve identity data, Datafly supports server-proxied enrichment. These calls happen server-side, not in the browser:

Server-proxied enrichment is configured per source in the management UI under Sources > Identity Enrichment. The credentials are stored securely and never exposed to the browser.

Storage

Vendor IDs are stored in multiple layers for resilience:

The server-set cookie is the authoritative source. When Datafly.js loads, it first checks for the server-set cookie. If found, it uses that value. If not, it falls back to localStorage, and if that is also empty, it self-generates a new ID.

Per-source vendor modules

Not every site needs IDs for every vendor. In the management UI, you configure which vendors each source delivers to. Custom builds of Datafly.js only include the ID generation modules for the selected vendors.

For example, if a source only sends data to GA4 and Meta:

• Included: GA4 client_id parsing, Meta fbp/fbc generation, gclid and fbclid capture
• Excluded: TikTok ttp, Pinterest _pin_unauth, Snapchat _scid, ttclid, epik, ScCid

This reduces the script size and the number of cookies set on the domain.

Vendor IDs in the event payload

Vendor IDs are attached to the first event’s context.vendor_ids field:

{
  "type": "page",
  "context": {
    "vendor_ids": {
      "ga_client_id": "1234567890.1709312400",
      "fbp": "fb.1.1709312400000.1234567890",
      "gclid": "EAIaIQobChMI...",
      "fbclid": "IwAR3..."
    }
  }
}

After the first event, vendor IDs are stored server-side and are not re-sent with every event. The server retrieves them from Redis when preparing events for vendor delivery.