> ## 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.

# Google Ads

> Connect Google Ads to Ocular via OAuth — sign in once with an Admin user and Ocular handles account selection, syncs, and token refresh for you.

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.

<CardGroup cols={2}>
  <Card title="What you need" icon="key">
    A Google account with **Admin User** access on the Google Ads account.
  </Card>

  <Card title="What it unlocks" icon="bullhorn">
    Marketing report, Ad & Campaign Performance, search-term and asset performance across Search, Performance Max, Shopping, Display.
  </Card>
</CardGroup>

<Warning>
  **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.
</Warning>

***

## <Icon icon="plug" /> Connect via OAuth

<Steps>
  <Step title="Open the connector form" icon="window">
    In Ocular, go to **Data Management → Connectors → Add Connector**, then choose **Google Ads → Connect with OAuth**.
  </Step>

  <Step title="Sign in with an Admin user" icon="google" iconType="brands">
    Sign in with your Google account that is linked to your Google Ads account as an **Admin User**.

    <Note>
      View-only or standard users won't have permission to grant the scopes Ocular needs. Use an Admin.
    </Note>
  </Step>

  <Step title="Approve the permissions" icon="shield-check">
    Approve the scopes Ocular requests — read access to spend, conversions, search terms, asset performance, and conversion actions.
  </Step>

  <Step title="Ocular stores your tokens" icon="lock">
    Ocular securely stores your refresh token and developer token.
  </Step>

  <Step title="Create the connector" icon="circle-check">
    You will be redirected to the connector page where you can see the **YOUR GOOGLE ADS ACCOUNT IS CONNECTED** message. Click **Create**.

    That's it — your Google Ads account is linked, and you can immediately start syncing data.
  </Step>
</Steps>

***

## <Icon icon="layer-group" /> Breakdowns Ocular ingests

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

<CardGroup cols={2}>
  <Card title="Age" icon="user-clock">
    `google_ads_age` — age\_range dimension.
  </Card>

  <Card title="Gender" icon="venus-mars">
    `google_ads_gender_datamodel`.
  </Card>

  <Card title="Device" icon="mobile">
    Device and ad\_network\_type.
  </Card>

  <Card title="Geo" icon="location-dot">
    City, most-specific location, location type.
  </Card>

  <Card title="Placement" icon="grip">
    Placement type, URL, display name.
  </Card>

  <Card title="Search Term" icon="magnifying-glass">
    Search term, status, match type.
  </Card>

  <Card title="Conversion Action" icon="bullseye">
    Ad-level conversion actions.
  </Card>
</CardGroup>

**Metrics on every breakdown:** Ad Spend, Conversion Value, ROAS, Conversions, Clicks, Impressions, CTR.

***

## <Icon icon="life-ring" /> Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth succeeds but no data appears" icon="triangle-exclamation">
    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.
  </Accordion>

  <Accordion title="Conversions don't match Google Ads UI" icon="chart-line">
    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.
  </Accordion>

  <Accordion title="Manager (MCC) account vs sub-account" icon="sitemap">
    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.
  </Accordion>
</AccordionGroup>

<Note>
  For ticket-writing format when filing a connector issue, see [Working with the Ocular team → Connector-not-working tickets](/overview/working-with-the-ocular-team).
</Note>