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
| Component | Type | Technical 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:
- Open your client workspace in the dashboard and navigate to Workspace Settings → Integrations.
- Click Connect Google Ads. You will be redirected to Google's OAuth consent screen.
- Grant offline access. Upon return, PaceCast queries accessible accounts and prompts you to select your 10-digit Customer ID.
- 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:
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_requiredwithout 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 Metric | Type | Normalized 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. |