Attribution Reporting API 교차 웹 및 앱 구현 가이드

Attribution Reporting API를 사용하면 동일한 기기에서 발생하는 소스 및 트리거에 대해 교차 앱 및 웹 기여 분석을 사용 설정할 수 있습니다. Chrome과 같은 브라우저는 브라우저에서 이러한 등록을 처리하는 대신 소스 및 트리거 등록을 모두 Android용 Attribution Reporting API에 위임할 수 있습니다. 이렇게 하면 Android에서 사이트와 앱 모두에서 소스와 트리거를 일치시킬 수 있습니다.

이 가이드에서는 교차 앱 및 웹 기여 분석을 설정하는 방법을 설명합니다.

교차 앱 및 웹 기여 분석을 설정할 때는 설정이 의도한 대로 작동하는지 확인할 수 있는 디버깅 솔루션도 숙지하는 것이 좋습니다.

Android OS에 소스 및 트리거 등록

교차 앱 및 웹 기여 분석은 동일한 기기의 브라우저와 Android OS 모두에서 Attribution Reporting API가 사용 설정된 경우에만 사용할 수 있습니다. Android Attribution Reporting API의 사용 가능 여부는 Attribution-Reporting-Support 헤더를 통해 전송됩니다. 이 헤더는 기기에서 사용 가능한 항목에 따라 os, 웹 또는 둘 다를 반환합니다. 둘 다 사용할 수 있는 경우 광고 기술은 브라우저 또는 OS에 웹 소스와 웹 트리거를 등록할 수 있습니다.

광고 기술은 웹 소스 또는 웹 트리거를 브라우저 또는 OS에 등록할지 결정해야 합니다.

  • 웹 전용 캠페인의 경우 광고 기술은 계속해서 Chrome의 Attribution Reporting API에 소스와 트리거를 모두 등록하거나 둘 다 OS에 위임할 수 있습니다. 소스 또는 트리거가 WebView에서 발생할 수 있는 웹 전용 캠페인의 경우 광고 기술은 소스 및 트리거 등록을 모두 OS에 위임해야 합니다. 자세한 내용은 WebView 섹션을 참고하세요.

  • 광고 기술은 중복 기여 분석 보고서가 생성되지 않도록 Chrome API와 Android API에 소스와 트리거를 동시에 등록해서는 안 됩니다.

  • 브라우저와 OS에 대해 별도로 기여 분석이 실행됩니다. 소스가 브라우저에 등록되었지만 트리거가 OS에 등록된 경우 두 항목을 일치시킬 수 없으며 그 반대의 경우도 마찬가지입니다.

  • 앱 또는 웹 트리거가 발생할 수 있는 소스의 경우 광고 기술이 웹 소스 및 트리거 등록을 Android Attribution Reporting API에 위임하는 것이 좋습니다.

  • 앱 기반 소스에 의해 트리거될 수 있는 트리거의 경우 광고 기술은 웹 트리거 등록을 Android Attribution Reporting API에 위임하도록 선택할 수 있습니다.

  • 소스와 트리거가 모두 앱에서 발생하는 캠페인의 경우 둘 다 OS Attribution Reporting API에 등록해야 합니다.

앱 소스 및 웹 트리거 등록

일부 캠페인의 경우 소스는 앱에서 발생하지만 트리거는 동일한 기기의 모바일 브라우저에 있는 웹사이트에서 발생할 수 있습니다.

예

사용자가 즐겨 사용하는 뉴스 앱에서 기사를 읽고 있습니다. 파리행 저가 항공편 광고가 표시되자 사용자가 기쁜 마음으로 클릭하여 예약합니다. 뉴스 앱에서 광고를 게재하는 광고 기술은 Android Attribution Reporting API에 클릭 소스를 등록합니다. 그러면 사용자는 Chrome에서 광고주의 웹페이지로 이동하여 전환할 수 있습니다. 광고주의 사이트에 있는 광고 기술은 OS 수준 API를 사용할 수 있는지 확인하고 사용 가능함을 확인합니다. 광고 기술은 Chrome의 Attribution Reporting API에 직접 등록하는 대신 Chrome에 등록을 OS에 위임하도록 지시하여 전환 트리거를 등록합니다. 그러면 OS 수준 Attribution Reporting API가 앱 소스와 웹 트리거를 일치시키고 관련 보고서를 전송할 수 있습니다.

앱에서 웹으로의 기여 분석 흐름
앱에서 웹으로의 기여 분석 흐름

앱 소스 등록:

  1. Daily News Android 앱의 광고 기술 SDK는 registerSource()를 사용하여 클릭을 등록합니다.

  2. Android의 Attribution Reporting API는 registerSource()에 제공된 애드테크 서버 URL에 요청을 보냅니다.

  3. 광고 기술 서버는 Attribution-Reporting-Register-Source 헤더로 응답하여 소스 등록을 완료합니다.

웹 트리거 등록:

  1. 광고 기술이 트리거를 등록하고 Attribution Reporting API에서 OS 사용 가능 여부를 확인합니다.

  2. 웹 ARA는 지원되는 플랫폼에 관한 정보를 반환합니다.

  3. OS-Trigger 헤더는 웹 ARA API에 OS ARA API registerWebTrigger() 함수를 호출하도록 지시합니다.

  4. registerWebTrigger() 호출은 내부에서 실행되며 개발자가 OS에서 직접 registerWebTrigger()를 호출할 필요가 없습니다.

  5. OS ARA가 이를 인계받아 Attribution-Reporting-Register-OS-Trigger 헤더에서 제공한 광고 기술 서버 URL에 요청을 보냅니다.

  6. 광고 기술이 OS API로 트리거 등록을 완료합니다.

  7. OS ARA는 앱 간 기여 분석에 적용된 것과 동일한 로직에 따라 기여 분석을 실행하고 동일한 보고서를 전송합니다.

워크플로

다음 단계에는 작업을 완료하는 방법에 관한 자세한 내용이 포함되어 있습니다.

  1. 앱의 광고 기술은 다음과 같이 조정하여 Android의 Attribution Reporting API에 소스를 등록합니다.

    • 웹사이트에서 전환이 발생할 것으로 예상되는 앱 소스를 등록하려면 Attribution-Reporting-Register-Source 응답 헤더에 앱 대상 대신 웹 대상 (eTLD+1)이 포함되어야 합니다.
    Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
    • 일부 광고주는 302 리디렉션 체인을 사용하여 여러 측정 서비스 제공업체 (예: 서드 파티 측정 도구 또는 분석 도구)를 사용할 수 있습니다. 경우에 따라 Attribution Reporting API가 백그라운드에서 Attribution-Reporting-Redirect 헤더에 지정된 리디렉션 경로를 따르고 동시에 기존 탐색 요청에 대해 302 리디렉션 경로가 포그라운드에서 실행됩니다. 이러한 요청은 동일한 URL로 전송되며, 이로 인해 서드 파티 측정 서비스 제공업체에서 등록을 중복 집계할 수 있습니다. 등록이 중복으로 집계되지 않도록 하려면 광고 기술에서 리디렉션 동작을 수정하여 Attribution Reporting API 등록을 대체하지만 결정론적 URL로 전송할 수 있습니다.

    • 이 동작을 사용 설정하려면 광고 기술이 등록 요청에 응답할 때 새 HTTP 헤더를 포함해야 합니다.

      • 헤더는 Attribution-Reporting-Redirect-Config입니다.
      • 헤더 값은 redirect-302-to-well-known이어야 합니다.
      Attribution-Reporting-Redirect-Config: redirect-302-to-well-known

    • 소스 등록 프로세스의 나머지 부분은 표준 앱 간 소스 등록과 동일합니다.

  2. 광고주의 웹사이트에 있는 광고 기술은 Chrome에 등록을 Android Attribution Reporting API에 위임하도록 요청하여 트리거를 등록합니다.

    • 사용자가 웹사이트에서 전환을 완료하면 광고 기술이 Chrome에 트리거를 등록하도록 요청합니다.

      1. 픽셀 또는 fetch() 요청을 사용하여 트리거 등록 요청을 할 수 있습니다.

      2. Attribution-Reporting-Support 요청 헤더는 Chrome에서 광고 기술로 반환됩니다. Chrome 브라우저와 Android 기기 모두에서 API가 사용 설정된 경우 헤더는 os, web를 반환합니다.

      Attribution-Reporting-Support: os, web

    • 그런 다음 광고 기술은 다음과 같은 Attribution-Reporting-Register-OS-Trigger 헤더를 사용하여 Chrome에 OS에 위임하도록 지시해야 합니다.

      1. Chrome에 등록을 OS에 위임하도록 지시합니다.

      2. Chrome은 OS API 함수 registerWebTrigger()를 호출하여 등록을 OS에 위임합니다.

        • registerWebTrigger() 호출은 내부에서 이루어지므로 광고 기술에서 registerWebTrigger()를 직접 호출할 필요가 없습니다.

      3. OS API는 브라우저에서 전달된 광고 기술 URI에 대한 보조 API 호출을 시작합니다.

      Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger",
"https://other-adtech.example/register-trigger"

    • 경우에 따라 Attribution-Reporting-Support 헤더를 사용할 수 없으며 전송할 수 없습니다. 이 경우 광고 기술은 Attribution-Reporting-Info 헤더를 포함하여 트리거 등록을 처리할 기본 플랫폼을 계속 설정할 수 있습니다. 키는 preferred-platform이고 허용되는 값은 os 및 web입니다. 브라우저는 사용 가능한 경우 기본 플랫폼을 사용하고 OS를 사용할 수 없는 경우 웹 플랫폼으로 대체합니다.

    Attribution-Reporting-Info: preferred-platform=os
    • 트리거 등록을 완료하려면 광고 기술의 엔드포인트가 응답 헤더를 사용하여 Android Attribution Reporting API 요청에 응답해야 합니다.
    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}

웹 소스 및 앱 트리거 등록

일부 캠페인의 경우 소스는 모바일 브라우저의 사이트에서 발생하지만 트리거는 동일한 기기의 앱에서 발생할 수 있습니다.

예

사용자가 Android 휴대전화의 Chrome 브라우저에서 사이트를 탐색하고 있습니다. 사용자가 좋아하는 매장의 스웨터 광고를 보게 됩니다. 사용자가 광고를 클릭하면 이미 다운로드한 앱으로 이동합니다. 광고가 게재된 웹사이트의 광고 기술은 Chrome에서 Attribution Reporting API를 사용하는 대신 등록을 Android Attribution Reporting API에 위임하도록 Chrome에 지시하여 클릭 소스를 등록합니다. 사용자가 쇼핑 앱에서 스웨터를 구매합니다. 그러면 광고주 앱의 광고 기술이 Android Attribution Reporting API에 전환 트리거를 등록합니다. OS 수준 Attribution Reporting API는 웹 소스와 앱 트리거를 일치시키고 관련 보고서를 전송할 수 있습니다.

웹에서 앱으로의 기여 분석 흐름
웹에서 앱으로의 기여 분석 흐름

웹 소스 등록:

  1. 광고 기술이 소스를 등록하고 Attribution Reporting API에서 OS 사용 가능 여부를 확인합니다.

  2. 웹 ARA는 지원되는 플랫폼에 관한 정보를 반환합니다.

  3. OS-Source 헤더는 웹 ARA API에 OS ARA API registerWebSource() 함수를 호출하도록 지시합니다.

  4. registerWebSource() 호출은 백그라운드에서 이루어지며 개발자가 OS에서 직접 registerWebSource()를 호출할 필요가 없습니다.

  5. OS ARA가 이를 인계받고 Attribution-Reporting-Register-OS-Source 헤더에서 제공한 광고 기술 서버 URL에 요청을 보냅니다.

  6. 광고 기술이 OS API로 소스 등록을 완료합니다.

앱 트리거 등록:

  1. 의류 매장 Android 앱의 광고 기술 SDK가 OS ARA에 트리거를 등록합니다.

  2. Android의 Attribution Reporting API는 registerTrigger()에 제공된 애드테크 서버 URL에 요청을 보냅니다.

  3. 광고 기술 서버가 Attribution-Reporting-Register-Trigger 헤더로 응답하여 트리거 등록을 완료합니다.

  4. OS ARA는 앱 간 기여 분석에 적용된 것과 동일한 로직에 따라 기여 분석을 실행하고 동일한 보고서를 전송합니다.

워크플로

다음 단계에는 이 작업을 완료하는 방법에 관한 자세한 내용이 포함되어 있습니다.

  1. 게시자 웹사이트의 광고 기술은 Chrome에 등록을 Android Attribution Reporting API에 위임하도록 지시하여 소스를 등록합니다.

    • 웹에서 앱으로의 사용 사례의 경우 소스를 등록할 때 attributionsrc 태그를 사용하거나 JavaScript 등록을 사용하여 기여 분석 소스 매개변수를 직접 지정해야 합니다.
    • 다음 예에서는 attributionsrc 태그를 사용하여 소스 매개변수를 지정합니다.
    <img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">

  2. Attribution-Reporting-Support 요청 헤더는 Chrome에서 광고 기술로 반환됩니다. Chrome 브라우저와 Android 기기 모두에서 API가 사용 설정된 경우 헤더는 os, web를 반환합니다.

    Attribution-Reporting-Support: os, web

  3. 광고 기술은 다음과 같은 Attribution-Reporting-Register-OS-Source 헤더를 사용하여 Chrome에 OS 수준 API에 위임하도록 지시해야 합니다.

    1. Chrome에 등록을 OS에 위임하도록 지시합니다.
    2. Chrome은 OS API 함수 registerWebSource()를 호출하여 등록을 OS에 위임합니다.
    3. registerWebSource() 호출은 내부에서 이루어지므로 광고 기술은 registerWebSource()를 직접 호출할 필요가 없습니다.
    4. OS API는 브라우저에서 전달된 광고 기술 URI에 대한 보조 API 호출을 시작합니다.
    Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
    • 경우에 따라 Attribution-Reporting-Support 헤더를 사용할 수 없습니다. 이 경우에도 광고 기술은 Attribution-Reporting-Info 헤더를 포함하여 소스 등록을 처리할 기본 플랫폼을 설정할 수 있습니다. 키는 preferred-platform이고 허용되는 값은 os 및 web입니다. 브라우저는 사용 가능한 경우 기본 플랫폼을 사용하고 OS를 사용할 수 없는 경우 웹 플랫폼으로 대체합니다.
    Attribution-Reporting-Info: preferred-platform=os
    • 소스 등록을 완료하려면 광고 기술의 엔드포인트가 응답 헤더 Attribution-Reporting-Register-Source를 사용하여 Android Attribution Reporting API 요청에 응답해야 합니다. 응답은 대상 필드에 앱 대상도 지정해야 합니다.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
    • 소스 등록의 리디렉션을 지원하기 위해 Chrome은 리디렉션을 따르고 각 리디렉션 홉의 웹 컨텍스트 API를 호출합니다.
    • 나머지 소스 등록은 동일하게 유지됩니다.

  4. 광고주 앱의 광고 기술이 Android Attribution Reporting API에 트리거를 등록합니다.

    • 앱에서 발생하는 트리거의 경우 앱은 평소와 같이 Android Attribution Reporting API에 트리거를 등록합니다.

앱 및 웹 잠재 도착 페이지가 모두 있는 캠페인

  1. 이중 대상 설정

    • 일부 캠페인은 사용자가 앱을 설치했는지와 같은 다양한 요인에 따라 광고주의 앱 또는 광고주의 웹페이지에서 전환되도록 설정될 수 있습니다.
    • 이 경우 트리거가 발생한 위치와 관계없이 소스에 올바르게 기여도를 부여할 수 있도록 소스 등록을 OS에 위임하는 것이 좋습니다(가능한 경우). OS에 소스를 등록할 때 각 매개변수에 앱 및 웹 대상을 모두 지정할 수 있습니다.
    • 앱 대상이 destination 필드에 있어야 함
    • 웹 대상이 web_destination 필드에 있어야 함
    • Chrome 개발자는 OS Attribution Reporting API의 destination 필드가 URL이 아닌 앱 패키지여야 함을 유의해야 합니다.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    "web_destination": "https://example.advertiser"
    ...
}
    • 대략적인 보고에 관한 다음 섹션에서는 이중 대상을 사용하면 보고서의 노이즈에 미치는 영향에 대해 설명합니다.

  2. 대략적인 보고를 사용하여 이중 대상 소스의 이벤트 수준 보고서에서 노이즈를 줄입니다.

    • 소스 등록에서 OS (앱)와 웹 대상이 모두 지정된 경우 이벤트 수준 보고서는 기본적으로 트리거가 웹 대상에서 발생했는지 앱 대상에서 발생했는지 지정합니다. 하지만 개인 정보 보호 한도를 유지하기 위해 이러한 보고서에 추가 노이즈가 추가됩니다.
    • 광고 기술은 Attribution-Reporting-Register-Source 헤더 아래의 coarse_event_report_destinations 필드를 사용하여 대략적인 보고를 사용 설정하고 노이즈를 줄일 수 있습니다. coarse_event_report_destinations 필드가 지정된 소스가 기여도를 부여받으면 결과 보고서에는 실제 트리거가 발생한 위치를 구분하지 않고 앱과 웹 대상이 모두 포함되지만 앱 또는 웹 대상이 지정된 보고서보다 노이즈가 적습니다.
    • 집계 보고서는 변경되지 않습니다.

Chrome 맞춤 탭을 사용하는 앱의 경우

일부 앱은 맞춤 탭을 사용하여 웹 콘텐츠를 렌더링할 수 있습니다. 맞춤 탭은 앱과 모바일 웹사이트에서 측정할 때 일반 웹페이지와 유사하게 작동합니다.

  1. 앱 소스 및 맞춤 탭 트리거를 등록합니다.

  2. 맞춤 탭 소스 및 앱 트리거를 등록합니다.

  3. CCT 소스 및 CCT 트리거 등록

WebView를 사용하는 앱

일부 앱은 WebView를 사용하여 콘텐츠를 표시할 수 있습니다. 광고 렌더링, 웹 콘텐츠 호스팅, 웹 형식에 더 적합한 맞춤 앱 기능 등 WebView의 사용 사례는 다양합니다.

  1. WebView에서 Attribution Reporting API를 사용하도록 허용하려면 임베딩 앱을 올바른 권한으로 구성해야 합니다.

  2. WebView에서는 OS 수준 기여 분석만 사용할 수 있습니다. Attribution-Reporting-Support 헤더는 Android Attribution Reporting API를 사용할 수 있는 경우에만 os만 반환합니다.

  3. OS에 위임할 때 WebView는 registerSource 또는 registerWebSource 및 registerTrigger 또는 registerWebTrigger를 사용할 수 있습니다. WebView에서 사용하는 메서드는 WebView를 렌더링하는 앱에서 설정하며 WebView별로 결정됩니다.

    • registerSource와 registerWebSource의 차이는 게시자로 로깅되는 소스입니다. registerSource를 사용하면 앱이 게시자로 로깅됩니다. registerSource를 사용해야 하는 경우의 예로는 WebView를 사용하여 렌더링된 광고를 표시하는 게시자 앱이 있습니다. registerWebSource를 사용하면 WebView에 호스팅된 웹사이트가 게시자로 로깅됩니다. registerWebSource를 사용해야 하는 경우의 예는 WebView를 호스팅하는 앱과 WebView에서 렌더링 중인 웹사이트에 광고가 표시되는 경우입니다. registerTrigger와 registerWebTrigger는 비슷하게 동작합니다. 3번 항목의 차트에는 앱 또는 SDK 개발자가 registerSource 또는 registerWebSource 및 registerTrigger 또는 registerWebTrigger를 사용하도록 API를 구성해야 하는 다양한 시나리오가 자세히 설명되어 있습니다.
    • 기본적으로 WebView는 Android Attribution Reporting API를 호출할 때 registerSource 및 registerWebTrigger를 사용합니다. 이를 통해 소스를 앱과 연결하고 트리거가 발생할 때 WebView의 URL 최상위 출처와 트리거를 연결합니다.

      • 앱에 다른 동작이 필요한 경우 androidx.webkit.WebViewSettingsCompat 클래스의 새 메서드 setAttributionRegistrationBehavior를 사용해야 합니다. 이 메서드는 WebView가 registerSource()나 registerTrigger()가 아닌 registerWebSource() 또는 registerWebTrigger()를 호출해야 하는지 지정합니다.

      • 이 동작은 시작된 각 WebView에 대해 설정해야 합니다.

      • 광고 기술 SDK가 WebView를 시작하는 경우 SDK에서 이 기본 동작을 설정해야 합니다.

      • registerWebSource()를 사용하여 소스 등록을 앱 대신 WebView의 웹사이트와 연결하려는 앱은 WebView 허용 목록에 추가되어야 합니다. 허용 목록에 가입하려면 이 양식을 작성하세요. 허용 목록의 목적은 웹 컨텍스트의 신뢰 설정과 관련된 개인 정보 보호 고려사항을 완화하는 것입니다.

      값 설명 사용 사례
      APP_SOURCE_AND_WEB_TRIGGER(기본값) 앱이 WebView에서 앱 소스(앱 패키지 이름과 연결된 소스) 및 웹 트리거(eTLD+1과 연결된 트리거)를 등록할 수 있도록 허용합니다. WebView를 사용하여 웹 탐색을 사용 설정하기보다 광고를 게재하는 앱
      WEB_SOURCE_AND_WEB_TRIGGER 앱이 WebView에서 웹 소스 및 웹 트리거를 등록하도록 허용합니다. 광고 노출 및 전환이 WebView의 웹사이트에서 모두 발생할 수 있는 WebView 기반 브라우저 앱
      APP_SOURCE_AND_APP_TRIGGER 앱이 WebView에서 앱 소스 및 앱 트리거를 등록하도록 허용합니다. 광고 노출 및 전환이 항상 WebView의 eTLD+1이 아니라 앱과 연결되어야 하는 WebView 기반 앱
      사용 중지됨 WebView에서 소스 및 트리거 등록을 사용 중지합니다.
    1. WebView에서 소스 및 트리거 등록

    2. 광고 기술은 Attribution-Reporting-Register-OS-Source 헤더를 사용하여 소스 등록에 응답해야 합니다. WebView에 설정된 동작에 따라 OS에서 registerSource() 또는 registerWebSource()를 호출하고 Android Attribution Reporting API에서 광고 기술 URI로 보조 API 호출을 시작합니다.

      • 소스 등록을 완료하려면 광고 기술의 엔드포인트가 응답 헤더를 사용하여 Android Attribution Reporting API 요청에 응답해야 합니다.
       Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}

    3. 나머지 소스 등록은 동일하게 유지됩니다.

    4. 광고 기술은 Attribution-Reporting-Register-OS-Trigger 헤더를 사용하여 트리거 등록에 응답해야 합니다. WebView에 설정된 동작에 따라 OS에서 registerTrigger() 또는 registerWebTrigger()를 호출하고 Rb에서 광고 기술 URI로 보조 API 호출을 시작합니다.

    5. 트리거 등록을 완료하려면 광고 기술의 엔드포인트가 응답 헤더를 사용하여 Android Attribution Reporting API 요청에 응답해야 합니다.

    Attribution-Reporting-Register-OS-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}

디버그

앱을 웹 구현으로 설정할 때는 디버그 보고서를 설정하여 소스와 트리거가 올바르게 등록되는지 확인하고 등록되지 않은 경우 그 이유에 관한 정보를 받는 것이 좋습니다.

일반적인 Attribution Reporting 디버깅 단계는 디버깅 레시피를 참고하세요.