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 your other Branch statistics, such as total installs, referrals, and app link statistics.


Apple Search Ads 更新框架(2021 年 4 月)

Apple Search Ads (ASA) 集成已更新。在旧版框架中,我们无法从启用了有限广告跟踪的用户那里获得归因数据。在新版框架中,Apple 将为选择退出追踪的用户返回一个修改的请求结果;因此,Branch 将从启用了限制广告追踪的用户那里接收归因数据。

对于选择退出追踪的用户,Apple 将返回一个归因请求结果,但其中不包含“点击时间”。

如果您当前正在使用旧版 ASA 框架(SDK 或 S2S),则建议升级到最新的 SDK 并同时运行两个框架。

Note: The new framework only works for iOS version 14.3+ because a token is only on iOS v14.3+. Apple Search Ads does not use the SKAdNetwork framework.

SDK 设置(新版框架)

Update the Branch SDK to iOS v1.39.0+. The new SDK will automatically retrieve a token on your behalf, our servers will use that token to call the Apple Search Ads Attribution API.
Note: If you are using Cocoapods, you need to manually import AdServices Framework


AdServices Framework

On SDK v1.39.1+, we recommend you import AdServices Framework to leverage the Apple Ads Attribution API.

SDK 设置(旧版框架)

为了检查用户是否来自 Apple Search Ads,必须在 Branch 初始化之前进行归因调用。作为警告,Apple Search Ads Attribution API 可能要花费1秒钟以上的往返时间。这意味着您对 Branch 的 initSession 的调用到回调块的执行可能会延迟此额外1秒钟。

导入 iAd、AdSupport 和 AdServices

您必须在 Xcode 项目的 Linked Frameworks 中添加 Apple 的 iAd.frameworkAdSupport.frameworkAdServices.framework,才能启用 Apple Search Ads 检查。



使用 Cocoapods

如果使用 Cocoapods,则会自动添加 iAd 框架(在构建阶段)并导入 header。如果不使用 Cocoapods,则需要手动进行。

启用 Apple Search Ads 检查


BranchiOS SDK v0.30.0

从 v0.30.0 版本开始,Branch iOS SDK 支持新逻辑,该逻辑增加了 Apple Search Ads 用有效负载响应以及忽略 Apple 的测试数据的等待时间。

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];

// This will usually add less than 1 second on first time startup.  Up to 3.5 seconds if Apple Search Ads fails to respond.
[branch delayInitToCheckForSearchAds];

// Increases the amount of time the SDK waits for Apple Search Ads to respond. The default wait has a better than 90% success rate, however waiting longer can improve the success rate. This will increase the usual delay to about 3 seconds on first time startup.  Up to about 15 seconds if Apple Search Ads fails to respond.
[branch useLongerWaitForAppleSearchAds];

// Branch won't callback with Apple's test data, this is still sent to the server.
[branch ignoreAppleSearchAdsTestData];

[branch initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
    // handle payload


let branch = Branch.getInstance()

// This will usually add less than 1 second on first time startup.  Up to 3.5 seconds if Apple Search Ads fails to respond.

// Increases the amount of time the SDK waits for Apple Search Ads to respond. The default wait has a better than 90% success rate, however waiting longer can improve the success rate. This will increase the usual delay to about 3 seconds on first time startup.  Up to about 15 seconds if Apple Search Ads fails to respond.

// Branch won't callback with Apple's test data, this is still sent to the server.
branch.initSession(launchOptions: launchOptions, andRegisterDeepLinkHandler: { (params, error) in
    // handle payload


测试 Apple Search Ads

If you test using a non-production app and do not use the ignoreAppleSearchAdsTestData() method, the iAd framework will return fake Apple Search Ads payloads to simulate the install being claimed by Apple Search Ads. Subsequently, you will see these claims in your reporting.



If you use deferred deep linking, do not use the useLongerWaitForAppleSearchAds() method as it will negatively impact the end user's experience by creating longer wait times for the deferred deep linking to occur.


  • For S2S integrations, you will need to retrieve the new token and send to Branch on the install as apple_attribution_token This is necessary only if you send installs S2S. No need to complete this step in case installs are recorded by Branch iOS SDK.

Please refer to the new AdServices developer documentation on how to retrieve the token.

  1. 导入 AdServices.framework
  2. 请求归因令牌(请参见示例代码)。Apple 应该在 50 毫秒内响应。
  3. 令牌具有 24 小时 TTL,因此请在该时间内发送给 Branch,以便将其用于归因。

请参阅获取 Apple 归因令牌的示例代码:

func appleAttributionToken() -> String? {
        if #available(iOS 14.3, *) {
            return try? AAAttribution.attributionToken()
        return nil
+ (NSString *)appleAttributionToken {
    if (@available(iOS 14.3, *)) {
        NSError *error;
        NSString *appleAttributionToken = [AAAttribution attributionTokenWithError:&error];
        if (!error) {
            return appleAttributionToken;
    return nil;


如果您与 Branch 具有 S2S 集成(即您不使用 Branch SDK 发送 Branch 数据),则需要先进行 Apple Search Ads 检查,然后才能将返回的有效负载发送给 Branch。

Please refer to Apple Search Ads developer documentation on how to make requests to their API.


  • 在调用 Apple 的 Attribution API 之前,请留出2秒的缓冲时间。如果您的请求在5秒钟后超时,请重试。
  • 如果响应返回为 False 或错误代码[0,2,3],则实现重试逻辑。 2秒后再次调用 Apple。
  • 20秒后或成功响应后,使用返回的 Apple Search Ads 有效负载调用 Branch。


  1. Navigate to the partner management tab and search for Apple Search Ads
  2. 点击 Sign in With Apple
  1. 使用您的 Apple 帐户登录。登录后,同意授权并选择 Grant Access
11461146 19581958
  1. 在 Branch 操作后台上,选择相关的广告帐户
  1. 击中 Save




代理商管理的 Campaign

Apple Search Ads 数据已映射到 Branch

Branch 从 Apple Search Ads 归因 API 接收并映射以下参数:


Apple Search Ads 参数Branch 映射字段


Apple Search Ads 参数Branch 映射字段

Additional Fields Supported

Apple Search Ads 参数Branch 映射字段


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 channelApple App Store and the Ad PartnerApple Search Ads. The campaign will be set to the Campaign Name you've configured in the Apple Search Ads dashboard.

  • 安装可能不准确,但安装+打开事件应与 Apple Search Ads 报告的内容相匹配。
  • 由于 API 的限制,设备可能需要30天才能完全归因。

请注意,这些统计信息是仅限于页面顶部的日期范围 。如果您需要,可以扩大范围。




Please see our guide on Attribution Windows.

关键字 ID

With the new framework, keywordId is also passed to Branch , and you may use that in your Compare Bys to measure your campaign performance.


This is also available in Branch's Query API in the last_attributed_touch_data_tilde_keyword_id field in all EO topics.


与 Apple Search Ads 操作后台 (Dashboard)对比产生的安装差异

Apple Search Ads 差异可能有几种原因。由于 Apple Search Ads 归因设置的可定制性较低,因此即使性能可能可靠并且报告可能会按预期运行,Apple Search Ads 上的差异通常也比其他平台更高。尝试与 ASA 安装和 Branch 进行对帐的最佳方法是查看 'New Download' 计数,但减去通过在报告中对 LAT 进行分组来发现的用户的 LAT 百分比。这将估算关闭 LAT 时的新下载量,而 Branch 报表会首先从这些下载中打开。

  • 时区。确保您的 Apple Search Ads 时区(在 Settings > Overview > Account Information 中)与您的 Branch 操作后台 (Dashboard) 时区(在 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 via the old framework. However the Apple Search Ads dashboard shows all installs by default, regardless of limit ad tracking state. If the newer framework is properly set up, attribution will still be provided for LAT-on or ATT opted-out users and this will not be a source of discrepancy, but if the new framework is not set up properly this may still cause a difference in numbers.
  • 归因窗口 (Attribution Windows)。 Apple Search Ads 会将所有安装归因于 Apple Search Ads 点击其自身30天内。 Branch 的默认点击安装归因窗口为7天。您可以修改 Branch 的点击以安装窗口。您可以在 Branch 中修改 Apple Search Ads 归因窗口。
  • 最终点击归因 (Last-click attribution)。 Apple Search Ads 会将所有安装归因于 Apple Search Ads 点击其自身30天内。Branch 将归因于其归因窗口中的最终点击,而归因窗口通常可能是与 Apple Search Ads 不同的来源。
  • 重新安装 (Reinstalls)。 Apple Search Ads 的操作后台 (Dashboard)在其默认视图中将重新安装显示为转化,但 Branch 称这些安装为 “REINSTALLS”。在Apple 操作后台 (Dashboard)中,在列选择器中选择“新建下载”或“重新下载”以对齐数据。
  • 归因 API 超时或延迟 (Attribution API timeouts or delays)。 Apple Search Ads Attribution API 响应速度可能很慢。尽管客户可以编辑超时,但是上面代码中的默认 Branch 超时仅超过1秒。如果Apple Search Ads 在此超时后做出响应,则 Branch 不会将安装归因于 Apple Search Ads。
  • 打开与安装 (Opens vs. installs)。 Branch 将第一个打开认为安装。 Apple Search Ads 认为用户下载应用的时间为安装时间。这可能会导致计数和安装日期不一致。

向 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 Branch dashboard. We will track installs regularly.

安装或转化事件在 Branch 操作后台 (Dashboard)中显示时没有关键字

Apple Search Ads 有 KeywordSearch Match 匹配来源。搜索匹配功能会自动将您的广告与 App Store 上的相关用户搜索进行匹配,而不是预先分配的关键词。归因于“搜索匹配”的安装没有与之关联的关键字。可以在 Apple Search Ads 操作后台 (Dashboard)的广告组一级启用和禁用 Search Match。

Using TestFlight app or Developer App

If you are using the new ASA framework and are debugging or testing your app using the TestFlight app or developer app, Apple Search Ads returns dummy values of test campaign data with Campaign ID as 1234567890 which will be visible in the Branch Dashboard. Please ensure to filter it out when looking at your ASA attributed campaign data in the Dashboard.


If you ever need to restart your integration with Apple Search Ads, you must do so by clicking the Reset Settings button in the Apple Search Ads settings in the Branch Dashboard. Clicking the Disable button at the bottom will not reset your integration.