> ## 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 Apple Search Ads data source to Adriel: register the account, complete the pending Apple Developer credentials step, and add each sub-account.

Apple Search Ads is Apple's advertising platform for iOS apps, placing ads in App Store search results and the Today, Product, and Search tabs across iPhone and iPad. Connecting it brings App Store campaign performance into Adriel dashboards, with conversions tracked as app installs (new downloads and redownloads).

Setup follows a two-phase flow because Apple's API uses a JWT-signed client-credentials OAuth2 flow rather than a browser-based authorization redirect. After the initial account registration, the connection enters a pending state until Apple Developer credentials are supplied, at which point server-side certificate signing activates it.

## Before you connect

The following are required:

* An Apple Search Ads account in good standing.
* The **Account ID** and **Account Name** from the Apple Search Ads dashboard. Open the dropdown at the upper right of the screen to find both values.
* The **Sub Account ID** for each sub-account to connect (the 7-digit number shown under the upper-left dropdown).
* Access to the **Apple Developer Console** to generate API credentials.
* A **Search Ads API certificate** (private key) generated through the Apple Developer portal.
* The associated **Client ID**, **Team ID**, and **Key ID** values.

## Connect Apple Search Ads

<Steps>
  <Step title="Register the Apple Search Ads account">
    On the **Data Sources** page, search for **Apple Search Ads** and select it. Enter the **Account ID** and **Account Name** gathered beforehand, then click **Submit**. The connection is created in a pending state at this point.
  </Step>

  <Step title="Supply the Apple Developer credentials">
    When prompted, provide the **Client ID**, **Team ID**, and **Key ID** generated in the Apple Developer Console. These values are used server-side to sign the JWT and obtain an access token, which activates the connection.
  </Step>

  <Step title="Configure the sub-account">
    Enter the **Sub Account ID** gathered beforehand and an identifiable **Sub Account Name** for the data source. Only one Sub Account ID can be added at a time — repeat this step for each additional sub-account.
  </Step>

  <Step title="Submit">
    Click **Submit** to complete the connection. Initial data availability can take up to one business day.
  </Step>
</Steps>

## What gets imported

The connector imports the full campaign hierarchy — ad account, campaign, ad group, ad, and keyword — with App Store-specific breakdowns including country/region, device class (iPhone versus iPad), and search match type (exact, broad, search-match). Performance metrics cover impressions, taps, tap-through rate, CPT, CPM, installs, new downloads, redownloads, conversion rate, and average CPA. Apple Search Ads reports in **taps** rather than clicks; the standardized Clicks metric is mapped from Apple's taps field for consistency with other ad connectors.

For the complete list of metrics, breakdowns, and refresh cadence, see the [Apple Search Ads data reference](/data-sources/a-f/apple-search-ads/data-reference).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection stuck in a pending state">
    A pending state after the first phase is expected — the connection waits for the Client ID, Team ID, and Key ID before activation. Complete the pending form with the credentials generated in the Apple Developer Console. If the form was already submitted, verify the credentials were entered correctly and regenerate them if needed.
  </Accordion>

  <Accordion title="Tap counts differ from the Apple Search Ads UI">
    The Clicks metric in dashboards is mapped directly from Apple's taps field, so the numbers should match. Discrepancies usually indicate a different date range or timezone setting between the two views.
  </Accordion>

  <Accordion title="Keyword data is not appearing">
    Keyword-level reporting applies only to Search campaigns. Today, Product, and Search-tab placement campaigns do not produce keyword data.
  </Accordion>

  <Accordion title="Connection returns to pending after working">
    Apple can invalidate the signing certificate without notice, which returns the connection to a pending state with a PENDING error. Regenerate the certificate and key in the Apple Developer Console, then re-supply the credentials.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Apple Search Ads data reference" href="/data-sources/a-f/apple-search-ads/data-reference">
    Metrics, breakdowns, and refresh cadence for Apple Search Ads.
  </Card>

  <Card title="Apple Search Ads FAQs" href="/data-sources/a-f/apple-search-ads/faqs">
    Common questions and expected behaviors for the Apple Search Ads data source.
  </Card>

  <Card title="How to connect AppsFlyer" href="/data-sources/a-f/appsflyer/how-to-connect">
    Connect AppsFlyer mobile attribution data.
  </Card>

  <Card title="How to connect Adjust" href="/data-sources/a-f/adjust/how-to-connect">
    Connect Adjust mobile measurement data.
  </Card>
</CardGroup>