이 문서에서는 현재 버전의 Protected Audience API에서 사용되는 것처럼 단일 판매자의 Protected Audience 데이터로 입찰을 실행하는 방법을 대략적으로 설명합니다. 단일 판매자가 참여하는 입찰은 여러 판매자가 참여하는 더 복잡한 입찰의 일부로 실행될 수 있습니다. 이 경우 단일 판매자 입찰은 '구성요소 입찰'이라고 하며, 이는 여러 판매자가 참여하는 '최상위 입찰'에 광고 후보를 제공할 수 있습니다.
Protected Audience API의 전체 수명 주기에 관한 내용은 개발자 가이드를 참고하고, 판매자가 기기 내 입찰을 실행하는 방법에 관한 자세한 내용은 Protected Audience API 설명을 참고하세요.
Protected Audience API 광고 입찰의 6단계
- 사용자가 광고를 게재하는 사이트를 방문합니다.
- 판매자의 코드가
navigator.runAdAuction()를 실행합니다. 여기에서 판매할 광고 공간과 입찰할 수 있는 사용자를 지정합니다. 판매자는 각 입찰에 점수를 부여하는 스크립트인scoreAd()도 포함해야 합니다. - 초대된 구매자의 코드가 실행되어 입찰가, 관련 광고 소재의 URL, 기타 데이터를 생성합니다. 입찰 스크립트는 구매자의 키/값 서비스에서 잔여 광고 캠페인 예산과 같은 실시간 데이터를 쿼리할 수 있습니다.
- 판매자의 코드는 각 입찰가에 점수를 매기고 낙찰자를 선택합니다. 이 로직은 입찰가 값과 입찰가의 선호도를 반환하는 기타 데이터를 사용합니다. 문맥 낙찰자를 이길 수 없는 광고는 거부됩니다. 판매자는 실시간 데이터에 자체 키/값 서비스를 사용할 수 있습니다.
- 낙찰된 광고는 불투명 값으로 반환되며 울타리 프레임에 표시됩니다. 판매자와 게시자 모두 이 값을 볼 수 없습니다.
- 입찰 결과가 판매자와 낙찰자에게 보고됩니다.
사용자가 광고가 게재되는 페이지로 이동할 때 입찰이 진행될 수 있습니다. 광고 슬롯이 표시될 때 광고 소재가 준비되도록 사전에 입찰이 실행될 수 있습니다.
판매자는 광고 입찰을 시작하고 scoreAd() 함수로 제공된 맞춤 로직을 사용하여 조합 광고에 점수를 매기며 입찰 결과를 본인과 낙찰된 구매자에게 보고해야 합니다. 판매자는 scoreAd() 함수를 사용하여 게시자 규칙을 시행하고 광고 품질을 필터링할 수도 있습니다.
판매자는 다음을 참조할 수 있습니다.
- 웹사이트에 광고 콘텐츠를 호스팅하기 위해 자체적으로 행동하는 콘텐츠 게시자
- 광고 게시자와 협력하고 기타 서비스를 제공하는 공급측 플랫폼 (SSP)
- 게시자를 대신하여 광고 입찰에 참여하도록 하는 서드 파티 스크립트입니다.
입찰 실행을 위한 기본 요건
판매자는 입찰을 실행하기 위해 정의된 두 개의 JavaScript 함수가 필요합니다.
- 광고 후보의 점수를 부여하는
scoreAd() reportResult(): 입찰 결과를 판매자에게 직접 보고하는 작업을 처리합니다.
이러한 스크립트는 판매자가 소유한 단일 엔드포인트에서 제공되어야 합니다.
scoreAd()
판매자는 소유한 엔드포인트에서 제공되는 scoreAd() 함수를 정의해야 합니다. 엔드포인트는 입찰 구성에서 decisionLogicUrl로 지정됩니다. scoreAd() 함수의 서명은 다음과 같습니다.
scoreAd(
adMetadata,
bid,
auctionConfig,
trustedScoringSignals,
browserSignals,
directFromSellerSignals)
scoreAd() 매개변수는 다음과 같습니다.
adMetaData: 구매자가 제공하는 광고 소재에 관한 임의의 메타데이터입니다. 이는 판매자와 구매자가 구조를 정의하고 동의해야 하는 직렬화 가능한 JSON 객체입니다.bid: 입찰가를 나타내는 숫자 값입니다.auctionConfig: 입찰을 실행하는 데 사용되는 입찰 구성입니다.trustedScoringSignals: 판매자의 키/값 서버에서 입찰 시 읽은 신호입니다. 플랫폼은 조회 키로 조합 광고의renderUrl를 사용합니다.browserSignals: 브라우저가 생성한 객체로, 브라우저가 알고 있고 판매자의 입찰 스크립트에서 확인하고 싶어 하는 정보를 포함합니다.directFromSellerSignals는 다음 필드를 포함할 수 있는 객체입니다. **sellerSignals:auctionConfig.sellerSignals와 같지만directFromSellerSignals메커니즘을 사용하여 전달됩니다. **auctionSignals:auctionConfig.auctionSignals와 같지만directFromSellerSignals메커니즘을 사용하여 전달됩니다.
다음은 browserSignals의 예입니다. 조합 광고의 renderUrl는 다음 신호를 통해 사용할 수 있습니다.
{ 'topWindowHostname': 'www.example-publisher.com',
'interestGroupOwner': 'https://www.example-buyer.com',
'renderURL': 'https://cdn.com/render_url_of_bid',
'renderSize': {width: 100, height: 200}, /* if specified in the bid */
'adComponents': ['https://cdn.com/ad_component_of_bid',
'https://cdn.com/next_ad_component_of_bid',
...],
'biddingDurationMsec': 12,
'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}
reportResult()
판매자는 소유한 엔드포인트에서 제공되는 reportResult() 함수를 정의해야 합니다. 엔드포인트는 입찰 구성에서 decisionLogicUrl로 지정됩니다. reportResult() 함수의 서명은 다음과 같습니다.
reportResult(auctionConfig, browserSignals) {
...
return signalsForWinner;
}
reportResult() 매개변수는 다음과 같습니다.
auctionConfig: 입찰을 실행하는 데 사용되는 입찰 구성입니다.browserSignals: 브라우저가 생성한 객체로, 브라우저가 알고 있고 판매자의 입찰 스크립트에서 확인하고 싶어 하는 정보를 포함합니다. 이는scoreAds()함수에 전달된 것과 동일한 객체입니다.
reportResult()는 낙찰된 구매자의 보고 함수에 전달되는 임의의 JSON 객체인 signalsForWinner을 반환합니다. 여기에는 구매자가 보고에 필요한 입찰에 대해 판매자가 제공할 수 있는 관련 정보가 포함되어야 합니다.
Protected Audience API 입찰 실행
판매자가 입찰을 실행하려면 다음 4가지 주요 단계를 따라야 합니다. 이 단계에서는 판매자가 이전에 이 가이드에서 언급한 필수 JavaScript를 반환하도록 설정된 엔드포인트를 보유하고 있다고 가정합니다.
- 입찰을 구성합니다. 이 단계에는
auctionConfig객체를 만드는 작업이 포함됩니다. 이를 통해 판매자는 입찰에 참여해야 하는 구매자를 지정하고 입찰 생성 또는 광고 점수 산정 중에 관련성이 있을 수 있는 신호를 제공할 수 있습니다. - 이전 단계에서 만든 구성을 전달하여
navigator.runAdAuction()를 호출하여 입찰을 실행합니다. 그러면 입찰가를 생성한 후 점수를 매기는 구매자 체인이 시작됩니다. 이 단계의 최종 결과는 광고를 표시하기 위해 렌더링할 수 있는 광고 후보입니다. - 펜싱된 프레임 또는 iframe에서 낙찰된 광고를 렌더링합니다.
- 입찰 결과를 보고합니다. 보고를 시작하는 함수
navigator.sendReportTo()가 있습니다. 판매자는 항상 입찰 결과 보고서를 받습니다. 입찰에서 낙찰된 구매자만 보고서를 수신합니다. 이 방법에서는 이 가이드 앞부분에 설명된 판매자의reportResult()를 사용하여 서버에 보고합니다.