판매자 가이드: 광고 입찰 실행

Protected Audience API 광고 입찰을 위한 판매자 API 가이드 및 참조입니다.

이 도움말에서는 현재 실험용 Protected Audience API에 사용되는 광고 입찰에 대한 기술 참조를 확인할 수 있습니다.

Protected Audience API의 전체 수명 주기는 개발자 가이드를 참고하고 판매자가 기기 내 입찰을 실행하는 방식에 관한 자세한 내용은 Protected Audience API 설명을 참고하세요.

개발자가 아니신가요? Protected Audience API 개요를 참고하세요.

Protected Audience API 광고 입찰이란 무엇인가요?

Protected Audience API 광고 입찰은 브라우저가 사용자 기기에서 광고를 선택하기 위해 실행하는 소규모 JavaScript 프로그램의 모음입니다. 개인 정보 보호를 위해 판매자와 구매자의 모든 광고 입찰 코드는 외부와 통신할 수 없는 격리된 JavaScript 워크렛에서 실행됩니다.

Protected Audience API 광고 입찰의 6단계
이 다이어그램은 Protected Audience API 광고 입찰의 각 단계를 간략히 보여줍니다.
  1. 사용자가 광고가 게재되는 사이트를 방문합니다.
  2. 판매자의 코드는 navigator.runAdAuction()를 실행합니다. 이를 통해 판매할 광고 공간과 입찰할 수 있는 사용자를 지정할 수 있습니다. 또한 판매자는 각 입찰의 점수를 매기는 스크립트 scoreAd()도 포함해야 합니다.
  3. 초대된 구매자의 코드가 실행되어 입찰가, 관련 광고 소재의 URL 및 기타 데이터를 생성합니다. 입찰 스크립트는 구매자의 키/값 서비스에서 남은 광고 캠페인 예산과 같은 실시간 데이터를 쿼리할 수 있습니다.
  4. 판매자의 코드가 각 입찰의 점수를 매기고 낙찰자를 선택합니다. 이 로직은 입찰가를 사용하고 기타 데이터는 입찰가의 타당성을 반환합니다. 문맥상의 낙찰자를 이길 수 없는 광고는 거부됩니다. 판매자는 실시간 데이터에 자체 키/값 서비스를 사용할 수 있습니다.
  5. 낙찰된 광고는 분리된 프레임에 표시되는 불투명 값으로 반환됩니다. 판매자와 게시자 모두 이 값을 볼 수 없습니다.
  6. 판매자와 낙찰자에게 입찰이 보고됩니다.

입찰은 언제 진행되나요?

Protected Audience API는 단독으로 또는 프로그래매틱 입찰과 함께 실행할 수 있습니다. 다중 판매자 프로그래매틱 입찰에서는 다음과 같은 특징이 있습니다.

  1. 사용자가 참여 사이트를 방문합니다.
  2. 프로그래매틱 입찰은 사용 가능한 광고 슬롯에 대한 문맥 광고를 찾기 위해 다른 판매자가 실행합니다.
  3. Protected Audience API 입찰이 실행됩니다.
  4. scoreAd()구매자의 입찰가를 첫 번째 입찰의 결과와 비교합니다.

문맥상 낙찰자보다 더 높은 입찰가를 제시할 수 없는 입찰은 거부됩니다.

Protected Audience API 광고 입찰은 누가 진행하나요?

광고 공간을 판매하기 위해 입찰을 실행하는 업체는 여러 가지가 있습니다.

예를 들면 다음과 같습니다.

  • 콘텐츠 게시자: 웹사이트에 광고 콘텐츠를 호스팅하기 위해 스스로 행위합니다.
  • 공급측 플랫폼 (SSP): 게시자와 협력하고 기타 서비스를 제공합니다.
  • 서드 파티 스크립트: 광고 입찰에 참여할 수 있도록 게시자를 대행합니다.

Protected Audience API를 사용하는 판매자는 다음 세 가지 작업을 할 수 있습니다.

  • 게시자 규칙 적용: 대상 구매자 및 입찰 가능
  • 입찰 로직을 실행합니다. 워크렛에서 실행되는 JavaScript는 각 입찰의 호감도 점수를 계산합니다.
  • 입찰 결과를 보고합니다.

이러한 작업은 JavaScript 함수 navigator.runAdAuction()를 호출하여 광고 입찰을 시작할 때 판매자가 제공하는 코드에서 프로그래매틱 방식으로 실행됩니다.

API 함수

runAdAuction()

판매자는 navigator.runAdAuction()를 호출하여 사용자의 브라우저에 광고 입찰을 시작하도록 요청합니다.

예를 들면 다음과 같습니다.

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction()는 광고 입찰 결과를 나타내는 URN (urn:uuid:<something>)으로 확인되는 프로미스를 반환합니다. 이는 렌더링을 위해 분리된 프레임에 전달될 때만 브라우저에서 디코딩될 수 있습니다. 게시자 페이지에서는 낙찰된 광고를 검사할 수 없습니다.

decisionLogicUrl 스크립트는 연결된 입찰가 및 메타데이터와 함께 각 개별 광고를 한 번에 하나씩 고려한 다음 광고에 수치적 호감도 점수를 할당합니다.

숙박 시설 auctionConfig개

seller
필수
예: 'https://ssp.example'
역할: 판매자의 출처입니다.
decisionLogicUrl
필수
예: 'https://ssp.example/auction-decision-logic.js'
역할: 입찰 Worklet 자바스크립트의 URL입니다.
trustedScoringSignalsUrl
선택사항
예: 'https://ssp.example/scoring-signals'
역할: 판매자의 신뢰할 수 있는 서버의 URL입니다.
interestGroupBuyers
필수
예: ['https://dsp.example', 'https://buyer2.example', ...]
역할: 입찰에 참여를 요청한 모든 관심분야 그룹 소유자의 출처입니다.
참고: 판매자는 interestGroupBuyers:를 지정하여 모든 관심분야 그룹의 입찰을 허용할 수 있습니다. 그런 다음 관심분야 그룹 소유자 포함 이외의 기준에 따라 광고가 승인되거나 거부됩니다. 예를 들어 판매자는 광고 소재를 검토하여 정책을 준수하는지 확인할 수 있습니다.
auctionSignals
선택사항
예: {...}
역할: 페이지 컨텍스트, 입찰 유형 등에 대한 판매자 정보
sellerSignals
선택사항
예: {...}
역할: 게시자 설정, 문맥 광고 요청 등에 기반한 정보
sellerTimeout
선택사항
예: 100
역할: 판매자의 scoreAd() 스크립트의 최대 런타임 (밀리초)입니다.
perBuyerSignals
선택사항
예: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
역할: 서버에서 각 특정 구매자의 페이지에 대한 문맥 시그널입니다.
perBuyerTimeouts
선택사항
예: 50
역할: 특정 구매자의 generateBid() 스크립트의 최대 런타임 (밀리초)입니다.
componentAuctions
선택사항
예: 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
역할: 구성요소 입찰의 추가 구성.

decisionLogicUrl

decisionLogicUrl는 runAdAuction()에 전달되는 입찰 구성 객체의 속성입니다. 이 URL에는 scoreAd() 함수의 스크립트가 포함되어야 합니다. 이 로직은 각 광고에 한 번씩 실행되어 광고 게재 여부가 결정됩니다.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals는 브라우저에서 구성한 객체로, 브라우저가 알고 있는 정보 및 판매자의 입찰 스크립트에서 인증하려고 하는 정보를 포함합니다.

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

입찰을 시작하기 전에 판매자는 사용 가능한 광고 슬롯에 가장 적합한 문맥 광고를 찾습니다. scoreAd() 로직의 일부가 문맥상 낙찰자를 이길 수 없는 모든 광고를 거부합니다.

scoreAd()

scoreAd()는 다음 인수를 사용합니다.

인수 역할
adMetadata 구매자가 제공한 임의 메타데이터입니다.
auctionConfig navigator.runAdAuction()에 전달되는 입찰 구성 객체입니다.
bid 숫자로 된 입찰가입니다.
trustedScoringSignals 입찰 시 판매자의 신뢰할 수 있는 서버에서 가져온 값으로, 광고에 대한 판매자의 의견을 나타냅니다.

자주 묻는 질문(FAQ)

경매 낙찰자는 어떻게 결정되며 누가 선정되나요?

판매자는 각 광고의 호감도 점수를 결정하는 점수 로직을 제공하고 브라우저가 가장 높은 점수를 낙찰 광고로 선택합니다.

판매자는 scoreAd() 함수에 로직을 포함하고, 브라우저는 외부 코드와의 통신이 제한된 Worklet에서 함수를 실행합니다. 브라우저 자체는 광고의 점수를 매기지 않습니다. 점수 로직을 실행하고 점수가 가장 높은 입찰가를 선택하는 것은 전적으로 브라우저에서 책임집니다.

모든 Protected Audience API 참조

다음과 같은 API 참조 가이드를 이용할 수 있습니다.

Protected Audience API 설명에서는 기능 지원 및 제약조건에 대한 세부정보도 제공합니다.