Skip to content

Apple Search Ads

Overview

Apple Search Ads

Branch can help track your Apple Search Ads campaigns by fetching the Apple Search Ads Attribution API. You can then use the parameters you've set in the Apple Search Ads dashboard, parameters such as the campaign name, and take special action in your app after an install, or simply track the effectiveness of a campaign in the Branch dashboard, along with other your other Branch statistics, such as total installs, referrals, and app link statistics.

Setup

In order to check if the user came from an Apple Search Ads, you must make the attribution call before Branch initializes. As a warning, Apple's Search Ads Attribution API may take more than 1 second round trip. This means that your call to Branch's initSession to the execution of the callback block may be delayed by this additional 1 second.

Import iAd and AdSupport

You must add Apple's iAd.framework and AdSupport.framework to your Linked Frameworks in your Xcode project to enable Apple Search Ads checking.

image

Enable Apple Search Ads Check

To enable this check, add a delayInitToCheckForSearchAds call to your AppDelegate.m (or AppDelegate.swift) file after you create the Branch singleton, but before you call initSession. Your code will end up looking something like this:

Branch *branch = [Branch getInstance];
[branch delayInitToCheckForSearchAds];
[branch initSession.....
let branch: Branch = Branch.getInstance()
branch.delayInitToCheckForSearchAds()
branch.initSession.....

If you're concerned about the additional 1 second latency, the call to delayInitToCheckForSearchAds can be called conditionally at run time. So, if you want to only check on first install, or the like, then just don't call this method.

Apple Search Ads Debug

We've also added a debug mode which will demonstrate the functionality. You can enable it like so, but just remember to remove this before release!

Branch *branch = [Branch getInstance];
[branch setAppleSearchAdsDebugMode];
[branch delayInitToCheckForSearchAds];
[branch initSession.....
let branch: Branch = Branch.getInstance()
branch.setAppleSearchAdsDebugMode()
branch.delayInitToCheckForSearchAds()
branch.initSession.....

Cost Data Setup

  1. Navigate to the Apple Search Ads UI > Settings > API. Verify you have selected the correct account by using the account selector in the top right hand corner.

    image

  2. Create an API certificate

    image

  3. Download the API certificate to your computer. You'll unzip the folder and get one .key and one .pem file.

    image

  4. Navigate to the Apple Search Ads partner manager in the Branch dashboard.

  5. Upload the certificates there, selecting each file, and then clicking the blue upload arrow to upload the files. Click Next to continue.

    image

  6. Select the organizations for which you would like to ingest data and click Save to enable Apple Search Ads with Cost Data.

Cost Data

Branch provides the following cost metrics for this ad partner:

Analytics Tag Description Used for
Cost Total cost (spend) for those dimensions (analytics tags, user data, time range), regardless of cost model Understanding the total amount spent
eCPI cost / installs Normalizing spend per install, to understand the average price of an install across networks or over time
eCPC cost / clicks Normalizing spend per click, to understand the average price of an click across networks or over time
eCPM cost / (impressions / 1000) Normalizing spend per thousand impressions, to understand the average price of 1000 impressions across networks or over time
eCPA cost / purchases [includes web and app purchases] Normalizing spend per purchase, to understand the average price of a purchase across networks or over time
Return On Investment (ROI) (revenue-cost / cost) * 100 Deriving return on investment, to understand the percentage "profit" made on ad spend
Return On Ad Spend (ROAS) (revenue / cost) * 100 Deriving return on investment by understanding the percentage revenue multiple for a given unit of spend

Info

All cost data is ingested in local currency and then translated to USD on the dashboard using the exchange rate for that currency on the day the data is stored. In effect, this means the dashboard shows the amount that campaign cost converted to USD at the time it ran.

Cost Data Support

"Next" button not clickable

Please ensure you've both selected the correct files and pressed the blue upload arrows to complete your upload.

Cost, click and impression data not appearing

Verify that you have selected the right certificates:

  • Did you create the certificate for the right accounts? You can toggle the accounts that you are viewing in the top right hand side of the Apple Search Ads UI.
  • Does your certificate have relevant permissions? Your certificate must have read-only permissions or higher to retrieve Apple Search Ads data.

Still not working? Try downloading a new certificate and uploading that to Branch.

Branch Cost data not matching the Ad Partner dashboard

Please ensure that you've selected the same time zone in your Ad Partner's dashboard and your Branch dashboard.

CPI metric doesn't match between Ad Partner and Branch, although cost metric does

Branch's last-click attribution model can lead to differences in install counts for Branch vs self-attributing networks (SANs) that in turn cause differences in CPI metrics. Verify whether your cost and install metrics match the Ad Partner's dashboard. If there is an install discrepancy, it is likely legitimate and due to differences in install counts, where Branch's number is more accurate. If the discrepancy is very large, investigate causes of install discrepancies through the usual troubleshooting steps.

Cost, click and impression data is all missing

Generally, reauthenticating a partner and waiting 24 hours will re-enable cost data.

When you reauthenticate, double check that you have selected the correct accounts. We will only pull cost data for accounts that you select as part of the authentication process.

Background: Cost, click and impression data for SANs are generally sourced from Partner APIs (unless Branch impression pixels or links are being intentionally used for attribution, for example, in web campaigns). When you enable a SAN, you authenticate with your provider. Branch uses this authentication to retrieve click, cost and impression data. If the authentication token expires (for example, if you reset your password, or the partner force resets your token), then you may not see click, impression or cost data. In this case, simply reauthenticate and that will refresh your token.

Cost data is missing or incorrect for certain "compare by" breakdowns

Downstream events, such as installs, should always have the full range of compare by options in the dashboard. However, clicks, impressions and cost data for SAN are often imported via Partner APIs. These APIs do not necessarily provide the same breakdowns for cost data that Branch supports with raw install events, so there may be cases where the Branch Dashboard cannot compare by the same dimensions for cost data vs install data.

Apple Search Ads Data Mapped to Branch

Branch receives and maps the following parameters from the Apple Search Ads Attribution API:

Apple Search Ads Parameter Branch Mapped Field
iad-campaign-name last_attributed_touch_data_tilde_campaign
iad-campaign-id last_attributed_touch_data_tilde_campaign_id
iad-adgroup-name last_attributed_touch_data_tilde_ad_set_name
iad-adgroup-id last_attributed_touch_data_tilde_ad_set_id
iad-keyword last_attributed_touch_data_tilde_keyword_text

View Attribution on Dashboard

All the attribution can be visible on the Branch dashboard summary page. All installs and opens registered from this channel will automatically be tagged with the channel: Apple App Store and the Ad Partner: Apple Search Ads. The campaign will be set to the Campaign Name you've configured in the Apple Search Ads dashboard.

  • Installs might not be accurate, but installs + open events should match what Apple Search Ads reports.
  • Due to API limitations, it may take up to 30 days for full attribution of a device.

Note that these stats are limited to the date range at the top of the page. You can expand the range if you'd like.

Change attribution windows

Attribution windows can be specified at the global account level or on a per link basis with the link level window taking priority. See the below instructions for setup.

Account Level Attribution Windows

You can edit your attribution windows under Link Settings > Attribution Windows.

image

Learn more about account level attribution windows in People-Based Attribution.

Ad Network Attribution Windows

You can edit your attribution windows at the ad network level, if your ad network requires it. This is recommended when you enable networks like Apple Search Ads, Facebook and Google, who may have different windows for installs. With this, you can preserve your Account Level Attribution Windows, as well.

image

Integration Support

Install discrepancies when compared with Apple Search Ads dashboard

There are a few possible causes of discrepancies with Apple Search Ads. Due to the low customizability of Apple Search Ads' attribution settings, discrepancies are often higher on Apple Search Ads than other platforms, even though performance may be solid and reporting may be working as expected.

  • Time zones. Ensure your Apple Search Ads time zone (in Settings > Overview > Account Information ) matches your Branch Dashboard time zone (visible under Account Settings).
  • Limit Ad Tracking (LAT) On. Apple Search Ads doesn't report installs to third parties if the user has Limit Ad Tracking enabled. However the Apple Search Ads dashboard shows all installs by default, regardless of limit ad tracking state. You can see the approximate quantity of Limit Ad Tracking On and Limit Ad Tracking off installs by adding those columns in the Apple Search Ads Reporting Dashboard. Those installs will not appear in Branch's dashboard.
  • Attribution Windows. Apple Search Ads attributes all installs within 30 days of an Apple Search Ads click to itself. Branch's default click to install attribution window is 7 days. You can modify Branch's click to install window. You can modify your Apple Search Ads attribution windows in Branch.
  • Last-click attribution. Apple Search Ads attributes all installs within 30 days of an Apple Search Ads click to itself. Branch will attribute to the last click within its attribution windows, which can often be a different source than Apple Search Ads.
  • Reinstalls. Apple Search Ads' dashboard shows reinstalls as conversions in its default view, but Branch calls these installs "REINSTALLS." In the Apple dashboard, select New Downloads or Redownloads in the column selector to align data.
  • Attribution API timeouts or delays. Apple Search Ads Attribution API can be slow to respond. Although customers can edit the timeout, the default Branch timeout in the code above is just over 1 second. If Apple Search Ads responds after this timeout, Branch will not attribute the install to Apple Search Ads.
  • Opens vs. installs. Branch considers the first open to be the install. Apple Search Ads considers the time that the user downloaded the app to be an install. This can cause discrepancies in counts and date of install.

Adding deep linking to Apple Search Ads

Since this integration doesn't utilize Branch links, options for deep linking are limited. We'll pass back the value you use for campaign in the Apple Search Ads dashboard. Since this value is controlled by you, you can put anything there, but it will reflect on the Apple Search Ads dashboard. We will track installs regularly.

Installs or conversion events appearing without keywords in Branch dashboard

There are "Keyword" and "Search Match" match sources for Apple Search Ads. The Search Match feature automatically matches your ad to relevant user searches on the App Store, rather than a rubric of preassigned keywords. Installs attributed to Search Matches do not have keywords associated with them. Search Match can be enabled & disabled at the Ad Group level in the Apple Search Ads dashboard.