Apple Search Ads

The Apple Search Ads (ASA) integration lets you attribute installs, subscriptions, and revenue to ASA campaigns and keywords, segmented across the Apphud Attribution dimensions (Ad Network, Campaign, Ad Set, Keyword, etc.).

Available for iOS 14.3+ devices via Apple's AdServices framework. Works without IDFA and without SKAdNetwork setup.

How it works

ASA attribution uses two independent Apple APIs. Understanding the split explains why some setup steps are required for some scenarios but not others.

Token resolution — no credentials required

Your app collects an attribution token via Apple's AdServices framework and sends it to Apphud via the SDK. Apphud forwards the token to Apple's Attribution API (api-adservices.apple.com) which returns:

• attribution (true = non-organic, false = organic)
• campaignId, adGroupId, keywordId, creativeSetId
• conversionType, clickDate, orgId, countryOrRegion

This works as soon as the SDK starts sending tokens — no ASA credentials needed. Users get tagged as non-organic with the right numeric IDs.

Name resolution — credentials required

To turn the numeric IDs into human-readable names (campaign name, ad group name, keyword text, creative set name), Apphud calls Apple's Campaign Management API (api.searchads.apple.com) using OAuth credentials you set up below. Without credentials, names appear as Unknown [<id>] but the numeric IDs and conversion data are still there.

How to add integration

Step 1 — Pass the attribution token from your app

Call the attribution method after Apphud SDK initialization for every iOS install. If your app uses ATT consent, call it inside the ATT callback; otherwise, call it from AppDelegate.didFinishLaunching.

import AdServices

func trackAppleSearchAds() {
    if #available(iOS 14.3, *) {
        Task {
            if let asaToken = try? AAAttribution.attributionToken() {
                Apphud.setAttribution(data: nil, from: .appleAdsAttribution, identifer: asaToken, 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];
                });
            }
        });
    }
}

// There is no direct React Native method yet; call native Swift code:

if #available(iOS 14.3, *) {
    Task {
        if let asaToken = try? AAAttribution.attributionToken() {
            Apphud.addAttribution(data: nil, from: .appleAdsAttribution, identifer: asaToken, callback: nil)
        }
    }
}

await Apphud.collectSearchAdsAttribution();

ApphudSDK.TrackAppleSearchAds();

Without this step, no attribution data reaches Apphud — credentials alone are not enough.

Step 2 — Copy the Apphud public key

1. Go to Connections in the Apphud sidebar.
2. Find Apple Search Ads in the list. Open its menu (⋯) → Configure.
3. Apphud has generated a public-private key pair for your app automatically. Copy the public key value. You'll paste it into Apple Search Ads in Step 4.

If you prefer to generate your own key pair, see Generate your own key pair below.

Step 3 — Invite an Apple ID with API access in Apple Search Ads

In your Apple Search Ads account, go to Settings → User Management and invite a separate Apple ID with API access.

Step 4 — Create API credentials in Apple Search Ads

1. Log out from your primary Apple Search Ads account.
2. Log in with the Apple ID you invited in Step 3.
3. Go to Settings → API (or open it directly: https://app.searchads.apple.com/cm/app/settings/apicertificates).
4. Paste the Apphud public key you copied in Step 2.
5. After Apple validates the key, copy three values: Client ID, Team ID, and Key ID.

Step 5 — Save credentials in Apphud

1. Back in Connections → Apple Search Ads → Configure.
2. Paste Client ID, Team ID, and Key ID into the matching fields.
3. Click Save.

If all credentials are valid, the page shows an Access Token and the Organizations list that the credentials can access. The integration is ready.

Multi-app credential sharing

If you have several Apphud apps using the same Apple Search Ads account, share credentials across apps instead of repeating the setup for each one.

Share to other apps

From a configured app's Apple Search Ads settings, expand Actions menu:

1. Click Share credentials to app.
2. In the picker, select one or more target apps. Apps that already have ASA configured are marked so you don't overwrite by accident.
3. Click Apply.

You'll see a queued confirmation message. The credentials and key pair are pushed to each selected app's ASA configuration asynchronously.

Share from another app

If you're on an app that doesn't have ASA configured yet:

1. Click Share from app.
2. The picker shows apps in your organization that have a valid ASA configuration available to copy from.
3. Select the source app and click Apply.

Same queued confirmation; configuration is copied in.

Refresh token

The Refresh token button on the ASA settings page re-fetches the OAuth access token from Apple:

• On a configured app — green confirmation that the token was refreshed.
• On an unconfigured app — red warning that there's no configuration to refresh.

View Apple Search Ads data

On the user page

For users attributed by Apple Search Ads, the User Page shows:

• Apple Search Ads - raw attribution data as received from Apple (numeric IDs, conversion type, click date).
• Apphud attribution — normalized fields, these are what's used in analytics and what you filter / segment by in Reports.

In Reports

ASA dimensions live under the Apphud Attribution segment group (not MMP Attribution — that's for AppsFlyer, Branch, Adjust, etc.).

Use these dimensions to filter or segment any chart:

Examples:

• Revenue by ASA campaign over time — open Proceeds, set Filter Apphud Attribution → Ad Network = Apple Search Ads, then Segment by → Apphud Attribution → Campaign.
• Retention at keyword level (Exact Match campaigns only) — open Subscribers retention, apply the same filter, segment by Keyword.
• Cumulative LTV per keyword — open Cumulative LTV, filter by ASA Ad Network, segment by Keyword.

Generate your own key pair

If you can't paste the Apphud-generated public key into Apple Search Ads (for example, browser cache issues prevent pasting), generate the key pair yourself in Terminal:

openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

Then:

1. Copy the contents of public-key.pem and paste them into Apple Search Ads → Settings → API.
2. In Apphud → Connections → Apple Search Ads → Configure, click the Paste button and paste the contents of private-key.pem.
3. Continue with Step 4 above — generate Client ID, Team ID, Key ID in Apple Search Ads and paste them into Apphud.

See Apple's documentation on implementing OAuth for the Apple Search Ads API for the key-pair requirements.

FAQ

My credentials are configured, but no Apple Search Ads campaigns appear in Reports. What should I check?

Run through this checklist:

1. The app sends the attribution token. Confirm Step 1 — the SDK method is called after initialization on every install. Without it, credentials alone produce no data.
2. API role is correct. The invited Apple ID has API Account Manager access. Read Only doesn't work.
3. Multi-app setup, if applicable. If the same Apple Search Ads account is used across multiple Apphud apps, use Share credentials to app to apply the same credentials everywhere.
4. You're filtering / segmenting by Apphud Attribution, not MMP Attribution. ASA data lives under Apphud Attribution.
5. There actually are ASA-attributed users in Apphud. If no users have ASA raw data yet (open a user page and check), Reports has nothing to show.

Why do I see Unknown [123456789] or Undetermined [123456789] instead of campaign names?

Apphud received the attribution token (so the numeric IDs are there), but couldn't decode them into names because credentials are missing, mis-configured, or pointing to a different Apple Search Ads account than the one the user came from.

Try:

1. Re-check Steps 2–5 of the setup above.
2. Confirm the Apple ID used for API access has API Account Manager.
3. If multiple apps share an Apple Search Ads account, run Share credentials to app from the configured one.
4. If credentials look right, regenerate the API certificates in Apple Search Ads and re-save in Apphud.

I connected Apple Search Ads just now. Will old trials and purchases become attributed?

Generally no. ASA attribution is set per-install when the SDK sends the token. Users who installed before the integration was wired up (or before the SDK started sending tokens) stay as they were — unattributed or Unknown. There's no backfill of historical installs.

Can I connect multiple Apple Search Ads accounts to one Apphud app?

No. An Apphud app has one ASA configuration at a time. If you need to work with multiple ASA accounts on the same app, this isn't supported as a single-app setup.

Can I analyze Apple Search Ads Search Terms in Apphud?

Not as a separate dimension. Search Terms live in Apple's reporting layer but aren't returned in the per-user attribution payload Apphud receives from Apple. Apphud's analytics are user-level, so they can only segment by fields Apple includes in user attribution (Campaign, Ad Set, Keyword, Creative Set, Conversion Type, Click Date).

For dedicated Search Terms analysis, use an ASA-specialized tool such as Asapty, which Apphud has a direct integration with.

Does Apphud support Apple Search Ads Basic?

Apphud charts are built around Campaign / Ad Group / Keyword fields. Apple Search Ads Basic uses a simpler reporting model and doesn't expose the same structure, so attribution from Basic campaigns may not surface in Apphud as cleanly. For full campaign and keyword analytics, use Apple Search Ads Advanced.

Why are some events skipped from Asapty / SplitMetrics with Skipped non attributed install?

Asapty and other ASA-dependent integrations only receive events from users who have ASA attribution in Apphud. If a user hasn't been attributed yet (the SDK hasn't sent the token, or Apple hasn't returned attribution), the event is skipped.

This can also happen due to timing: if a subscription event fires before ASA attribution arrives, that event is skipped; later events for the same user — once attribution lands — are sent normally.

To minimize skips, call the attribution method as early as possible after SDK initialization in Step 1.

I get invalid_client when saving Apple Search Ads credentials

Apple's API returned invalid_client because it couldn't authorize the credentials. Common causes and fixes:

• Client ID, Team ID, or Key ID was typed / pasted with a typo. Re-copy from Apple Search Ads.
• Public key in Apple Search Ads doesn't match the private key in Apphud. Regenerate credentials in Apple Search Ads against the current Apphud public key (Step 2).
• You regenerated credentials but didn't update the public key in Apple Search Ads to the new Apphud-generated one.
• Apple Search Ads account-level restrictions (some regions are blocked, including known issues with Russian accounts). Try changing the country on your Apple Search Ads account or using a different ASA account.

Apple says my public key is invalid when I try to paste it

Browser caching can interfere with pasting the public key into Apple Search Ads.

1. Open Apple Search Ads in an incognito window.
2. Clear your browser cache.
3. If the issue persists, generate your own key pair and paste the private key into Apphud.

What information should I send to Apphud Support if attribution doesn't work?

Include:

• Your Apphud app link or app ID.
• iOS Bundle ID and App Store App ID.
• Whether the Apple Search Ads account is used by one app or multiple apps.
• The app version where ASA token collection was added.
• SDK used (native iOS, Flutter, React Native, Unity).
• A user link in Apphud that should be attributed but isn't.
• A screenshot or numbers from Apple Search Ads (campaign, clicks, installs, dates) for the same window.
• A screenshot of the Apphud Apple Search Ads settings page — without exposing the private key.

This lets support check whether the raw ASA data is reaching Apphud and whether credentials can decode the metadata.