Google Ads

Datafly Signal delivers conversion events to Google Ads server-to-server using Enhanced Conversions for Web via the Google Ads API. This improves conversion measurement accuracy by supplementing click-based attribution with hashed first-party data.

API Overview

Enhanced Conversions for Web uses the Google Ads API ConversionUploadService to upload conversions. Unlike tag-based tracking, this approach sends conversion data directly from your server to Google, improving reliability and data quality.

Google Ads API v16 — ConversionUploadService.UploadClickConversions

Configuration

Management UI Setup

1. Go to Integrations > Add Integration > Google Ads.
2. Enter your customer_id and conversion_action_id.
3. Complete the OAuth flow by clicking Connect Google Account or manually enter OAuth credentials.
4. Select consent categories (typically advertising).
5. Click Save.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "google_ads",
    "name": "Google Ads Conversions",
    "enabled": true,
    "config": {
      "customer_id": "1234567890",
      "conversion_action_id": "987654321",
      "oauth_client_id": "your_client_id.apps.googleusercontent.com",
      "oauth_client_secret": "your_client_secret",
      "oauth_refresh_token": "your_refresh_token",
      "developer_token": "your_developer_token"
    },
    "consent_categories": ["advertising"]
  }'

Identity

Google Click ID (gclid)

The primary identity signal for Google Ads conversions is the gclid (Google Click Identifier). When a user clicks a Google ad, the gclid parameter is appended to the landing page URL. Datafly.js automatically captures this value and includes it in all subsequent events.

https://example.com/landing?gclid=Tester123456789

Datafly Signal extracts the gclid from the URL and persists it for the duration of the session (or until a new gclid is received).

Enhanced Conversions (Hashed User Data)

When gclid is not available (e.g. the user arrived via organic search but later converts), Enhanced Conversions uses hashed first-party data to match the conversion to a Google account:

Event Mapping

Only conversion events are sent to Google Ads. Pageviews and other non-conversion events are filtered out.

Example: Purchase Conversion

Datafly.js call:

_df.track("Order Completed", {
  order_id: "ORD-001",
  total: 129.99,
  currency: "USD"
});

Google Ads API payload (simplified):

{
  "conversions": [
    {
      "conversion_action": "customers/1234567890/conversionActions/987654321",
      "conversion_date_time": "2026-01-29 14:30:00+00:00",
      "order_id": "ORD-001",
      "conversion_value": 129.99,
      "currency_code": "USD",
      "gclid": "Tester123456789",
      "user_identifiers": [
        {
          "hashed_email": "836f82db99121b3481011f16b49dfa5fbc714a0d1b1b9f784a1ebbbf5b39577f"
        },
        {
          "hashed_phone_number": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6abcd"
        }
      ]
    }
  ],
  "partial_failure": true
}

Multiple Conversion Actions

If you need to report different event types to different conversion actions, create multiple Google Ads integrations, each with a different conversion_action_id, and use event filters to route the appropriate events:

{
  "vendor": "google_ads",
  "name": "Google Ads - Purchases",
  "config": {
    "customer_id": "1234567890",
    "conversion_action_id": "111111111"
  },
  "event_filter": {
    "event_names": ["Order Completed"]
  }
}

{
  "vendor": "google_ads",
  "name": "Google Ads - Leads",
  "config": {
    "customer_id": "1234567890",
    "conversion_action_id": "222222222"
  },
  "event_filter": {
    "event_names": ["Lead Generated"]
  }
}

Consent Mode

For users in the European Economic Area (EEA), Google requires that consent state be included with conversion uploads. Datafly Signal forwards the consent state from the event’s context.consent object.

{
  "conversions": [
    {
      "consent": {
        "ad_user_data": "GRANTED",
        "ad_personalization": "GRANTED"
      }
    }
  ]
}

Rate Limits

Google Ads API has per-account rate limits. The defaults are conservative; adjust based on your account tier and API quota.