Apple Search Ads (ASA), an AppsFlyer integrated partner, enables you to assist users to find your app in the App Store. The relevance of your app to the search query determines whether your ad is the one displayed. User response to an ad is an important signal of the ad's relevance. If no one taps the ad, Apple Search Ads stops showing it.
This guide describes how to start attributing Apple Search Ads with AppsFlyer, directly or through third parties, as well as related tips and explanations for the inherent differences between the platforms.
Setting up Apple Search Ads
To attribute Apple Search Ads your iOS app MUST include the native frameworks iAd.framework and AdSupport.framework. iAd.framework is automatically added from SDK version 4.10.0 and above, while AdSupport.framework is automatically added from SDK version 4.8.11 and above.
If you are using prior iOS SDK versions, you need to add these frameworks manually. To learn how to include these frameworks, see our iOS SDK Integration Guide.
Go to the dashboard of your app and click Integrated Partners on the left side bar.
Enter Apple Search Ads in the search field and click on its logo to open the Apple Search Ads configuration window.
The Apple Search Ads configuration window includes 3 active tabs: Integration, Cost, and Permissions. Click on the items below to read about the tabs setup.
For a detailed description of the Partner Configuration Window Header, click here.
The partner must be activated on first visit, to enable its setup.
The Integration Tab is divided into different sections as described below.
Apple Search Ads does not accept in-app events or postbacks from measurement partners and as such, you can't configure them.
This slider allows you to set the maximum time from click to install. Only installs (first launches) that take place within the lookback window may be attributed to Apple Search Ads.
Set the click-through attribution lookback window to any required value between 1 to 30 days.
AppsFlyer recommends configuring the click attribution lookback window to 30 days, to match the Apple Search Ads self-reporting window. This helps reducing discrepancies with the Apple Search Ads dashboard.
More details about the click lookback window here.
Activate Reinstall attribution if you want to attribute re-installs.
Reinstall attribution lookback window settings are taken from the install attribution settings.
- With every new install, AppsFlyer gets the re-download flag from Apple. If all the following conditions are met, the new install is attributed to Apple Search Ads as a reinstall:
- Currently Apple Search Ads retargeting does not support re-engagements.
Attribution link tab
For SRNs, such as Facebook, Apple Search Ads, Adwords, Snapchat there is nothing to set in this tab as SRNs don't use external attribution links.
Enabling Apple Search Ads cost integration
Use the cost tab to enable AppsFlyer to get costs, clicks, and impression data from Apple Search Ads by API. The use of multiple search ad accounts is supported. Meaning, if you run campaigns for the same app, using different search ads accounts you can get the data from all accounts.
To enable the Apple Search Ads API, you need to download authentication certificates, being PEM and KEY files, from the Apple Search Ads account. Get the files from each account separately.
To get the PEM and KEY file from you Apple Search Ads account:
- Log in to Apple Search Ads, click on the upper-right hand, select settings.
- Click on API tab, click Create API Certificate.
- Name the API certificate and select the permissions type from Account Read-only or Account admin, click Create.
- Select Action, then Download
The certificates are downloaded in a .zip file containing two files that you extract and upload to AppsFlyer as described in the procedure that follows.
If the certificate has the permissions to view data of more than one app, you can use it to get cost data for those apps.
You need to repeat the procedure that follows, for each app that is referenced the certificate.
To enable the API connection to Apple Search Ads:
- In AppsFlyer, go to the Apple Search Ads, cost tab.
- If necessary enable Get cost, clicks, and impressions data.
- Click Add certificate.
- Enter Certificate name. This should be synonymous with the Apple Search Ads account name.
- If you haven't already done so, unzip the file you downloaded from Apple Search Ads.
- Upload the PEM file and KEY file you downloaded from Apple Search Ads.
- After a few moments, the status indicator changes to OK. If this is not the case, an error message displays. Use the table in the following section to diagnose the problem.
- Click Save Cost.
- If you have more than one Apple Search Ads account repeat, the relevant steps in this procedure for each account.
AppsFlyer receives cost data for the past 7 days. Cost data prior to this is not available.
Cost data for Basic campaigns is not supported by the ASA reporting API, and so Basic campaign data is not available in AppsFlyer.
Cost data sync status
In the cost tab, the status of the cost integration displays.
The table below describes the different status messages, and corrective action to perform if necessary.
|Status||Description||What to Do|
Fail / Invalid credentials
Cost API credentials are incorrect. AppsFlyer is unable to pull cost data
|Make sure that the cost API key is correct|
With sync message:
Cost Data was never successfully pulled
One of the following is possible:
No Matching Data
AppsFlyer queries this app's active campaigns with the Partner API, but the partner API isn't returning any data for these campaigns.
This might happen if you change the campaign ID while it is still running.
If you rely on cost data, do not change the IDs of campaigns while they are still active and running.
Also, make sure you entered the API credentials for the correct app, and that the network is passing the correct campaign IDs on the attribution link.
Partner API is not responding
The ad network cost data API is either down or experiencing issues
Wait for the network API to become responsive
Last successful data pull
The cost tab shows the last time cost data has been pulled yet. If cost data has never been pulled, the sync message shows Cost Data was never successfully pulled.
Scenario 1: Stopped campaigns
AppsFlyer pulls cost for several campaigns that you run with ad network A. You look in the cost tab and you see the message Last successful sync 2 hours ago. The same day you stop running campaigns with ad network A. Two weeks later, you look in the cost tab of ad network A. You then see the message Last successful sync 14 days ago.
Scenario 2: Ad network API issues
AppsFlyer pulls cost for several campaigns that you run with ad network B. You look in the cost tab and you see the message Last successful sync 2 hours ago. Ad network B then experiences issues with their API. It takes them a few hours to fix it. When you look in the cost tab you see the message Last successful sync 8 hours ago.
Ad revenue tab
In this tab, you can select the permissions to grant Apple Search Ads. Note that even if attribution is disabled for Apple Search Ads, the permissions tab is active and you can grant Apple Search Ads control.
Enable Ad Network Permissions to begin the configuration.
Once you switch Ad Network Permissions on:
- The app appears on the ad network's dashboard
- Permissions are granted only to this ad network
- The ad network admin can see basic data about the app
Grant permissions to ad network team members
Apple Search Ads admin has access to your app by default, but you can give specific Apple Search Ads employees the permissions to manage your app. To be able to do so, these employees must be added by Apple Search Ads admin as team members to AppsFlyer.
Then, get the email addresses of the relevant Apple Search Ads team members.
To add team members that can have permissions to manage your app:
- Click Add team member.
- Enter the email of the ad network team member.
- Click Add.
- Repeat the process to add more team members if needed.
Once you enable permissions for the ad network, select the permissions you want to grant it.
Use these toggles to give the ad network permissions to handle its own configuration for your app:
Ad network permissions
- Allow to configure integration - permit the partner to setup the integration tab (except in-app event postbacks)
- Allow to configure in-app event postbacks - permit the partner to setup in-app event postbacks mapping to itself on the integration tab
- Allow access to your retention report - only to the partner's own retention data
- Allow access to your aggregate loyal user data - only to the partner's own loyal user data
- Allow access to your aggregate in-app events data - only to the partner's own in-app events data
- Allow access to your aggregate revenue data - only to the revenue data attributed to the partner
- Allow spend ingestion - at the app level
- Allow access to your Protect360 dashboard - only to the partner's own Protect360 data, and providing the feature is enabled for the advertiser
Learn more about granting ad network permissions.
Disabling Apple Search Ads attribution
To disable the attribution to Apple Search Ads:
- Go to the Apple Search Ads configuration page
- Switch off the Activate partner setting.
- Click Save.
Apple Search Ads attribution API mapping
|AF Raw Report Parameter||ASA Attribution Parameter|
Note: iad-creativeset-name and iad-creativeset-id are not mandatory when setting up Apple Search Ads campaigns. If they are not specified when setting up a campaign, the Ad and Ad ID fields in raw data are empty.
Apple Search Ads:
Marketing Partner Vs. Agency
Advertisers and agencies can work with Apple Search Ads Marketing Partners to report and optimize campaigns on Apple Search Ads. When configured, AppsFlyer sends postbacks to the configured Apple Search Ads Marketing Partner.
To differentiate between marketing partners and agencies, the following points should be considered:
- Marketing Partners receive postbacks, agencies do not.
- Marketing Partners are generally tech companies often with their own SAAS solution. Agencies are likely to run the traffic on your behalf using Apple Search Ads native tools.
Marketing partner configuration
Set out below are the instructions for the configuration of marketing partners.
Enabling sending postbacks to Apple Search Ads marketing partners
- Advertiser enables attribution for Apple Search Ads.
- From the agency account configure the Apple Search Ads Marketing Partner configuration.
- Click Integrated Partners on the left sidebar
- Enter the name (or list of comma-separated names) of the Apple Search Ads Marketing Partner you want to work with in the search box.
- Click the logo of the selected partner.
- Enter the name of the partner's Apple Search Ads Campaign Group.
The campaign group name must be unique across Apple Search Ads platform. To make sure it's unique, add your company's name at the beginning of the campaign group name. For example, partner_campaign_group_name.
- Copy the Campaign Group name highlighted below in green on the Apple Search Ads UI and paste it on the AppsFlyer Apple Search Ads Campaign Group parameter as shown in the screenshot above.
If there are no campaign groups in the Apple Search Ads account, use the Account Name (appearing in the upper right-hand corner).
Configuring in-app events
- Toggle In-App Event Postbacks to ON
- Select the Sending Option for all SDK defined events.
- Only events attributed to this partner for events coming only from users attributed to this partner
- Events attributed to any partner or organic to have your entire user base available to be reported to the partner
- Click Add Event to add an SDK Event to the list
- Complete the following parameters:
|SDK Event Name||The name of the event, as received by AppsFlyer either from the SDK integrated in your app, or from server to server events.
Tip - If you don't see the event you want in the list, make sure to activate the event on a device with a non-organic installation and recheck.
|Partner Event Identifier||The unique name or ID of each event as defined on Apple Search Ads' side.
Obtain the corresponding Event ID from Apple Search Ads and set in the text field.
|Send Revenue||When unchecked - AppsFlyer sends all the parameters of the rich in-app event to the partner, except for the revenue parameter, which is contained in the af_revenue parameter.
When checked - AppsFlyer sends all the parameters including the revenue value (if it exists in the event).
If the advertiser or the agency has disabled attribution for Apple Search Ads, attribution for this app, including sending the postbacks to Apple Search Ads Marketing Partner campaigns, will not work.
Advertisers can allow agencies to run campaigns on their behalf using Apple Search Ads.
Both advertisers and agencies must actively configure the system, as described below.
Prerequisite advertiser actions
To grant access to the agency, follow the instructions here.
To enable attribution for Apple Search Ads:
- Click Integrated Partners on the left sidebar
- Enter "Apple Search Ads" in the search field
- Click on the logo of Apple Search Ads to open the configuration page
- In the Integration Parameters tab, switch on the Activate partner setting
- Switch on Reinstall attribution setting if you plan to attribute users who who reinstall the app during the re-attribution window
- Click Save.
The agency logs into the AppsFlyer dashboard and selects the specific app they want to promote on Apple Search Ads.
- Click Integrated Partners on the left sidebar
- Enter Apple Search Ads in the search field
- Click the logo of Apple Search Ads to open the configuration page
- Go to your Apple Search Ads account, and copy the Campaign Group name (highlighted below in green:
- Paste it in the Apple Search Ads Campaign Group parameter field in AppsFlyer.
- The campaign group name must be unique across Apple Search Ads platform. To make sure it's unique, add your company's name at the beginning of the campaign group name. For example, partner_campaign_group_name.
- AppsFlyer also recommends your Campaign group to NOT include special characters or white spaces.
When an agency works with an Apple Search Ads Marketing Partner, the agency must configure the same campaign group name in both the Apple Search Ads configuration page and the Marketing Partner configuration page.
Cost, clicks and impressions data
- In the Cost tab, toggle Get Cost, Clicks and Impressions Data to ON.
- Upload the valid PEM and KEY file.
- Click Save.
Agencies must enable cost on their dashboard and upload the certificates on their side to sync costs with AppsFlyer.
- Agency campaigns must be run from a separate Apple Search Ads campaign group than the advertiser's.
- If the advertiser has disabled attribution for Apple Search Ads but the attribution is enabled by the agency, attribution for this app, including from the agency campaigns, will not work.
- Special characters and spaces should not be used for the group name.
Disabling Apple Search Ads attribution
To disable an agency or a marketing partner's attribution of Apple Search Ads, while keeping it enabled for the advertiser:
- From the agency account go to the Apple Search Ads or the marketing partner's configuration page
- Clear the text in the Apple Search Ads Campaign Group box
- Click Save
Since AppsFlyer and Apple Search Ads use different attribution logic, discrepancies between the two platforms are expected.
For each new install, AppsFlyer's SDK receives the Apple Search Ads' attribution data directly from the Apple Search Ads servers.
Campaigns are aggregated by Geo. Apple Search Ads reporting API does not return impressions, taps, or cost for geos with less than 100 impressions for a specific campaign. When grouping by Geo in AppsFlyer, Geos with unavailable data are not shown, and the total of unavailable data appears under N/A.
AppsFlyer's retargeting toggle
AppsFlyer’s retargeting attribution mechanism allows advertisers to measure and analyze their retargeting campaigns, in addition to their user acquisition campaigns.
The diagrams below illustrate how discrepancies may occur when Retargeting is either enabled or disabled for campaigns configured with Apple Search Ads.
Additional reasons for discrepancies
Set out below are a number of the main causes for discrepancies between the AppsFlyer and Apple Search Ads data.
Time delays in data arriving from Apple Search Ads
Differences based on the AppsFlyer's SDK version used
If your app is using AppsFlyer SDK Version 4.7.11 or above, but haven't updated it in over 4 months, it is highly recommended to do so.
Limited ad tracking (LAT)
Some iOS users activate LAT, which prevents attribution in some cases.
Apple Search Ads excludes LAT users from your campaign targeting, if you apply age and gender refinements on it.
Note: Apple users aged 18 and younger are always LAT.
AppsFlyer and Apple Search Ads use different methods for counting users
In general, 90% of downloaded apps are also launched at least once, completing the install process.
Out of this group, around 90% launch within 24 hours of the download, meaning that on the first day roughly 81% of downloads are recorded as installs in AppsFlyer.
App Re-Installs: User has the app, then deleted it and then installs it again having clicked on the Apple Search Ad. AppsFlyer and Apple Search Ads differ in the way these installs are considered.
Enable Retargeting toggle on the Integrated Partners - Apple Search Ads Configuration screen - so re-installing users appear in the Retargeting Dashboard.
Differences between the AppsFlyer and Apple Search Ads click lookback window
Set the Click Lookback window in the AppsFlyer dashboard to 30 days.
Differences in the visibility of last click installs between AppsFlyer and Apple Search Ads
The time of the install record date differs between AppsFlyer and Apple Search Ads
AppsFlyer and Apple Search Ads use different time zones
Make sure you align the app's time zone on AppsFlyer's dashboard with Apple Search Ads. For details, click here.
Apple Search Ads reports cost for all keywords.
AppsFlyer does not report cost data for keywords that contain uppercase letters in the cohort report or cohort API.
Differences in Geo location of users
Users that install while being in the actual country of the app store have the same geo data on AppsFlyer and Apple Search Ads
Issue with iOS versions 11.3 to 11.4.0
There may be some discrepancies between the number of installs reported by AppsFlyer and Search Ads Campaign Management due to an issue with the Search Ads Attribution API on devices running iOS versions 11.3 to 11.4.0.
As of 9 July 2018 this issue has been resolved, with the release of iOS 11.4.1. Search Ads driven conversions attribute as expected as of this iOS version, but data continues to be unreported for devices running iOS 11.3. Therefore, this issue is not a common reason for discrepancy anymore.
Working with Apple Search Ads enables you to collect valuable marketing data, which can impact your user acquisition efforts with all media sources for your iOS apps.
Tips to help you maximize the benefits of using Apple Search Ads:
Get keyword data
Apple Search Ads shares keyword data with AppsFlyer. You can view the keyword data in the raw data and advanced reports like Pivot, Retention, and Cohort.
In cases where the keyword data is missing in AppsFlyer, this can be caused by:
- Package type: Keyword data is shared by Apple Search Ads with advertisers, that have the Apple Search Ads advanced package.
- Campaign type: You can configure different campaign keyword matching types in Apple Search Ads. Based on match type, Apple Search Ads shares the keywords as follows:
- Exact match: The exact keywords searched for by the user
- Broad match: The keywords Apple used to perform the search. These are similar to the user's actual search terms.
- Search match: Apple does not share these keywords with advertisers.
- Case sensitivity: Apple Search Ads marketing API returns case-sensitive data and Apple Search Ads attribution API returns lower-case data. To avoid data conflicts in reports, use only lower-case keywords.
Use only exact or broad match search campaigns to receive complete keyword data.
Compare the quality of users based on keyword data
Analyze keyword cost
The platform contains aggregate keyword cost data when ASA keyword campaigns are configured as an exact match or broad match. Keyword cost data has the following characteristics:
- Historical data is available from October 13, 2019.
- Analysis tools:
- Only use the noted dimensions to filter and group cost data queries. For example, don't filter or group using Geo.
Find the best performing creative set
It's good practice to test how leads respond to different creative sets you use. The best performing creative sets have the highest conversion rates. In addition, the best creative sets convert users with a higher level of engagement.
This impacts all your iOS leads, not only ASA leads, for they all reach your app page in the app store. However, with ASA installs, AppsFlyer indicates the creative set ID in the raw data Ad ID parameter, enabling you to compare the performance of different creative sets.
Your past users are possibly the best audience for you to target using ASA.
A user, who uninstalled your app, and as a result of your ASA retargeting campaign installs again, is called a Re-Downloader by ASA. If the re-install is performed during the re-attribution window, AppsFlyer calls this a Re-Attribution. In all other cases, it is treated as a new install.