이 문서에서는 Protected Audience API의 현재 반복에서 사용되는 단일 판매자의 Protected Audience 데이터로 입찰을 실행하는 방법에 관한 대략적인 개요를 보여줍니다. 판매자가 1명인 입찰은 여러 판매자가 관여하는 보다 복잡한 입찰의 일부로 실행할 수 있습니다. 이 경우 단일 판매자 입찰을 '구성요소 입찰'이라고 하며, 여러 판매자가 참여하는 '최상위 입찰'에 광고 조합을 제공할 수 있습니다.
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 입찰 실행
판매자가 입찰을 실행하기 위해 수행해야 하는 네 가지 주요 단계가 있습니다. 이 단계에서는 판매자가 앞에서 이 가이드에서 언급한 필수 JavaScript를 반환하도록 설정된 엔드포인트가 있다고 가정합니다.
- 입찰을 구성합니다. 이 단계에는
auctionConfig객체 만들기가 포함됩니다. 이를 통해 판매자는 입찰에 참여해야 하는 구매자를 지정하고 입찰 생성 또는 광고 점수 산정 중에 관련이 있을 수 있는 신호를 제공할 수 있습니다. navigator.runAdAuction()를 호출하여 입찰을 실행하고 이전 단계에서 만든 구성을 전달합니다. 이렇게 하면 입찰을 생성한 후 점수 산정을 위한 구매자 체인이 시작됩니다. 이 단계의 최종 결과는 광고를 표시하도록 렌더링할 수 있는 광고 조합입니다.- 분리 프레임 또는 iframe에서 낙찰된 광고를 렌더링합니다.
- 입찰 결과를 보고합니다. 보고를 시작하는
navigator.sendReportTo()함수가 있습니다. 판매자는 항상 입찰 결과의 보고서를 받습니다. 입찰에서 낙찰된 구매자만 보고서를 받게 됩니다. 그러면 이 가이드의 앞부분에서 설명한 판매자의reportResult()를 사용하여 서버에 보고합니다.