Apple Search Ads API Connector

📌 Overview

The Apple Search Ads connector is designed to automate the ingestion of campaign and ad group level performance data from the Apple Search Ads API.

This integration pulls both data and metadata tables to support in-depth campaign analysis, including performance metrics such as spend, impressions, installs, and download types (new vs. re-downloads).

The data is refreshed on a daily schedule with a 5-day look-back window.

Granularity: Campaign → Ad Group level

Purpose: Track delivery metrics (impressions, spend, installs) and enrich with campaign and ad group metadata for performance analysis and reporting.

Refresh Cadence: Daily

Update Modes: Append (for data), Refresh (for metadata)

For more information on this integration, please follow this link

⚙️ Configuration

Connection Details

Key	Description	Required	Notes
`apple_search_org_id`	Apple Search Ads Organization ID	✅	Must be a valid org ID
`apple_search_client_id`	Apple Ads Client ID (e.g., starts with `SEARCHADS`)	✅	OAuth Client ID
`apple_search_team_id`	Apple Ads Team ID	✅	Associated with the org
`apple_search_key_id`	API Key ID shown in the Apple Search UI	✅	Used for JWT generation
`apple_search_private_key`	Authentication private key (as string)	✅	Used for secure token generation

🛠 Jobs

Job 1: Apple Search Report Import

Job Label: Apple Search Report Import
Job Type: data
Status: Active (1)
Poll Frequency: 24 hours
First Run Hour: 5:00
Lookback: 5 days
Lookback Window: 0

Targets

Table Name	Description	Update Mode	Priority	Create Target
`applesearch_data_campaigns`	Campaign-level data	append	1	true
`applesearch_data_adgroups`	Ad group-level data	append	2	true

Job 2: Apple Search Meta Import

Job Label: Apple Search Meta Import
Job Type: lookup
Status: Active (1)
Poll Frequency: 24 hours
First Run Hour: 5:00
Lookback: 1 day
Lookback Window: 0

Targets

Table Name	Description	Update Mode	Priority
`applesearch_meta_campaigns`	Campaign metadata	refresh	1
`applesearch_meta_adgroups`	Ad group metadata	refresh	2

🏗️ Tables Created

1. `applesearch_data_campaigns`

Description: Campaign-level performance data.

Field Name	Description
`date`	Date of data
`campaignId`	Unique campaign identifier
`app_appName`	Name of the advertised app
`localSpend_amount`	Spend in local currency
`impressions`	Total impressions
`tapInstalls`	Installs resulting from ad taps
`totalInstalls`	Total installs
`tapNewDownloads`	New downloads
`tapRedownloads`	Re-downloads

Update Mode: append
Create Target: true
Primary Date Field: date

2. `applesearch_data_adgroups`

Description: AdGroup-level performance data.

Field Name	Description
`date`	Date of data
`adGroupId`	Unique ad group ID
`campaignId`	Linked campaign ID
`localSpend_amount`	Spend in local currency
`impressions`	Total impressions
`tapInstalls`	Installs from ad taps
`totalInstalls`	Total installs
`tapNewDownloads`	New downloads
`tapRedownloads`	Re-downloads

Update Mode: append
Create Target: true
Primary Date Field: date

3. `applesearch_meta_campaigns`

Description: Metadata for campaigns.

Field Name	Description
`id`	Campaign ID
`name`	Campaign name

Update Mode: refresh
Create Target: false

4. `applesearch_meta_adgroups`

Description: Metadata for ad groups.

Field Name	Description
`id`	Ad group ID
`name`	Ad group name

Update Mode: refresh
Create Target: false

🧠 Dimensions

Name	Field Mapping
`App Name [Apple]`	`applesearch_data_campaigns.app_appName`
`Campaign [Apple]`	`applesearch_meta_campaigns.name`
`AdGroup [Apple]`	`applesearch_meta_adgroups.name`

📊 Base Metrics

Name	Formula
`Spend [Apple]`	`SUM(applesearch_data_campaigns.localSpend_amount) + SUM(adgroups)`
`Impressions [Apple]`	`SUM(applesearch_data_campaigns.impressions) + SUM(adgroups)`
`Tap Installs [Apple]`	`SUM(applesearch_data_campaigns.tapInstalls) + SUM(adgroups)`
`Total Installs [Apple]`	`SUM(applesearch_data_campaigns.totalInstalls) + SUM(adgroups)`
`New Downloads [Apple]`	`SUM(applesearch_data_campaigns.tapNewDownloads) + SUM(adgroups)`
`Re-Downloads [Apple]`	`SUM(applesearch_data_campaigns.tapRedownloads) + SUM(adgroups)`

🧮 Composite Metrics

Name	Formula
`CPM [Apple]`	`(Spend [Apple] / Impressions [Apple]) * 1000`

🔄 Data Sync Schedule

Data Jobs
- Job: Apple Search Report Import
  - Frequency: Every 24h
  - Lookback: 5 days
  - First Run: 05:00 UTC
- Job: Apple Search Meta Import
  - Frequency: Every 24h
  - Lookback: 1 day
  - First Run: 05:00 UTC

🔗 Joins

Join Type	Source Table	Join Key	Target Table	Target Field
Lookup	`applesearch_data` `_adgroups`	`adGroupId`	`applesearch_meta` `_adgroups`	`id`
Lookup	`applesearch_data` `_adgroups`	`campaignId`	`applesearch_meta` `_campaigns`	`id`
Lookup	`applesearch_data` `_campaigns`	`campaignId`	`applesearch_meta` `_campaigns`	`id`

✅ Summary

The Apple Search Ads integration provides full visibility into campaign and ad group performance across a 5-day rolling window. It creates four distinct tables for raw and metadata, supports auto joins for easier reporting, and offers a set of robust KPIs like Spend, Impressions, Installs, and derived metrics like CPM. All metrics are refreshed daily to keep reports up to date with the latest marketing performance data.