> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to connect

> How to connect the Google Analytics 4 data source to Adriel: authorize a Google account, select accounts and properties, and pick reporting fields.

Google Analytics 4 (GA4) is the current generation of Google's web and app analytics platform, built on an event-based data model that records user interactions — page views, scrolls, clicks, purchases — as events. Connecting it brings acquisition, engagement, conversion, revenue, and audience data into Adriel dashboards, including any custom breakdowns and custom metrics defined in the property.

## Before you connect

The following are required:

* A Google Analytics 4 account.
* A Google account with at least the **Viewer** role on the target GA4 property. Editor or Admin also work.
* The GA4 property identifier, visible under **Admin** then **Property Settings** then **Property ID**, formatted as `123456789`.
* Any custom breakdowns or custom metrics already defined in the GA4 property. No separate configuration is needed for them to appear.

## Connect Google Analytics 4

<Steps>
  <Step title="Authorize a Google account">
    On the **Data Sources** page, search for **Google Analytics 4** and select it. Click **Sign in with Google** in the pop-up, then click **Continue** to allow access. The connector requests only the read-only `analytics.readonly` scope.
  </Step>

  <Step title="Select accounts and properties">
    On the data source settings, choose the **Accounts** and **Properties** to connect. Each selected property becomes its own data source — connecting three properties creates three data sources. Confirm the currency code surfaced from the property at connection time.
  </Step>

  <Step title="Choose reporting fields and submit">
    Select the engagement, conversion, revenue, and breakdown fields required for reporting, then click **Submit**. Custom breakdowns and metrics defined in GA4 appear once the property metadata cache refreshes. Initial data availability can take up to one business day.
  </Step>
</Steps>

## What gets imported

The connector reads from the Google Analytics Data API for reporting queries and the Google Analytics Admin API for account, property, and metadata discovery. Imported data covers acquisition (source, medium, campaign, default channel grouping), engagement (sessions, users, page views, engagement rate), conversions, revenue and e-commerce, audience demographics, device, geography, and any custom breakdowns or metrics defined in the property.

For the complete list of metrics, breakdowns, and limits, see the [Google Analytics 4 data reference](/data-sources/g-n/google-analytics-4/data-reference).

## Troubleshooting

<AccordionGroup>
  <Accordion title="A sampling warning appears on reports">
    GA4 samples data when a query covers a wide date range, many breakdowns, or a high-traffic property. The `GA_SAMPLED_DATA` warning includes the sampling percentage. Narrow the date range or reduce the number of breakdowns to lower the chance of sampling. The GA4 BigQuery export can be used for unsampled event-level analysis.
  </Accordion>

  <Accordion title="A row-limit warning appears on reports">
    A single GA4 report request can return at most 100,000 rows. When the result would exceed that cap, a `GA_ROW_LIMIT` warning is surfaced. Apply tighter filters or higher-level aggregations (for example, country rather than city) to see the full result set.
  </Accordion>

  <Accordion title="Newly created custom breakdowns or metrics do not appear in the field picker">
    Property metadata is cached for up to 12 hours. New custom breakdowns and metrics defined in GA4 appear after the next metadata cache refresh.
  </Accordion>

  <Accordion title="Authentication returns INVALID_CREDENTIALS">
    The Google OAuth refresh token was revoked or invalidated — typically after a password change, account removal, or revocation in Google account permissions. Reconnect using a Google account that retains Viewer access to the property.
  </Accordion>

  <Accordion title="Cohort breakdowns and metrics are unavailable">
    Cohort fields are filtered out of the available-fields list. Cohort analysis is not supported through this connector.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Google Analytics 4 data reference" href="/data-sources/g-n/google-analytics-4/data-reference">
    Metrics, breakdowns, and limits for Google Analytics 4.
  </Card>

  <Card title="Google Analytics 4 FAQs" href="/data-sources/g-n/google-analytics-4/faqs">
    Common questions and expected behaviors for the Google Analytics 4 data source.
  </Card>

  <Card title="How to connect Google Ads" href="/data-sources/g-n/google-ads/how-to-connect">
    Join GA4 outcomes with paid-search spend.
  </Card>

  <Card title="How to connect Google BigQuery" href="/data-sources/g-n/google-bigquery/how-to-connect">
    Event-level analysis from the GA4 BigQuery export.
  </Card>
</CardGroup>