Protected Audience API 입찰 보고

Protected Audience API 입찰 데이터 및 결과 측정

이 도움말에서는 Protected Audience API 입찰 데이터를 서버에 보고하는 데 사용할 수 있는 다양한 메커니즘과 대체 솔루션이 준비될 때까지 이전 중에 사용할 수 있는 전환 메커니즘을 간략하게 설명합니다.

광고 입찰에서 수집하는 중요한 측정항목을 보고하기 위해 Protected Audience API는 다음과 함께 작동합니다.

• 비공개 집계: 입찰 신호와 결과를 수집하여 요약 보고서를 생성합니다.
• Protected Audience API 워크렛과 통신하기 위한 프레임 내의 채널인 Fenced Frames 및 iframe용 Ads Reporting API API를 사용하면 이벤트 수준 데이터를 입찰 신호와 연결할 수 있습니다. Ads Reporting API의 이벤트 수준 보고는 비공개 보고 메커니즘이 설계될 때까지의 전환 메커니즘입니다.
• 기여도 보고서: 전환 데이터를 입찰 신호와 연결할 수 있습니다.
• 공유 스토리지: 교차 출처 스토리지에 입찰 신호를 작성한 후 나중에 비공개 집계를 사용하여 해당 데이터를 보고할 수 있습니다.

Protected Audience API 보고 개요

</ph>

Protected Audience API 입찰 흐름의 데이터가 서버에 보고될 수 있는 주요 기간은 세 가지입니다. 게시자 사이트에서 입찰이 실행될 때의 입찰 시점, 광고가 게시자 사이트의 분리 프레임 또는 iframe으로 렌더링될 때의 렌더링 시간, 사용자가 입찰로 간주될 수 있는 다른 사이트에서 특정 액션을 수행할 때의 전환 시간입니다.

입찰 시간 동안 보고 워크렛을 사용하여 입찰 데이터를 보고할 수 있습니다. 렌더링 시간 동안 iframe 또는 분리 프레임에서 참여 데이터를 보고할 수 있습니다. 전환 시간 동안 Attribution Reporting API를 사용하여 도착 페이지에서 기여 분석 데이터를 보고할 수 있습니다.

보고 위치

입찰 내에서 구매자는 generateBid() 및 reportWin() Worklet에서 사용 가능한 신호를 보고할 수 있고, 판매자는 scoreAd() 및 reportResult()에서 사용 가능한 신호를 보고할 수 있습니다. 입찰 외부에서 구매자와 판매자는 광고를 렌더링한 프레임과 전환이 발생한 사이트의 데이터를 보고할 수 있습니다.

표시된 각 기간 동안 구매자와 판매자는 입찰 신호, 이벤트 수준 데이터, 전환 데이터와 같은 데이터를 보고하는 데 사용할 수 있는 다양한 보고서 API에 액세스할 수 있습니다.

Protected Audience API 입찰 내에서 이용 가능한 데이터

다음 데이터는 입찰 중에 Protected Audience API Worklet에서 보고될 수 있습니다.

신호

신호는 Worklet 내에서 구매자와 판매자가 입찰을 생성하고, 광고에 점수를 매기고, 입찰 결과를 보고하는 데 사용할 수 있는 입찰 문맥 데이터, 사용자 데이터, 실시간 데이터, 브라우저 데이터입니다.

입찰 구성 객체는 Worklet에서 신호로 사용할 수 있도록 제공되는 데이터의 기본 소스입니다. 게시자와 판매자는 입찰 구성에서 문맥 데이터와 퍼스트 파티 데이터를 제공할 수 있으며, 이러한 신호는 구매자의 관심분야 그룹 데이터, 광고 렌더링 프레임의 이벤트 수준 데이터, 클릭연결 페이지의 기여 분석 데이터로 보강될 수 있습니다. 보고된 데이터는 구매자/판매자 보고, 청구, 예산, ML 모델 학습 등에 사용할 수 있습니다.

기타 사용 가능한 데이터

• 결과 데이터: 낙찰가, 입찰 거부 사유 등 입찰 성공 및 실패 데이터와 관련된 데이터입니다.
• 입찰 Worklet을 가져오고 실행하는 데 걸린 시간 등의 지연 시간 정보가 포함된 실적 데이터입니다.

Protected Audience API 입찰 외부에서 사용 가능한 데이터

Protected Audience API 입찰 외에도 데이터가 보고될 수 있는 기간이 두 개 있습니다.

렌더링 시간 동안 광고가 게시자 사이트에서 렌더링되면 iframe 또는 분리 프레임 내의 이벤트 수준 데이터가 Protected Audience API 입찰 데이터와 연결되고 서버에 보고될 수 있습니다. 이벤트 수준 데이터의 예로는 광고 노출, 클릭률, 마우스 오버 및 프레임 내에서 발생하는 기타 이벤트가 포함됩니다.

전환 시간 동안 사용자가 클릭연결 페이지에서 입찰로 다시 인정된 작업을 수행하면 전환 페이지의 이벤트 수준 데이터가 Protected Audience API 입찰 데이터와 연결되어 서버에 보고될 수 있습니다.

이벤트 수준 보고

이벤트 수준 보고서는 하나 이상의 이벤트에 관한 세부정보를 제공합니다. 이벤트는 입찰 낙찰, 광고 노출 또는 전환일 수 있습니다. 최소 2026년까지, 이벤트 수준 입찰 낙찰 보고는 그대로 유지되며, Protected Audience 광고를 렌더링하는 데 분리 프레임이 필요하지 않으며, 네트워크 액세스가 제한되지 않은 iframe을 이벤트 수준 보고에 사용할 수 있습니다. 또한 Ads Reporting API는 분리 프레임 및 iframe에서 사용할 수 있으며, 이를 통해 입찰 및 전환 데이터를 프레임의 이벤트 수준 데이터와 연결할 수 있습니다. 시스템을 Protected Audience로 이전하는 동안 적어도 2026년까지는 기존 보고 인프라를 계속 사용할 수 있으므로 생태계에서 더 쉽게 이전할 수 있도록 설계되었습니다.

sendReportTo()를 사용한 이벤트 수준 입찰 낙찰 보고

Protected Audience 입찰 내에서 이벤트 수준 데이터를 보고하는 데 사용할 수 있는 메커니즘은 입찰에서 낙찰된 sendReportTo() function입니다. 이 함수는 구매자 및 판매자 보고 워크릿에서 사용할 수 있으며, 광고 렌더링이 시작되면 브라우저가 제공된 URL 문자열에 GET 요청을 합니다. 워크릿에서 사용 가능한 모든 신호를 URL의 쿼리 매개변수로 인코딩할 수 있습니다.

예를 들어 구매자는 청구 목적으로 reportWin() 워크릿에서 낙찰가를 보고할 수 있습니다.

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

sendReportTo() 함수는 reportResult()에서 호출될 때 판매자의 낙찰 보고서를 생성하고 reportWin()에서 호출될 때 구매자에 관한 낙찰 보고서를 생성하는 데 사용할 수 있습니다. sendReportTo() 함수는 적어도 2026년까지 사용할 수 있습니다.

참여도 보고서

참여 보고서에는 광고를 렌더링한 Protected Audience API 입찰의 신호와 연결된 노출 또는 클릭 데이터와 같은 광고 소재의 이벤트 수준 데이터가 포함됩니다. 입찰이 종료된 후에 광고가 렌더링되므로 광고를 렌더링하는 프레임 내에서는 입찰 신호를 사용할 수 없습니다. 서로 다른 기간의 데이터를 연결하기 위해 참여도 보고서를 생성하는 두 가지 전환 메커니즘을 제공합니다.

위에서 설명한 sendReportTo() 함수는 입찰 데이터를 iframe의 이벤트 수준 데이터와 연결하는 데 사용할 수 있지만 분리 프레임에서는 작동하지 않습니다. 이는 임베딩에서 고유 ID를 전달할 수 없기 때문입니다. 임베딩과 분리 프레임 간의 통신이 제한되어 있기 때문입니다. 입찰 데이터를 분리 프레임 광고의 이벤트 수준 데이터와 연결하려면 Ads Reporting API를 사용하면 됩니다.

분리 프레임 및 iframe용 Ads Reporting API

분리 프레임 및 iframe을 위한 Ads Reporting API는 광고 프레임의 사용자 이벤트 수준 데이터를 Protected Audience 입찰 내의 신호와 연결하는 메커니즘을 제공합니다.

Protected Audience API 보고 워크렛에서는 registerAdBeacon() 함수를 사용하여 광고 비콘을 등록하고, 쿼리 매개변수로 추가된 신호를 사용하여 보고 URL을 전달할 수 있습니다. 또한 보고 URL과 연결할 맞춤 이벤트를 지정합니다. 그런 다음 나중에 광고가 분리 프레임에서 렌더링될 때 window.fence.reportEvent() 함수를 호출하여 맞춤 이벤트를 트리거할 수 있습니다. 분리 프레임 내에서 제공되는 데이터는 페이로드로 추가될 수 있습니다.

registerAdBeacon() 함수는 보고 함수에서만 사용할 수 있으며 구매자의 입찰 로직 및 판매자의 점수 로직에서는 사용할 수 없습니다.

다음 예에서는 캠페인 ID가 클릭 좌표가 있는 이벤트 수준 페이로드와 연결됩니다.

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

Fenced Frames Ads Reporting API는 낙찰 보고와 동일한 이유로 최소 2026년까지도 사용할 수 있습니다.

자세한 내용은 설명서를 참고하세요.

무제한 네트워크 액세스

분리(Fenced) 프레임을 사용하면 iframe과 같은 방식으로 네트워크 리소스를 로드할 수 있으며, 분리 프레임 내의 이벤트 수준 데이터를 서버로 전송할 수 있습니다. 나중에 분리 프레임의 이벤트 수준 데이터를 위의 입찰 이벤트 수준 보고 메커니즘 섹션에서 설명한 sendReportTo()와 함께 전송된 입찰 데이터와 연결하여 서버 측에서 이벤트 수준 보고서를 생성할 수 있습니다.

향후 네트워크 액세스가 제한될 예정입니다.

기여 분석 보고서

기여도 보고서를 사용하면 웹사이트의 전환을 Protected Audience API 입찰에서 선택된 광고와 연결할 수 있습니다. 예를 들어, 사용자가 게재 중인 제품 광고를 클릭하여 광고주 사이트로 리디렉션되어 그곳에서 구매를 하고, 광고주는 게재된 광고가 구매의 원인이라는 데 관심이 있을 수 있습니다. Attribution Reporting API가 Protected Audience API와 통합되어 게시자 사이트의 입찰 데이터와 광고주 사이트의 전환 데이터를 결합합니다.

Google에서 보다 영구적인 솔루션을 설계하는 동안, 분리 프레임에는 Ads Reporting API를 사용하여 Attribution Reporting을 통해 이벤트 수준의 집계 가능한 보고서를 생성하기 위한 전환 메커니즘으로 사용할 수 있습니다. 이러한 보고서는 전환 측정을 위한 것이며 입찰 및 광고 프레임에서 생성된 이벤트 수준의 집계 가능한 참여도 보고서와는 별개입니다. 준비가 되면 보다 영구적인 해결 방법에 대한 설명을 게시할 예정입니다.

전환 메커니즘

광고 비콘을 등록할 때 reserved.top_navigation 키워드를 사용하면 비콘이 기여 분석 소스로 등록할 수 있도록 비콘의 Attribution-Reporting-Eligible 헤더가 자동으로 추가됩니다.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

등록한 비콘에 이벤트 수준 데이터를 첨부하려면 이벤트 페이로드와 함께 분리 프레임에서 setReportEventDataForAutomaticBeacons()를 호출하면 됩니다.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

자세한 내용은 Ads Reporting API 설명의 Attribution Reporting 섹션을 참고하세요.

참여 및 전환 보고의 예

이 예에서는 입찰, 광고 프레임 및 전환 사이트의 데이터를 서로 연결하려는 구매자의 관점에서 살펴보겠습니다.

이 워크플로에서 구매자는 판매자와 협력하여 입찰에 고유 ID를 전송합니다. 입찰 중에 구매자는 이 고유 ID를 입찰 데이터와 함께 전송합니다. 렌더링 및 전환 시간 동안 분리 프레임 또는 iframe의 데이터도 동일한 고유 ID로 전송됩니다. 나중에 이 고유 ID를 사용하여 이러한 보고서를 함께 연결할 수 있습니다.

워크플로:

1. 입찰이 시작되기 전에 구매자는 프로그래매틱 실시간 입찰('RTB') 입찰 응답의 일부로 고유 ID를 판매자에게 전송합니다. ID는 auctionId와 같은 변수로 설정할 수 있습니다. ID는 auctionConfig에서 perBuyerSignals로 전달되며 구매자의 워크렛에서 사용할 수 있게 됩니다.
2. 입찰 시간에 구매자는 광고 렌더링 시간 및 전환 시간 (registerAdBeacon()) 중에 트리거되도록 광고 비콘을 등록할 수 있습니다. <ph type="x-smartling-placeholder">
   </ph>
   1. 광고 프레임 이벤트의 입찰 신호를 연결하려면 비콘 URL의 쿼리 매개변수로 auctionId를 설정합니다.
   2. 전환 이벤트의 입찰 신호를 연결하려면 비콘 URL에서 auctionId를 설정합니다.
3. 광고 렌더링 시간 동안 입찰 시 등록한 비콘은 이벤트 수준 데이터로 트리거되거나 개선될 수 있습니다.
   1. reportEvent()로 프레임 이벤트를 트리거하고 이벤트 수준 데이터를 전달합니다.
   2. setReportEventDataForAutomaticBeacons()를 사용하여 기여 분석 비콘에 이벤트 수준 페이로드 추가
   3. Attribution-Reporting-Register-Source 헤더로 광고 비콘 요청에 응답하여 Attribution Reporting API에 광고를 등록합니다.
4. 전환 시간 동안 입찰 시간에 등록한 소스를 트리거할 수 있습니다.

위의 절차가 완료되면 구매자는 입찰 보고서, 참여 보고서, 전환 보고서를 갖게 되며, 서로 연결하는 데 사용할 수 있는 단일 고유 키로 모두 묶여 있습니다.

기여 분석 데이터에 액세스해야 하는 판매자에게도 유사한 워크플로가 적용되며, 판매자도 고유 ID를 사용하여 registerAdBeacon()와 함께 전송할 수 있습니다. 프레임에서 reportEvent() 호출에는 구매자와 판매자 모두에게 보고서를 전송하는 데 사용할 수 있는 대상 속성이 포함됩니다. 트리거가 소스에 기인하려면 방문 페이지에도 SSP가 있어야 합니다.

Protected Audience 데이터 집계

Private Aggregation API는 Protected Audience 데이터를 보고하여 버킷에서 수집된 데이터의 노이즈가 많은 집계 보고서인 요약 보고서를 생성하는 데 사용되는 메커니즘입니다. 버킷은 집계 키로 표시되며, 일부 정보는 키로 인코딩될 수 있습니다.

예를 들어 광고 노출 이벤트는 여러 버킷으로 집계될 수 있으며, 각 버킷은 서로 다른 광고 캠페인을 나타냅니다. 요약 보고서는 각 개별 이벤트에 대한 정보를 표시하지 않는다는 점에서 이벤트 수준 보고서와 다릅니다. 이벤트 수준 보고서를 사용하면 사용자 A, B, C가 캠페인 123을 조회했음을 확인할 수 있습니다. 요약 보고서를 사용하면 캠페인 123을 본 사용자 수를 측정하고 사용자 개인 정보를 보호하기 위해 노이즈가 추가될 수 있습니다.

API에 대한 자세한 내용은 비공개 집계 문서를 참조하세요.

입찰 신호 집계

비공개 집계를 사용하여 워크렛 내에서 사용 가능한 신호를 서버에 집계할 수 있습니다. 신호 집계의 경우 구매자 입찰 Worklet, 판매자 점수 Worklet, 구매자/판매자 보고 워크릿에서 사용할 수 있는 privateAggregation.contributeToHistogram() 메서드를 사용할 수 있습니다.

이 예에서는 낙찰가가 관심분야 그룹 소유자 버킷으로 집계됩니다.

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

집계하려는 신호가 이벤트 수준 데이터와 연결되어 있지 않고 입찰 외부의 이벤트에 의해 트리거되지 않는 경우에 사용하는 일반적인 메커니즘입니다. 입찰 신호 보고에 대해 자세히 알아보려면 설명을 참조하세요.

이벤트 데이터로 입찰 신호 집계

광고 프레임에서 발생하는 이벤트에 대한 제한된 정보를 사용하여 입찰 신호를 집계할 수 있습니다. 예를 들어 해당 캠페인과 클릭 이벤트를 나타내는 버킷을 만들어 캠페인의 광고에서 발생한 클릭수를 집계할 수 있습니다. 광고 프레임에서 발생한 이벤트를 지정할 수 있지만 이벤트 수준 페이로드는 연결할 수 없습니다.

이벤트별로 입찰 신호를 집계하려면 이벤트 유형 및 이벤트가 트리거될 때 보고할 기여도를 지정하는 문자열을 사용하는 privateAggregation.contributeToHistogramOnEvent(eventType, contribution)를 사용하면 됩니다. 맞춤 이벤트 유형으로 메서드를 호출한 다음 광고 프레임에서 window.fence.reportEvent(eventType)를 호출하여 보고서 제출을 트리거할 수 있습니다.

캠페인 광고에서 발생한 클릭수를 측정하려 한다고 가정해 보겠습니다.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

입찰 생성 함수에서 캠페인 ID와 클릭 이벤트의 조합으로 버킷을 정의한 다음 이벤트가 트리거될 때마다 해당 버킷의 값을 1씩 증가시킬 수 있습니다.

// Ad frame
window.fence.reportEvent('click');

그런 다음 나중에 광고 프레임에서 reportEvent(eventType)를 호출하여 보고서 제출을 트리거할 수 있습니다.

설명서에서 프레임에서 비공개 집계 참여를 트리거하는 방법을 자세히 알아보세요.

입찰 결과 및 실적 보고

예약된 이벤트 유형 키워드 (reserved.win, reserved.loss 및 reserved.always)를 전달하면 contributeToHistogramOnEvent(eventType, contribution)를 사용하여 입찰 낙찰 또는 실패 이벤트에 의해 트리거될 때 입찰 결과를 집계할 수도 있습니다.

비공개 집계는 기여도의 버킷과 가치를 계산할 수 있는 기준값 목록을 제공합니다. 입찰 결과에 사용할 수 있는 기본값은 낙찰된 광고의 입찰가, 두 번째로 높은 입찰가, 입찰이 거부된 이유입니다.

낙찰가와 같은 일부 기준이 제공되면 해당 값에 더하거나 뺄 금액을 설정한 다음 최종 가치를 보고할 수 있습니다. 예를 들어 낙찰가 5,000원이 기준이면 입찰가인 2,000원을 빼서 입찰에서 낙찰받지 못한 금액의 실제 가치인 3,000원을 계산할 수 있습니다.

입찰 결과 보고

경매에서 낙찰에 실패한 예를 통해 입찰가가 경매 가격에서 얼마만큼 차이가 나는지 알아보려고 합니다.

입찰에서 낙찰받지 못한 금액을 확인하려면 낙찰가에서 입찰가를 빼면 됩니다.

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

보고서가 제출되면 실제로 보고되는 값은 offset 값으로 이동한 조정된 baseValue 값입니다. 자세한 내용은 설명을 참고하세요.

실적 보고서

구매자와 판매자는 스크립트를 실행하는 데 걸린 시간과 신뢰할 수 있는 신호를 가져오는 데 걸린 시간을 보고할 수 있습니다. 판매자는 허가를 받은 각 구매자의 입찰 생성 시간 및 신뢰할 수 있는 입찰 신호 시간을 수집할 수 있습니다.

자세한 내용은 설명을 참조하세요.

공유 저장소에 입찰 신호 저장

공유 저장소는 자유롭게 쓸 수 있는 파티션을 나누지 않은 교차 출처 저장소이지만, 저장된 값을 읽고 처리할 때 게이트로 보호됩니다. Shared Storage API에 사용할 수 있는 게이트 중 하나는 비공개 집계입니다. 워크릿 내에서만 공유 저장소의 값을 읽을 수 있으며, 워크릿의 비공개 집계를 사용하여 이러한 값을 보고할 수 있습니다.

Protected Audience API 입찰, 점수 산정, 보고 워크렛에서 공유 스토리지에 쓸 수도 있습니다. 나중에 비공개 집계 를 사용하여 공유 저장공간의 해당 값을 서버에 보고할 수 있습니다 . URL 선택 작업에 저장된 값을 사용할 수도 있습니다.

Protected Audience API Worklet에서 공유 스토리지에 모든 키와 값을 쓸 수 있습니다.

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

나중에 공유 저장소 Worklet을 로드하여 비공개 집계를 통해 해당 값을 읽고 전송할 수 있습니다.

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

공유 저장소에 관해 자세히 알아보려면 Protected Audience API 보고 개발자 가이드의 공유 저장소 섹션, 설명, 실시간 데모, GitHub의 데모 코드를 참고하세요.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.