Apple Search Ads

Vendor/Partner	Apple
Version	4.0
API Documentation	https://developer.apple.com/documentation/apple_search_ads Changelog
Sunset Date	None as of July 2024
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
Conversions	NUMBER	conversions	Conversions for the keyword
Tap Through Rate	NUMBER	ttr	Tap Through Rate
Local Spend	NUMBER	localSpend	Spend in the currency of the account. Defaults to USD.