Kntnt Ad Attribution for Google Ads

Add-on plugin for Kntnt Ad Attribution that enables Google Ads offline conversion tracking.

Description

Kntnt Ad Attribution gives you internal, privacy-friendly lead attribution. This add-on extends it with Google Ads integration — capturing the gclid (Google Click Identifier) at ad click time and reporting conversions back to Google Ads via the Offline Conversion Upload API.

The result: you keep the core plugin's internal attribution data and get conversion data in Google Ads, allowing Google's bidding algorithms to optimize for actual leads rather than just clicks.

How It Works

The plugin uses two adapter hooks provided by the core plugin:

1. Click-ID capture (kntnt_ad_attr_click_id_capturers): Registers 'google_ads' => 'gclid'. When a visitor clicks a tracking URL that has a gclid query parameter, the core plugin's Click_Handler captures and stores the value in the kntnt_ad_attr_click_ids table. No custom tables or storage are needed — the core handles everything.

2. Conversion reporting (kntnt_ad_attr_conversion_reporters): Registers enqueue and process callbacks. When a conversion is attributed to a hash that has a stored gclid, a payload is built and queued for asynchronous processing. Each job is deferred by 6 hours from the click capture time (via the core queue's not_before parameter), giving Google Ads time to register the click before accepting the conversion upload. Clicks already older than 6 hours are processed immediately. The queue processor then sends the conversion to the Google Ads Offline Conversion Upload API.

The plugin creates no custom tables, CPTs, cron hooks, or cookies. It registers three REST API endpoints for settings page operations (test connection, create conversion action, fetch conversion action details). It relies on the core plugin's infrastructure for click-ID storage and conversion queuing.

Features

• Automatically captures gclid parameters when visitors arrive via Google Ads tracking URLs.
• Queues and uploads conversions to Google Ads via the Offline Conversion Upload API.
• Deferred upload — each conversion upload is deferred by 6 hours from click capture time, giving Google Ads time to register the click. Clicks older than 6 hours are processed immediately.
• Resilient queuing — conversions are always queued regardless of credential status. Missing credentials are filled in from current settings when the job is processed.
• Failed jobs are automatically reset when settings are updated with valid credentials.
• Test Connection button verifies all credentials — OAuth2 tokens, Customer ID, Developer Token, Login Customer ID, and Conversion Action ID — in a single click. Uses current form values, so you can test before saving.
• Create Conversion Action button creates a new conversion action in Google Ads directly from the settings page. The ID is filled in automatically on success.
• Auto-fetches conversion action name and category from Google Ads when an ID is present.
• Persistent admin notice warns when uploads fail due to missing or invalid credentials.

Settings Page

Navigate to Settings > Google Ads Attribution to configure the plugin. The page has three sections:

API Credentials — required for conversion reporting:

• Manager Account ID (MCC, 10 digits, dashes are stripped automatically)
• Customer ID (10 digits, dashes are stripped automatically)
• Developer Token
• OAuth2 Client ID, Client Secret, and Refresh Token

Conversion Action — configure or create the conversion action:

• Conversion Action ID (numeric)
• Conversion Action Name (auto-fetched from Google Ads when ID is set, or enter a name for a new action)
• Conversion Action Category (auto-fetched from Google Ads when ID is set, or select for a new action)
• Create Conversion Action button — creates a new action in Google Ads. Enabled when auth fields + name are filled and no ID exists. The ID is filled in automatically on success.

Conversion Defaults:

• Default Conversion Value (numeric, >= 0)
• Currency Code (ISO 4217 select dropdown, default: SEK)

Diagnostic logging is handled by the core plugin's shared Logger (configure under Settings > Ad Attribution).

The Test Connection button verifies all credentials using the current form values — you can test before saving. A single Save Changes button at the bottom saves all settings.

Limitations

• Requires the core plugin. This is an add-on — Kntnt Ad Attribution must be installed and active.
• Google Ads API credentials required. Conversion reporting requires a Google Ads Customer ID, Conversion Action ID, OAuth2 credentials, and a Developer Token. Configure these under Settings > Google Ads Attribution.
• Attribution window limited by cookie lifetime. The core plugin's cookie lifetime (default: 90 days) determines the maximum attribution window, even though Google Ads allows up to 90 days for offline conversion uploads.

For Users

Installation

1. Install and activate Kntnt Ad Attribution first.
2. Download the latest release ZIP file.
3. In your WordPress admin panel, go to Plugins → Add New.
4. Click Upload Plugin and select the downloaded ZIP file.
5. Activate the plugin.

The plugin is distributed via GitHub Releases and updated through the standard WordPress plugin update UI. When a new version is available, you will see it on the WordPress Updates page.

If the core plugin is not active when you try to activate this add-on, activation is blocked with a clear error message. While this add-on is active, the core plugin's "Deactivate" link on the Plugins screen is replaced with a "Required by" notice, and bulk deactivation of the core is silently prevented.

System Requirements

The plugin checks the PHP version on activation and aborts with a clear error message if the requirement is not met.

Configuration Guide

After activation, go to Settings > Google Ads Attribution to enter your credentials. The following sections walk you through every step, including creating any accounts you may not already have.

Prerequisites

Using the Google Ads API requires a Google Ads Manager Account (MCC). This is a special account type primarily used by agencies and consultants to manage multiple Google Ads accounts, but it is also required for anyone who needs API access — even if you only manage a single account.

If you don't already have one, you will create it in the steps below. It is free and does not affect your existing Google Ads account.

Step 1: Create a Google Ads Manager Account (MCC)

Skip this step if you already have a manager account.

1. Go to ads.google.com/home/tools/manager-accounts.
2. Sign in with a Google account. Note: If your email is already associated with a regular Google Ads account, you may need to use a different email address.
3. Follow the prompts to create the manager account. Give it a descriptive name (e.g. "Your Company — MCC").
4. Note the 10-digit Manager Account ID shown in the top-right corner (formatted as XXX-XXX-XXXX). You will need it later.
5. Link your existing Google Ads account to the manager account:
   1. In the manager account, go to Admin (gear icon) > Sub-account settings.
   2. Click + and enter the Customer ID of your Google Ads account (the 10-digit number shown in the top-right corner of your Google Ads dashboard).
   3. A link request is sent to the Google Ads account.
6. Accept the link request from the Google Ads account side:
   1. Sign in to ads.google.com with the account that has access to your Google Ads account (verify the correct Customer ID in the top-right corner).
   2. Go to Admin (gear icon) > Access and security.
   3. Click the Managers tab.
   4. Accept the pending request from your manager account.

Why is this needed? The Developer Token (obtained in the next step) belongs to the manager account. API calls use the login-customer-id header to identify the manager account, but this only works if the manager account actually manages the target Google Ads account. Without this link, API calls will fail with USER_PERMISSION_DENIED.

Step 2: Get a Developer Token

1. Sign in to your Manager Account (not your regular Google Ads account).
2. Go to ads.google.com/aw/apicenter. If you see the message "The API Center is only available to manager accounts", you are signed in to the wrong account — switch to the manager account.
3. Fill in the form:
   • API contact email: Your email address.
   • Company name: Your company name.
   • Company website: Your website URL (must be live and reachable).
   • Company type: Choose the option that best describes you (e.g. "Agency/SEM" if you manage ads for clients, or "Advertiser" if you manage your own).
   • Purpose: Describe your intended use. For example: "Offline conversion tracking. We upload lead conversions from our websites to Google Ads via the Offline Conversion Upload API, so that Google's bidding algorithms can optimize for actual leads rather than just clicks."
4. Accept the Terms and Conditions and submit.
5. You will typically receive Explorer Access immediately, which allows up to 2,880 API operations per day — more than sufficient for conversion uploads. You can apply for Basic Access later if needed.
6. Copy the Developer Token (a 22-character alphanumeric string) shown on the API Center page.

Step 3: Get the Conversion Action ID

You can either create a conversion action from the plugin's settings page or manually in Google Ads.

Option A: Create from the plugin settings page (recommended)

1. Complete Steps 1–2 and 4–7 first (you need API credentials).
2. In the plugin's settings page, go to the Conversion Action section.
3. Enter a name (e.g. "Offline Lead") and select a category.
4. Click Create Conversion Action. The ID is filled in automatically.

[!IMPORTANT] After creating a new conversion action, Google Ads requires a ~6 hour waiting period before it accepts conversion uploads. During this time, uploads will fail with "Can't import events to a conversion action that was just created." This is normal — the queue processor will keep retrying automatically, and conversions will be uploaded successfully once the waiting period has passed. No action is needed on your part.

Option B: Create manually in Google Ads

1. In Google Ads, go to Goals > Conversions.
2. If you already have a conversion action of type Import > from clicks (e.g. one used for offline conversion imports from Matomo or another source), you can reuse it. Otherwise, create a new one:
   • Click + New conversion action.
   • Choose Import > Other data sources or CRMs > Track conversions from clicks.
   • Name the action (e.g. "Offline Lead") and save.
3. Open the conversion action. Copy the numeric Conversion Action ID — you can find it in the URL parameter ctId (e.g. ctId=7171477836 → the ID is 7171477836), or in the action details.

If you were previously importing conversions from another system (e.g. Matomo's Conversion Export), you should disable that import to avoid double-counting. The plugin replaces the need for external conversion imports.

Step 4: Set up a Google Cloud Project

A Google Cloud project is needed to create the OAuth2 credentials that authorize the plugin to communicate with the Google Ads API.

1. Go to console.cloud.google.com.
2. In the project selector at the top of the page, create a new project (e.g. "Google Ads Integration") or select an existing one.
3. Go to APIs & Services > Library.
4. Search for Google Ads API, click on it, and click Enable.

Step 5: Configure the OAuth Consent Screen

Before you can create OAuth credentials, Google requires a consent screen configuration.

1. Go to Google Auth Platform > Overview (or navigate via the sidebar: APIs & Services > OAuth consent screen).
2. Click Configure (or Get started if this is a new project).
3. Fill in the required fields:
   • App name: A descriptive name (e.g. "Kntnt Ad Attribution").
   • User support email: Your email address.
   • Audience / User type: Choose External.
   • Developer contact email: Your email address.
4. You can skip all optional fields (logo, homepage, privacy policy, etc.).
5. You can also skip the Scopes step if prompted — scopes are not needed here.
6. Save and continue through all steps.