Google Ads Integration

OAuth 2.0

Direct programmatic synchronization with the Google Ads API. Secure OAuth 2.0 authentication, encrypted token storage at rest, and background daily metric ingestion.

Last updated: October 2026

PaceCast provides direct integration with Google Ads, eliminating the need to manually export and upload CSV files each week. Once linked, our background synchronization worker fetches daily campaign performance, normalizes currency units, and updates your workspace data pipelines automatically.

Integration Architecture

ComponentTypeTechnical Responsibility
OAuth Handshakerequired
/api/google-ads/connect
Initiates Google OAuth 2.0 consent with offline access scope ('adwords') to receive refresh tokens.
Account Linkingrequired
/api/google-ads/link
Associates a verified 10-digit Google Ads Customer ID (XXX-XXX-XXXX) with the target client workspace.
Sync Workerrequired
Background Ingestion
Executes chunked historical pulls (90–365 days) and ongoing daily sync jobs, enforcing rate limits and automatic token refresh.

OAuth 2.0 Connection & Account Linking

To connect a Google Ads account:

  1. Open your client workspace in the dashboard and navigate to Workspace Settings → Integrations.
  2. Click Connect Google Ads. You will be redirected to Google's OAuth consent screen.
  3. Grant offline access. Upon return, PaceCast queries accessible accounts and prompts you to select your 10-digit Customer ID.
  4. Click Link Account. The initial 90-day synchronization job is queued immediately.

AES-256-GCM Token Encryption

Google Ads refresh tokens grant long-lived API access. PaceCast never stores plain-text tokens in database columns. Every refresh token is encrypted at rest using authenticated AES-256-GCM:

src/lib/google-ads/crypto.ts (Simplified)
import crypto from "crypto"

export function encryptToken(token: string, secretKey: Buffer): string {
  const iv = crypto.randomBytes(12) // 96-bit IV
  const cipher = crypto.createCipheriv("aes-256-gcm", secretKey, iv)
  
  const encrypted = Buffer.concat([cipher.update(token, "utf8"), cipher.final()])
  const authTag = cipher.getAuthTag() // 128-bit authentication tag

  // Store format: iv:authTag:encryptedPayload
  return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted.toString("hex")}`
}

During decryption, if the authentication tag or ciphertext is tampered with, the cipher fails immediately and invalidates the session.

Background Sync Worker Mechanics

Synchronization jobs are processed in chunked daily intervals to avoid memory exhaustion and Google Ads rate limit thresholds:

  • Token Refresh:Ephemeral access tokens are refreshed using Google's token endpoint when within 5 minutes of expiration.
  • Failure Handling: If a user revokes access inside their Google Account settings, the connection is safely transitioned to reauth_required without corrupting historical records.
  • 7-Day Lag Trimming: Ingested Google conversion counts from the trailing 7 days are marked as pending attribution maturation.

Google Ads Metric Field Normalization

Google Ads API MetricTypeNormalized PaceCast Field
metrics.cost_microsrequired
int64 / 1,000,000
Micro-units converted to standard decimal float currency: spend = cost_micros / 1e6.
metrics.impressionsrequired
integer
Direct integer mapping to 'impressions'.
metrics.clicksrequired
integer
Direct integer mapping to 'clicks'.
metrics.conversionsrequired
float
Mapped to primary conversion count. Fractional conversions from data-driven attribution are preserved.
metrics.conversions_valueoptional
float
Mapped to 'conversion_value' for blended ROAS calculations.