Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ocular.dev/llms.txt

Use this file to discover all available pages before exploring further.

Ocular connects to Google Ads using OAuth. Most of the flow is automated — sign in once with a Google account that has Admin User access on the Google Ads account, and Ocular handles refresh and developer tokens securely.

What you need

A Google account with Admin User access on the Google Ads account.

What it unlocks

Marketing report, Ad & Campaign Performance, search-term and asset performance across Search, Performance Max, Shopping, Display.
Set up ad tracking first. Final URL Suffix and gclid auto-tagging must be configured at the account level before Ocular starts ingesting. Walk through the Ad Tracking Setup Guide before continuing here.
Google Ads connector placeholder

​
Connect via OAuth

Open the connector form

In Ocular, go to Data Management → Connectors → Add Connector, then choose Google Ads → Connect with OAuth.

Sign in with an Admin user

Use the Google account linked to your Google Ads account’s Admin User.
View-only or standard users won’t have permission to grant the scopes Ocular needs. Use an Admin.

Approve the permissions

Approve the scopes Ocular requests — read access to spend, conversions, search terms, asset performance, and conversion actions.

Save and create

Ocular securely stores your refresh token and developer token. You’ll be redirected back with a YOUR GOOGLE ADS ACCOUNT IS CONNECTED confirmation. Click Create.That’s it — the account is linked and syncing begins immediately.
Google Ads OAuth placeholder

​
Breakdowns Ocular ingests

Google Ads produces 7 breakdown data models, each keyed to date × account × campaign × adset × ad × breakdown_dimension.

Age

google_ads_age — age_range dimension.

Gender

google_ads_gender_datamodel.

Device

Device and ad_network_type.

Geo

City, most-specific location, location type.

Placement

Placement type, URL, display name.

Search Term

Search term, status, match type.

Conversion Action

Ad-level conversion actions.
Metrics on every breakdown: Ad Spend, Conversion Value, ROAS, Conversions, Clicks, Impressions, CTR.

​
Troubleshooting

Confirm the signed-in account is Admin User on the Google Ads account, not just a member of the linked Google Workspace. Re-run OAuth with the right account if needed.
The most common cause is that Final URL Suffix or gclid auto-tagging was not configured before the campaign launched. Retroactive backfill of tagging data isn’t possible — fix the configuration and Ocular will pick up new conversions from that point forward.
Connect at the client (sub-account) level, not the MCC. If you only have MCC access, ask the account owner to grant Admin on the specific sub-account you want to ingest.
For ticket-writing format when filing a connector issue, see Working with the Ocular team → Connector-not-working tickets.