Apple Search Ads integration setup

For:
Marketers
Last update:

At a glance: Apple Search Ads (ASA), an AppsFlyer SRN partner, helps users find your app in the App Store using keywords. 

apple_search_ads.png

App relevance determines if your ad is the one displayed in response to a search query in the App Store. User response to an ad is a signal of ad relevance. ASA uses user response as a signal in deciding which ads to display the most. 

ASA offers click-based mobile attribution, user retargeting, and cost data via API (with an ROI360 subscription).

Set up ASA integration

Get started

Prerequisite

  • The most recent version of the AppsFlyer iOS SDK is adopted

Set up Apple Search Ads in AppsFlyer:

The setup is done from the Active Integrations page, but to find new partners you must first go to the Partner Marketplace. Complete the configuration using the relevant tabs, as described below.

 Note

Before setting up an integration, make sure you contact the partner and open an account with them.

To activate the integration:

  1. In AppsFlyer, under Configuration go to Partner Marketplace. 
  2. Search for the partner and select it. You're directed to the partner details page.
  3. Click Set up integration. You’re directed to the integration setup page. 
  4. In the Integration tab, turn on Activate partner.
    Note: The toggle must stay on (activated) for as long as you work with the partner.
  5. Complete the configuration using the relevant tabs, as described below.

Integration tab

Apple Search Ads, an SRN, integrates with AppsFlyer via API. As such, there are no postback settings. Complete the following sections according to your attribution goals. 

Section  Details
Integration activation

To activate the integration for attribution:

  1. In AppsFlyer, under Configuration go to Partner Marketplace. 
  2. Search for the partner and select it. You're directed to the partner details page.
  3. Click Set up integration. You’re directed to the integration setup page. 
  4. In the Integration tab, turn on Activate partner.
    Note: The toggle must stay on (activated) for as long as you work with the partner.
  5. Complete the configuration using the relevant tabs, as described below.
Install attribution

Install click-through lookback window

Set the maximum time from click-to-install. Doing so enables AppsFlyer to attribute installs (first launches) taking place within the lookback window to ASA.

Range: 1–30 days
Reinstalls 

Reinstall attribution

If Reinstall attribution is on, AppsFlyer can attribute reinstalls to ASA.

Reinstall attribution lookback window settings are set according to the install attribution settings.

If the user is within the re-attribution window (set at the time of the original install), the install is attributed to ASA as a reinstall.

The reinstall can be seen in the retargeting view of the Overview dashboard.

The Store reinstall raw data field is set to true. 

Currently ASA retargeting does not support re-engagements.

Inactivity window

Set the user inactivity threshold (in days) to control the impact of retargeting campaigns. 

Cost tab

The cost integration provides the following aggregated data:

  • Cost data for your campaigns, adsets, geos/countries, and keywords. See the ad network cost integration table for full details on the supported dimensions, metrics, and features.
    Note: Cost data requires an ROI360 subscription. 
  • Data on clicks, impressions, and enriched data—keywords, campaign names, and adsets.

Note

  • The use of multiple ASA accounts is supported. In other words, if you run campaigns for the same app using different ASA accounts, AppsFlyer can receive this data from all accounts.
  • Cost data for "campaign groups" is not supported by the ASA reporting API, so "campaign group" data is not available in AppsFlyer.
  • To sign in with Apple, you need ASA admin-level permissions (either Account Read Only or Account Read and Write).
  • When you sign in with Apple, any previously provided API certificates stop pulling data.
  • When you sign in with Apple, authorization of ASA campaign groups isn't cumulative. This means that when you integrate a new app, the authorization for campaign groups chosen for the previous apps is revoked unless chosen again.

To enable cost, clicks, impressions, and enriched data:

View your cost API status and the last time AppsFlyer managed to pull matching cost data in either the cost (and ad revenue) integration status dashboard, or in the individual ad network dashboard.

Permissions tab

Setting ad network and agency permissions.

Set up agencies and ASA marketing partners

Principles

Apple Search Ads: Marketing partner vs. Agency

Advertisers and agencies can elect to work with ASA Marketing Partners to report and optimize campaigns on ASA. 

The differences between agencies and marketing partners are enumerated in the table that follows. 

Agency vs. marketing partner

  Agency Marketing partner
AppsFlyer sends postbacks  No Yes
Technology Run campaigns on your behalf Have a value add technology solution to optimize campaigns

Configuring agencies and marketing partners 

Use the checklist that follows to ensure that you complete all steps in the configuration process. Detailed instructions are contained per partner type in the sections that follow. 

Configuration steps checklist

Configured by Integration with an agency Integration with a marketing partner
Advertiser
  1. In AppsFlyer, in the ASA integration tab, turn on Activate partner.
  2. Select the agency, in the Agency permissions tab, turn on Agency Permission.
  1. In the ASA integration tab, turn on Activate partner.
  2. In the ASA dashboard get the marketing partner's Campaign Group ID.
  3. In the marketing partner's integration tab:
    1. Turn on Activate partner.
    2. Set Campaign Group.
    3. Configure in-app events postback.
Agency

In the ASA integration tab, set Apple Search Ads Campaign Group.

 N/A

Marketing partner setup

To set up a marketing partner:

  1. If required, activate Apple Search Ads integration: 
    1. In AppsFlyer, go to, Configuration> Active integration partners > Apple Search Ads. 
    2. Turn on Activate Partner. 
    3. Click Save.
  2. In your Apple Search Ads dashboard: Get the Apple Search Ads Campaign Group ID parameter related to the marketing partner. Use the screenshot that follows as a guide to locating the ID. 

    ASACGroupID.png

  3. In AppsFlyer, configure the ASA marketing partner:
    1. In AppsFlyer, go to, Configuration > Active integrations.
    2. Search for the Apple Search Ads marketing partner.
      The list of marketing partners displays. 
    3. Select a marketing partner.
    4. Turn on Activate Partner.
    5. Enter the partner's Apple Search Ads Campaign Group ID that you retrieved in the earlier step. Enter the digits (numbers) only. 
    6. Click Save.

  4. [Optional] Configure in-app events postback:

    1. Turn on In-app events postback.

    2. Click Add event to add an SDK event to the list.

    3. Complete the following parameters:

      1. 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.
      2. Send revenue: Select one of the following: No values and no revenue, Values and no revenue, or Values and revenue.
  5. Click Save integration.

Agency setup

Advertisers permit agencies to run campaigns on their behalf using Apple Search Ads. Both advertisers and agencies perform setup actions in AppsFlyer as described in this section. 

Apple Search Ads campaign group

  • Agency campaigns and advertiser campaigns must be separate Apple Search Ads ID campaign groups.
  • Don't use special characters and spaces for the group name.
  • When you sign in with Apple, authorization of ASA campaign groups isn't cumulative. This means that when you integrate a new app, the authorization for campaign groups chosen for the previous apps is revoked unless chosen again. You will need to select Limited Access and each of the relevant campaign groups (related to the apps you want to connect for the advertiser).

Advertiser actions

Prerequisite:

Grant permission to an agency. 

To enable attribution of Apple Search Ads the advertiser:

  1. In AppsFlyer, go to Configuration > Active integrations.
  2. Select Apple Search Ads. 
  3. Go to the Integration tab, switch on Activate partner.
  4. [Optional] If you want to attribute users who reinstall the app during the re-attribution window, switch on Reinstall attribution. 
  5. Click Save.

Agency actions

  1. In your Apple Search Ads dashboard: Get your Campaign Group ID. Use the screenshot that follows as a guide to locating the ID. Get only the digits.

    ASACGroupID.png

  2. In AppsFlyer, select an App. 
  3. Go to Configuration > Active integrations. 
  4. Select Apple Search Ads. 
  5. Enter the Apple Search Ads Campaign ID parameter. Note! Enter digits (numbers only)
  6. Click Save. 

 Note

When an agency works with an Apple Search Ads Marketing Partner, the agency must configure the same campaign group ID in both the Apple Search Ads configuration page and the Marketing Partner configuration page.

Cost, clicks, and impressions data

If you enable cost API, AppsFlyer receives cost, clicks, and impression data from ASA via API. See the ad network cost integration table for full details on the supported dimensions, metrics, and features. Note: Cost data requires an ROI360 subscription. Without ROI360, only click and impression data is received. 

To enable the cost API:

  • Follow these integration instructions. Make sure that when prompted to log into your Apple Search Ads account in Select permissions, select one of the following:
    • Account Read and Write
    • Account Read Only
      Note: If you choose Limited Access and a specific campaign group, you may encounter data errors. 

View your cost API status and the last time AppsFlyer managed to pull matching cost data in either the cost (and ad revenue) integration status dashboard, or in the individual ad network dashboard.

 Note

Agencies must enable cost on their dashboard and upload the certificates on their side to sync costs with AppsFlyer.

Disable agencies and marketing partners

To stop recording attribution of Apple Search Ads installs generated by agencies or marketing partners: 

  1. In AppsFlyer, go to Configuration > Active integrations.
  2. Select the agency or marketing partner as the case may be. 
  3. Delete the content of the Apple Search Ads Campaign Group ID field. 
  4. Click Save integration. 

Additional information

ASA Attribution

Apple Search Ads functions independently of SKAdNetwork and deterministically attributes users, regardless of ATT consent. This means that for users attributed to ASA, you have the full range of features and measurements provided by our LTV attribution model.

ASA attribution doesn't rely on IDFA—attribution is done using a token from the device (deterministic attribution)—and differs according to ATT consent:

ATT consent

Click time available

Click lookback window

Remarks

Yes

Yes

Set by the advertiser

AppsFlyer last-click attribution rules used

No

No

30 days
(set by ASA) 

 No click time provided. Priority is given to deterministic candidates

Discrepancies

AppsFlyer and Apple Search Ads use different attribution logic resulting in discrepancies between the platforms. Apple Search Ads, an SRN, reports new installs by API. 

Apple Search Ads reporting to AppsFlyer by API

  • Campaigns are aggregated by Geo.
  • The following are not reported: Impressions, taps, or cost of Geos having less than 100 impressions for a given campaign.
  • When grouping by Geo in AppsFlyer, Geos with unavailable data are not shown, and the total of unavailable data appears under N/A.

Retargeting related discrepancies

The AppsFlyer retargeting attribution mechanism allows advertisers to measure and analyze retargeting campaigns, in addition to user acquisition campaigns.

The figures that follow illustrate how discrepancies can occur in relation to retargeting campaigns (irrespective of the retargeting controls setting) running on Apple Search Ads.

Retargeting on

ASA_R_Enabled.png

Retargeting off

ASA_R_Disabled.png

Additional reasons for discrepancies

The table that follows lists the main reasons for discrepancies.

Discrepancy Apple Search Ads AppsFlyer

Differences related to AppsFlyer SDK versions

Counts conversions irrespective of the AppsFlyer SDK version.

For AdsServices, SDK V6.1.3+ is required to attribute correctly. 

Limit ad tracking (LAT) and ATT.

Always counts the conversion.

If your campaign is limited by age and gender LAT users are excluded from the campaign. 

Apple users younger than 18 are always LAT.

LAT conversions are attributed to organic.

If AdServices is implemented and iOS14.3+ is installed, then non-consented users are attributed correctly.  

Counting users

Counts users based on downloads

Counts users based on first app open

Reinstall: A user, after installing the app, deletes it, clicks on a Search Ad, then installs the app again

Counts as a conversion (install)
  • With IDFA: AppsFlyer identifies the reinstall and does not count it for UA purposes. Tip! Enable retargeting and the reinstall is recorded as a retargeting install (AKA re-attribution)
  • Without IDFA: AppsFlyer can rely on IDFV to determine whether this is a re-install or a new install:
    1. If one or more other apps of the vendor are installed on the device, AppsFlyer attributes ASA with a re-attribution.
    2. Otherwise (no other app exists), AppsFlyer attributes ASA with a new install.

Click lookback window

Fixed 30-day window

For responses from AdServices that don't have a click time, the click lookback window is fixed to a 30-day window.   

Winning click

Always attributes to itself if the user engaged and downloaded the app.

Has visibility across multiple networks, and attribute according to last-click methodology

Install time

App download time

First app open 

Timezone

App store local timezone

UTC timezone or as set in AppsFlyer settings

Conversion data 

It can take more than 5 seconds for AppsFlyer to be updated that Search Ads brought the install

 Attributes within 5 seconds at which time the Conversion data API responds. If no data has been received then the response is organic.

Cost data

Reports cost for all keywords

Doesn't report cost data for keywords containing uppercase letters in the cohort dashboard or cohort API.

Geo locations

Apple Search Ads allows advertisers to target users according to their country and region. Apple Search Ads supports a limited number of countries.

AppsFlyer recognizes the exact geographic location of the user based on the IP address, and so reports on Geos not available on Apple Search Ads.

Tip! Users that install while being in the actual country of the app store have the same Geo data in AppsFlyer and Apple Search Ads

Tips

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:

Tip Details

Get keyword data

Apple Search Ads shares keyword data with AppsFlyer. You can view the keyword data in raw data and analytics tools like Pivot, Retention, and Cohort.

Note:

  • Obtaining keyword data may be delayed for 8-12 hours, and in some cases, may only include the keyword ID without the keyword term
  • To obtain keyword data, the Cost toggle must be turned on. Keyword data is provided as part of the Cost integration, without the need for an ROI360 subscription.

If 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

Not all keywords are equal meaning that whilst different keywords may cost the same the quality of users attracted could be different. Use the Retention or Pivot reports to identify the keywords that maximize your ROI.

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 starting October 13, 2019. 
  • Dimensions:
    • Date
    • Campaign
    • Adset
  • Analysis tools: 

Limitations

  • Only use the noted dimensions to filter and group cost data queries. For example, don't filter or group using Geo. 

 Examples

Cohort Example

The following example displays how to set up Cohort to view cost and ROI information.

Cohort setup

CohortRequest.png

Cohort result table

In the table that follows, the total cost and Cohort ROI is displayed

CohortTable.png

Pivot example

Pivot setup

Pivot_define.png

Pivot result table

Pivot.png
Find the best performing creative set

creative_sets.png

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.

Target re-downloaders

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.

ASACGroupID.png

ASA change log

ASA updates and changes
Effective date Update/change

2023-02-07

The enriched attribution parameters Campaign name, Adset name, and Keywords are available only when the Cost tab is enabled, irrespective of your subscription plan.
This means that for your dashboards and raw data reports to show campaign names, adset names, or keywords, you must have the Cost tab enabled. 

2022-02-16

Keywords are available via Cost API. You must enable the API in the Apple Search Ads integration page. Note! The API is available to all advertisers irrespective of your subscription plan.

2021-04-07

Apple Search Ads integration: ASA functions independently of SKAdNetwork and deterministically attributes users. This means that for users attributed to ASA you have the full range of features and measurements provided by our LTV attribution model.

2021-03-07

Apple Search Ads is rolling out Campaign Management API V4.0. The API relates to cost and other campaign-related data. It has no impact on attribution. We are in the process of adopting the updated API. No action is required from you.

2021-02-15

 Starting this date, the campaign name and adset name fields can be populated if you enable the ASA Cost API. The API is available to all advertisers irrespective of the subscription plan. 

Availability of Apple Search Ads campaign parameters

The table below shows the availability of attribution parameters in raw data reports or on the dashboard.

Raw data report parameter  Availability 
Campaign name For this parameter to be available, you must enable the Cost API on the Apple Search Ads integration page. The API is available to all advertisers, irrespective of their subscription plan
Campaign ID Always available
Adset name For this parameter to be available, you must enable the Cost API on the Apple Search Ads integration page. The API is available to all advertisers, irrespective of their subscription plan
Adset ID Always available
Ad Currently unavailable
Ad ID
This parameter is only available when both of the following conditions are met:
  • Users are on iOS 15.2 and later
  • The ad uses Custom Product Pages for campaigns that are associated with either of the following ad placements:
    • Today tab
    • Search results 
Keywords For this parameter to be available, you must enable the Cost API on the Apple Search Ads integration page. The API is available to all advertisers, irrespective of their subscription plan
Keyword ID

This parameter is available via raw data reports. However, it must be explicitly selected in Data Locker, Push API, and Export data. In the case of Pull API, add keyword_id to the  &additional_fields parameter of the Pull API call.
Keyword Match Type

Currently unavailable

Impact of Aggregated Advanced Privacy

Starting in iOS 14 ATTrackingManager (ATT) governs the availability of IDFA and the user-level attribution data of installs brought by ASA is controlled by ASA. As such, the user-level data availability of installs brought by ASA is not affected by Aggregated Advanced Privacy.

Note! Installs brought by ASA aren't reported in the framework of SKAdNetwork. 

ATT Consent 

Click time available

Click lookback window

Remarks

Data availability 

IDFA available

Consenting

Yes

Set by the advertiser

AppsFlyer last-click attribution rules used

User-level attribution data

Yes
Non-consenting

No

30 days
(set by ASA) 

Priority is given to deterministic candidates. 

User-level attribution data without the click time. 

No

 

See also