Apple Search Ads

Overview

423423

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 Updated Framework (2021년 4월)

Apple Search Ads (ASA) 연동이 업데이트되었습니다. 이전 프레임워크에서는 Limit Ad Tracking(광고 트래킹 제한)이 활성화된 유저의 어트리뷰션 데이터를 가져올 수 없었습니다. 새 프레임워크에서 Apple은 트래킹에서 옵트아웃한 유저에 대해 수정된 응답을 리턴합니다. 따라서 Branch는 Limit Ad Tracking(광고 트래킹 제한)이 있는 유저의 어트리뷰션 데이터를 수신합니다.

트래킹에 동의하지 않은 유저의 경우, 애플은 어트리뷰션 응답을 리턴하지만 '클릭 시간'은 포함되지 않습니다.

현재 이전 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 설정 (구 프레임워크)

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.

iAd, AdSupport및 AdServices 가져오기

Apple Search Ads 검사를 사용하려면 Xcode 프로젝트의 Linked Frameworks 에 Apple의 iAd.framework, AdSupport.frameworkAdServices.framework 를 추가해야 합니다.

19121912

🚧

Cocoapods 사용

Cocoapods를 사용하는 경우 iAd 프레임 워크가 자동으로 추가되고 (빌드 단계에서) 헤더를 가져옵니다. Cocoapods를 사용하지 않는다면 이를 수동으로 해야 합니다.

Apple Search Ads 확인 활성화

📘

Branch iOS 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:

Objective-C

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

Swift

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.
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.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. 어트리뷰션 토큰 요청 (샘플 코드 보기). 이것은 50 ms 이내에 Apple에서 구할 수 있어야 합니다.
  3. 토큰에는 24시간 TTL이 있으므로 이를 어트리뷰션에 사용하려면 해당 시간 내에 Branch로 전송하십시오.

Apple 어트리뷰션 토큰을 얻기 위한 샘플 코드를 참고하세요.

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

서버 간 설정 (구 프레임워크)

Branch와 S2S 연동이 있는 경우 (즉, Branch 데이터를 전송하기 위해 Branch SDK를 사용하지 않는 경우), 반환된 페이로드를 Branch에 보내기 전에 Apple Search Ads 확인을 직접 수행해야 합니다.

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

구현 지침

  • Apple의 어트리뷰션 API를 호출하기 전에 2초 버퍼를 제공하십시오. 요청 시간이 5초가 초과되면 다시 시도하십시오.
  • 응답이 False 또는 오류 코드 [0,2,3]로 반환되는 경우, 재시도 로직을 구현합니다. 2초 후에 Apple을 다시 호출하십시오.
  • 20초가 지나거나 성공적인 응답 후, 반환된 Apple Search Ads 페이로드로 Branch를 호출합니다.

Cost(비용) 데이터 설정

  1. Navigate to the partner management tab and search for Apple Search Ads
  2. 클릭 Sign in With Apple
21482148
  1. Apple 계정으로 로그인합니다. 로그인한 후 권한을 수락하고 다음을 선택합니다. Grant Access
11461146 19581958
  1. Branch 대시보드에서 관련 광고 계정을 선택합니다.
21302130
  1. Save를 클릭하세요. Save

📘

비용 데이터 서포트

📘

에이전시 관리 캠페인

Branch에 매핑된 Apple Search Ads 데이터

Branch는 Apple Search Ads 어트리뷰션 API에서 다음 파라미터를 수신하고 매핑합니다.

구 프레임워크

Apple Search Ads 파라미터Branch 매핑 필드
iad-campaign-namelast_attributed_touch_data_tilde_campaign
iad-campaign-idlast_attributed_touch_data_tilde_campaign_id
iad-adgroup-namelast_attributed_touch_data_tilde_ad_set_name
iad-adgroup-idlast_attributed_touch_data_tilde_ad_set_id
iad-creativeset-namelast_attributed_touch_data_tilde_ad_set_name
iad-creativeset-idlast_attributed_touch_data_tilde_ad_set_id
iad-keywordlast_attributed_touch_data_tilde_keyword
iad-keyword-idlast_attributed_touch_data_tilde_keyword_id
iad-org-namelast_attributed_touch_data_tilde_advertising_account_id
iad-org-idlast_attributed_touch_data_tilde_advertising_account_name
iad-country-or-regionlast_attributed_touch_data_tilde_country_or_region
iad-keyword-matchtypelast_attributed_touch_data_tilde_keyword_match_type

새 프레임워크

Apple Search Ads 파라미터Branch 매핑 필드
campaignIdlast_attributed_touch_data_tilde_campaign_id
campaignNamelast_attributed_touch_data_tilde_campaign
adGroupIdlast_attributed_touch_data_tilde_ad_set_id
adGroupNamelast_attributed_touch_data_tilde_ad_set_name
creativeSetIdlast_attributed_touch_data_tilde_creative_id
keywordIdlast_attributed_touch_data_tilde_keyword_id
keywordlast_attributed_touch_data_tilde_keyword
orgIdlast_attributed_touch_data_tilde_advertising_account_name
countryOrRegionlast_attributed_touch_data_tilde_country_or_region

대시보드에서 어트리뷰션 보기

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.

  • 설치가 정확하지 않을 수 있지만 설치 + 공개 이벤트는 Apple Search Ads가 리포트하는 것과 매치되어야 합니다.
  • API 제한으로 인해 디바이스의 전체 어트리뷰션에 최대 30 일이 걸릴 수 있습니다.

이러한 통계는 페이지 상단의 날짜 범위에 한정된 데이터입니다. 원하는 경우 해당 날짜 범위를 확장할 수 있습니다.

📘

어트리뷰션 윈도우

어트리뷰션 윈도우를 글로벌 계정 레벨 또는 링크별로 지정할 수 있으며, 이때 링크 레벨 윈도우가 우선적으로 지정됩니다.

Please see our guide on Attribution Windows.

Keyword 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.

27402740

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

Keyword Name and Ad Set Name

With the new framework, Branch is now able to retrieve keyword names and Ad set names for Apple Search Campaigns, and you may use that in your Compare Bys to measure your campaign performance.

연동 서포트

Apple Search Ads 대시보드와 비교할 때 불일치

Apple Search Ads와의 불일치를 야기할 수 있는 몇 가지 원인이 있습니다. Apple Search Ads의 어트리뷰션 설정의 커스텀 가능성이 낮기 때문에 성능이 탄탄하고 리포트가 예상대로 작동할 수 있다는 장점이 있지만, Apple Search Ads은 타 플랫폼보다 더 많은 불일치를 보이는 경우가 많습니다. ASA 설치 및 Branch와의 조정을 시도하는 가장 좋은 방법은 '새 다운로드' 수를 확인하고 리포트에서 LAT 설정 / 해제를 그룹화하여 찾은 유저의 LAT 비율을 빼는 것입니다. 이렇게 하면 LAT를 끈 상태에서 새로운 다운로드의 추정치를 얻을 수 있으며 Branch 리포트는 해당 다운로드에서 처음으로 열리게 됩니다.

  • 타임존. Apple Search Ads의 시간대(Settings > Overview > Account Information에서 확인)가 Branch 대시보드의 시간대(Account 설정 아래에서 확인)와 일치하는지 확인하세요.
  • 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.
  • 어트리뷰션 윈도우. Apple Search Ads는 Apple Search Ads 클릭 후 30 일 이내에 이루어진 모든 설치를 그 자체에 어트리뷰션합니다. Branch의 기본 클릭 투 설치 어트리뷰션 윈도우는 7 일입니다. Branch의 클릭 투 설치 윈도우는 수정이 가능합니다. Branch에서 Apple Search Ads 어트리뷰션 윈도우를 수정할 수 있습니다.
  • 라스트 클릭 어트리뷰션. Apple Search Ads는 Apple Search Ads 클릭 후 30 일 이내에 이루어진 모든 설치를 그 자체에 어트리뷰션합니다. Branch는 어트리뷰션 윈도우 내에서 라스트 클릭을 어트리뷰션하며, 이는 종종 Apple Search Ads와 다른 소스일 수 있습니다.
  • 리인스톨. Apple Search Ads의 대시보드는 기본 보기에서 리인스톨을 전환으로 표시하지만, Branch는 이러한 설치를 "리인스톨"로 표시합니다. Apple 대시보드의 열 선택기에서 New Downloads 또는 Redownloads를 선택하여 데이터를 정렬하세요.
  • 어트리뷰션 API 타임아웃 또는 지연. Apple Search Ads 어트리뷰션 API는 반응이 느릴 수 있습니다. 고객이 타임아웃을 편집할 수 있지만 위 코드의 기본 Branch 타임아웃은 약 1초에 불과합니다. Apple Search Ads가 이 타임아웃 이후에 반응하는 경우, Branch는 해당 인스톨에 대한 Apple Search Ads의 어트리뷰션을 인정하지 않습니다.
  • 오픈 vs 설치 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 대시보드에서 키워드 없이 나타나는 설치 또는 전환 이벤트

Apple Search Ads에는 일치 출처로 KeywordSearch Match가 있습니다. 검색 일치 기능은 미리 할당된 키워드 지시문을 사용하지 않고, App Store에서 여러분의 광고가 관련성 높은 사용자 검색과 일치하는지 자동으로 확인합니다. 검색 일치를 통해 발생한 설치에는 관련 키워드가 없습니다. 검색 일치는 Apple Search Ads 대시보드의 광고 그룹 수준에서 활성화하거나 비활성화할 수 있습니다.

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.

Re-Authentication

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.

10281028