Apple Search Ads

Vendor/Partner	Apple
Version	5.1
API Documentation	https://developer.apple.com/documentation/apple_search_ads Changelog
Sunset Date	v5 available, v4 sunsets on February 11, 2025
Channel(s)
Refresh Time (CST)	6 am / Real Time
Default backfill	There may be a delay of up to three hours to view the latest data
Alli Data Library

Getting Started

Limitations

This datasource only works with Search Results type campaigns. Today Tab and Search Tab campaign types are not currently supported.

Setting Up (Key & Certificate Authentication)

Apple Search Ads requires a key pair. The Key and PEM files can be found in the Apple Ads settings section here.

Click the Create API Certificate button and fill in the form with read-only access. Admin access is not necessary for Datawarehouse.
After creating the API Certificate, click the download credentials button to download a Certificates.zip.
The file should contain two files, Datawarehouse API.key and Datawarehouse API.pem. Open both files in notepad or textedit and copy the contents to the datawarehouse fields.
The organization id can be found inside of the Apple Search Ads dropdown:

Setting Up (OAuth 2.0 Latest)

Apple Search Ads recently updated their authentication flow from Key & Certificate to OAuth 2.0. With OAuth 2.0, users now authenticate using credentials in exchange for an access token to make authenticated requests to Apple Search Ads API. More Information here.

Inviting Users

Navigate here, Sign in > Advanced, using an administrator account.
Click on name on the top right corner > Settings > User Management.
Click invite users and fill out the relevant information (First Name, Last Name, and Apple ID)
Select the user in the User Detail section and set their User Access Role to an API User.
Click send invite

Datasource setup for user

You need to generate a Public and Private key that has to be uploaded to your Apple Search Ads portal.
1. Generating a Private Key:
  1. Run the following command on your terminal
    CODE
```
openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
```
  2. It should generate a file called
    CODE
```
private-key.pem
```
    To view the file, run this command on your terminal
    cat private-key.pem
    which resembles the following output:
    CODE
```
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIKtnxllRY8nbndBQwT9we4pEULtjpW605iwvzLlKcBq4oAoGCCqGSM49
AwEHoUQDQgAEY58v74eQFyLtu5rtCpeU4NggVSUQSOcHhN744t0gWGc/xXkCSusz
LaZriCQnnqq4Vx+IscLFcrjBj+ulZzKlUQ==
-----END EC PRIVATE KEY-----
```
    Note: Blindly copy the whole string, including ‘-----BEGIN EC PRIVATE KEY-----' and ‘-----END EC PRIVATE KEY-----’. Also, do not change the spacing.
2. Generating a Public Key:
  1. Run the following command on your terminal
    CODE
```
openssl ec -in private-key.pem -pubout -out public-key.pem
```
  2. Should generate a file called
    CODE
```
public-key.pem
```
    To view the file, run the following command in your terminal
    cat public-key.pem
    which resembles the following output:
    CODE
```
-----BEGIN PUBLIC KEY-----
MHcCAQEEIKtnxllRY8nbndBQwT9we4pEULtjpW605iwvzLlKcBq4oAoGCCqGSM49
LaZriCQnnqq4Vx+IscLFcrjBj+ulZzKlUQ==
-----END PUBLIC KEY-----
```
    1. Note: Blindly copy the whole string, including ‘-----BEGIN PUBLIC KEY-----' and ‘-----END PUBLIC KEY-----. Also, do not change the spacing.
Navigate to the Apple Search Ads portal again (here). Log in as an advanced user and navigate to settings by clicking on your name on the top right corner.
Go to Account Settings > API and paste the public key generated in the appropriate field.

Hit Save and several credentials should show up above the public key field. They should resemble this:

CODE

clientId SEARCHADS.aeb3ef5f-0c5a-4f2a-99c8-fca83f25a9
teamId SEARCHADS.hgw3ef3p-0w7a-8a2n-77c8-scv83f25a7
keyId a273d0d3-4d9e-458c-a173-0db8619ca7d7

Finding your Organization ID:
1. In Apple Business Manager, sign in with a user that has the role of Administrator.
2. Select your name at the bottom of the sidebar, select Preferences ,then select Organization Information.
3. Locate your Organization ID.
Use these credentials, along with the private key generated in step 1, to create your Apple Ads Datasource.

NOTE:

keys need to be generated for every unique account
all of the key data needs to be entered into alli, every time any of the parameters change

Define your Data

Dimensions

Name	Type	Table Field Name	Description
Date	STRING	date	Date
Keyword Id	STRING	keywordId	the ID of the keyword or search term
Keyword Text	STRING	keyword
Ad Group Id	STRING	adGroupId
Ad Group Name	STRING	adGroupName
Campaign Id	STRING	campaignId
Campaign Name	STRING	campaignName

Metrics

Name	Type	Table Field Name	Description
Impressions	NUMBER	impressions	Number of impressions a keyword received
Taps	NUMBER	taps	Number of Taps a keyword received
Tap Through Rate	NUMBER	ttr	Tap Through Rate
Local Spend	NUMBER	localSpend	Spend in the currency of the account. Defaults to USD.
Tap Installs	Number	installs	Prior to API v5, this was the Installs field. The total number of new downloads and redownloads from people who tapped your ad within a 30-day attribution window.
View Installs	Number	viewInstalls	The total number of new downloads and redownloads from people who viewed your ad, but didn't tap it, within a 1-day attribution window.
Total Installs	Number	totalInstalls	The total number of tap-through and view-through new downloads and redownloads within the reporting period.
Tap New Downloads	Number	newDownloads	Prior to API v5, this was the New Downloads field. New downloads from people who tapped your ad within a 30-day attribution window.
View New Downloads	Number	viewNewDownloads	New downloads from people who viewed your ad, but didn't tap it, within a 1-day attribution window. The API counts new downloads when someone downloads your app to a device where your app hasn't previously been installed.
Total New Downloads	Number	totalNewDownloads	The total number of tap-through and view-through new downloads within the reporting period
Tap Redownloads	Number	redownloads	Prior to API v5, this was the Redownloads field. Redownloads from people who tapped your ad within a 30-day attribution window.
View Redownloads	Number	viewRedownloads	Redownloads from people who viewed your ad, but didn't tap it, within a 1-day attribution window. The API counts redownloads when someone downloads your app, deletes it, and downloads it again on the same device, or a different one, following an ad view.
Total Redownloads	Number	totalRedownloads	The total number of tap-through and view-through redownloads within the reporting period.
Tap Install Rate	Number	conversionRate	Prior to API v5, this was the Conversion Rate field. The total number of tap-through installs divided by the total number of taps within the reporting period.
Tap Install CPI	Number	avgCPA	Prior to API v5, this was the Average CPA field. The total campaign spend divided by the number of tap-through installs within the reporting period.
Average CPT	Number	avgCPT	The CPT (Cost-Per-Tap) is treated the same as CPC (Cost-Per-Click). The ratio is spend over taps.
Average CPM	Number	avgCPM	The average CPM is the average amount you pay per one thousand ad impressions.
Total Average CPI	Number	totalAvgCPI	The total campaign spend divided by the total number of installs within the reporting period.
Total Install Rate	Number	totalInstallRate	The total number of installs divided by the total number of taps within the reporting period.