Tracking Apple Search Ads campaigns

AppMetrica tracks Apple Search Ads campaigns. Apple links app installations from Search Ads on its own.

Note. For full attribution of Apple Search Ads on devices running iOS 14.5 and higher, we recommend using the AppMetrica SDK 3.15.1 and later.

For iOS versions 14.5 and higher, the user is asked for permission to access the advertising ID and use tracking. For users who do not grant access to the IDFA, a new attribution system is used: AdServices Framework.

For iOS versions 14.4 and below, the old iAd Framework tracking method is supported. The AppMetrica SDK 2.9.4 or higher is suitable for this purpose.

For iOS 14.5 and higher, you can also use the iAd Framework, but users who haven't granted access to IDFA aren't attributed.

Comparison of attribution systems
iAd Framework AdServices Framework
Supported iOS versions 10 and higher 14.3 and higher
Tracking iOS 14.4 and below Access to IDFA isn't required. The iAd framework will still work. Access to IDFA isn't required. The AdServices Framework works on devices running iOS versions 14.3–14.4.
Tracking restrictions for iOS 14.5 and higher

Only users who have agreed to tracking are attributed, provided that IDFA is available in the app.

Users who don't grant access to IDFA aren't attributed: ATTrackingManager.AuthorizationStatus = denied or notDetermined.

Users who don't grant access to IDFA are attributed with fewer details — the click date isn't specified.
How to customize
  • The AppMetrica SDK 2.9.4 or higher.

  • Add the iAd Framework library to the project according to the instructions.

The AppMetrica SDK 3.15.1 or higher.
Available campaign parameters

iad-org-name — String. The name of the organization that hosts the campaign.

iad-org-id — Integer. The ID of the organization that hosts the campaign.

iad-campaign-id — Integer. The ID of the campaign that the ad belongs to.

iad-campaign-name — String. The name of the campaign that the ad belongs to.

iad-click-date — Date/time string. The date and time of the ad click.

iad-purchase-date — Date/time string. The date and time when the user first downloaded your app. When iad-conversion-type takes the value redownload, iad-purchase-date is the date of the original download. It's possible that the download wasn't related to an ad in Apple Search Ads.

iad-conversion-date — Date/time string. The date and time when the user downloaded your app after clicking an ad.

iad-conversion-type — String. The type of conversion. Possible values: new download — first download, redownload — a download by users who installed your app before.

iad-adgroup-id — Integer. The ID of the ad group.

iad-adgroup-name — String. The name of the ad group.

iad-country-or-region — String. The country or region associated with the campaign that led to the installation.

iad-keyword — String. The keyword that led to the ad impression and click.

iad-keyword-id — Integer. The ID of the keyword that led to the ad impression.

iad-keyword-matchtype — String. The match type of keyword that led to the ad impression.

iad-creativeset-id — Integer. The ID of the creative set.

iad-creativeset-name — String. The name of the creative set.

Only entity IDs are supported.

orgId — Integer. The ID of the organization that hosts the campaign.

campaignId — Integer. The ID of the campaign that the ad belongs to.

conversionType — String. The type of conversion. Possible values: new download — first download, redownload — a download by users who installed your app before.

clickDate — Date/time string. The date and time of the ad click.

adGroupId — Integer. The ID of the ad group.

countryOrRegion — String. The country or region associated with the campaign that led to the installation.

keywordId — Integer. The ID of the keyword that led to the ad impression and click.

creativeSetId — Integer. The ID of the creative set.

Names aren't supported.

iAd Framework AdServices Framework
Supported iOS versions 10 and higher 14.3 and higher
Tracking iOS 14.4 and below Access to IDFA isn't required. The iAd framework will still work. Access to IDFA isn't required. The AdServices Framework works on devices running iOS versions 14.3–14.4.
Tracking restrictions for iOS 14.5 and higher

Only users who have agreed to tracking are attributed, provided that IDFA is available in the app.

Users who don't grant access to IDFA aren't attributed: ATTrackingManager.AuthorizationStatus = denied or notDetermined.

Users who don't grant access to IDFA are attributed with fewer details — the click date isn't specified.
How to customize
  • The AppMetrica SDK 2.9.4 or higher.

  • Add the iAd Framework library to the project according to the instructions.

The AppMetrica SDK 3.15.1 or higher.
Available campaign parameters

iad-org-name — String. The name of the organization that hosts the campaign.

iad-org-id — Integer. The ID of the organization that hosts the campaign.

iad-campaign-id — Integer. The ID of the campaign that the ad belongs to.

iad-campaign-name — String. The name of the campaign that the ad belongs to.

iad-click-date — Date/time string. The date and time of the ad click.

iad-purchase-date — Date/time string. The date and time when the user first downloaded your app. When iad-conversion-type takes the value redownload, iad-purchase-date is the date of the original download. It's possible that the download wasn't related to an ad in Apple Search Ads.

iad-conversion-date — Date/time string. The date and time when the user downloaded your app after clicking an ad.

iad-conversion-type — String. The type of conversion. Possible values: new download — first download, redownload — a download by users who installed your app before.

iad-adgroup-id — Integer. The ID of the ad group.

iad-adgroup-name — String. The name of the ad group.

iad-country-or-region — String. The country or region associated with the campaign that led to the installation.

iad-keyword — String. The keyword that led to the ad impression and click.

iad-keyword-id — Integer. The ID of the keyword that led to the ad impression.

iad-keyword-matchtype — String. The match type of keyword that led to the ad impression.

iad-creativeset-id — Integer. The ID of the creative set.

iad-creativeset-name — String. The name of the creative set.

Only entity IDs are supported.

orgId — Integer. The ID of the organization that hosts the campaign.

campaignId — Integer. The ID of the campaign that the ad belongs to.

conversionType — String. The type of conversion. Possible values: new download — first download, redownload — a download by users who installed your app before.

clickDate — Date/time string. The date and time of the ad click.

adGroupId — Integer. The ID of the ad group.

countryOrRegion — String. The country or region associated with the campaign that led to the installation.

keywordId — Integer. The ID of the keyword that led to the ad impression and click.

creativeSetId — Integer. The ID of the creative set.

Names aren't supported.

Step 1. Integrate the iAd Framework

Integrate the iAd Framework into an application with the AppMetrica SDK installed, so that Apple Search Ads can detect and link app installations. Integration instructions are available on the Search Ads site (see paragraph Add the iAd Framework to Your Xcode Project).

Connecting in Unity
In the Unity 3d interface, open Settings → Other Settings → Scripting Define → Symbols. Add the APP_METRICA_ADD_IAD_FRAMEWORK directive.
Note. If you added the iAd Framework in the Xcode project, you don't need to add the directive.

After the iAd Framework is added, the AppMetrica SDK starts to detect installations from Apple Search Ads automatically.

Step 2. Perform a test installation

Create a test advertising campaign for Search Ads and install the application through ad placement. The tracker for this source will appear in the AppMetrica interface automatically:

Step 3. (Optional) Configure attribution

Set up the Search Ads attribution by using the tracker configuration:

  1. Go to the Trackers section. In order to filter the trackers by a media source, click on the Media Source drop-down list in the menu on the left and select Apple Search Ads.
  2. Choose the tracker to set up attribution for from the list. The tracker name matches the name of the Apple Search Ads campaign.
  3. Make the necessary changes to the Attribution settings section and click Save. See more information about setting up attribution.
Step 4. (Optional) Configure postbacks

The campaign parameters can be sent in postbacks similar to macros. For example, to pass the campaign ID in the campaign_id parameter in the postback URL, specify campaign_id={iad-campaign-id}. You can also use all system macros.

Set up postbacks using the tracker settings:

  1. Go to the Trackers section. In order to filter the trackers by a media source, click on the Media Source drop-down list in the menu on the left and select Apple Search Ads.
  2. Choose the tracker to set up the postback for from the list. The tracker name matches the name of the Apple Search Ads campaign.
  3. Make the necessary changes to the Postback settings section and click Save. See more information about setting up postbacks.

If you didn't find the answer you were looking for, you can use the feedback form to submit your question. Please describe the problem in as much detail as possible. Attach a screenshot if possible.