Apple Search Ads

Promote your app on the App Store via Apple Search Ads and analyze revenue and other metrics segmented by keywords or campaigns in Apphud.

🚧

Attention

Integration is available for iOS 14.3+ devices via AdServices framework.

How to Add Integration?

Step 1

For every app installation, pass the attribution token from the app to Apphud.

🚧

Important Note

Call the code below for every app installation. If you use ATT consent, call the code in ATT callback, and if ATT is not used, in AppDelegate's didFinishLaunching method.

import AdServices

// call in ATT consent callback, or if ATT is not used, in AppDelegate's didFinishLaunching method.
private func trackAppleSearchAds() {
        if #available(iOS 14.3, *) {
            DispatchQueue.global(qos: .default).async {
                if let token = try? AAAttribution.attributionToken() {
                    DispatchQueue.main.async {
                        Apphud.addAttribution(data: nil, from: .appleAdsAttribution, identifer: token, callback: nil)
                    }
                }
            }
        }
   }
#import <AdServices/AdServices.h>

- (void)trackAppleSearchAds {
    if (@available(iOS 14.3, *)) {
        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0), ^{
        NSString *token = [AAAttribution attributionTokenWithError:nil];
        if (token != nil) {
            dispatch_async(dispatch_get_main_queue(), ^{
                [Apphud addAttributionWithData:nil from:ApphudAttributionProviderAppleAdsAttribution identifer:token callback:nil];
            });
        }
        });
    }
}

Step 2

  • At Apphud go to Settings > Search Ads Settings.
  • By default, Apphud generates public-private key pair automatically so you will need just to copy the public key value. However, if you are already using services like Asapty or your own solution, you will need to paste the private key instead. Read here for details.

Step 3

In your Apple Search Ads account go to Settings > User Management page. In order for Apphud to fetch attribution data you need to invite another Apple ID account and grant it API Account Manager access.

📘

Note

For an unknown reason, granting API Account Read Only role doesn't work.
Please grant the Account Manager role as described.

Step 4

  • Log out from your primary Search Ads Account
  • Log in to Apple Search Ads with Apple ID that has API access that you invited from step 3.
  • Go to Settings > API and paste your public key to generate credentials.
  • Copy Client ID, Team ID, and Key ID fields.

Step 5

Go to Apphud Settings > Search Ads Settings and fill in all the fields.
If all is done correctly Access Token field with the Organisations list will show up on the page:

Click Save and you're all set!

View Apple Search Ads Attribution Data in Apphud

Regardless of what of the two methods you use you can view attribution data from Apple Search Ads in Apphud charts or on the user page.

Shared Credentials for Multiple Apps

If you have several Apphud apps that use the same Apple Search Ads account, you will need to use same ASA credentials for every Apphud App.

In this case, you need to generate your own private-public key pair and upload private key and same Apple Search Ads IDs to all of your Apphud Apps. More details below.

Troubleshooting

I enter a valid public key to Apple Search Ads Console but get Invalid Key error

If you believe you did everything right, but still experience an issue with pasting public key to Apple Search Ads setting, try opening the same webpage in the incognito mode or delete caches of your browser. This is a known issue with cache on Apple side.

Generating public-private key pair manually

If nothing works, try generating public-private keys manually in your Terminal as per following documentation. Paste contents of private key to Apphud ASA Settings (find small paste it button, see image below) and contents of public key to ASA Account settings.

I see Undetermined [0123456789] attribution in Charts

Make sure your credentials are accurately set up as per documentation above.

I don't see any attribution data in Charts

Make sure you pass attribution information from within the app. See Step 1 of the documentation.

I am unable to paste the public key copied from Apphud

In this case generate your own public-private key pair on your computer. Please follow these two steps:

Generate Own Private Key

To generate own private key follow these steps:

  • Run in Terminal:
openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem
  • Open generated private-key.pem file in Text Editor and copy its contents.
  • In Apphud go to Apple Search Ads settings page and click small paste it button. See the screenshot below:
  • Open public-key.pem file in Text Editor and copy its contents.
  • In your Apple Search Ads account with API Account Manager role go to settings page and paste contents of public key.
  • Use generated team id, client id and key id values and paste them to Apphud Search Ads settings page.
  • Click Save. If everythings is OK, you will see a Disconnect button and Org ID:
  • For more details regarding generating private key, read Apple documentation.