잠재고객 데이터 정의

Protected Audience API를 사용해 관심분야 그룹을 만들어 잠재고객을 정의하는 방법을 알아봅니다. Protected Audience API의 전체 수명 주기는 개발자 가이드를 참고하고 브라우저에서 관심분야 그룹을 기록하는 방법에 관한 자세한 제안은 Protected Audience API 설명을 참고하세요.

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

Protected Audience API 관심분야 그룹

Protected Audience API 관심분야 그룹은 리마케팅 목록에 해당하는 공통 관심분야를 가진 사용자 그룹을 나타냅니다. 모든 Protected Audience API 관심분야 그룹에는 소유자가 있습니다.

관심분야 그룹 소유자는 Protected Audience API 광고 입찰에서 구매자 역할을 합니다. 관심분야 그룹 멤버십은 브라우저에 의해 및 사용자 기기에 저장되며 브라우저 공급업체 또는 다른 누구와도 공유되지 않습니다.

API 함수

joinAdInterestGroup()

광고주의 수요측 플랫폼 (DSP) 또는 광고주 자체에서 navigator.joinAdInterestGroup()를 호출하여 브라우저에 브라우저의 멤버십 목록에 관심분야 그룹을 추가하도록 요청합니다.

joinAdInterestGroup()에 대한 호출 컨텍스트의 출처는 관심분야 그룹 소유자의 출처와 일치해야 합니다. 따라서 관심분야 그룹 소유자의 출처가 현재 문서의 출처 (예: 자체 관심분야 그룹이 있는 웹사이트)와 일치하지 않는 한 iframe (예: DSP)에서 joinAdInterestGroup()를 호출해야 합니다.

joinAdInterestGroup()에 다음 권한 필요:

즉, dsp.example.com에 권한을 부여하지 않으면 malicious.example이(가) dsp.example.com 소유의 관심분야 그룹에 대해 joinAdInterestGroup()을(를) 호출할 수 없습니다.

방문한 사이트의 허가

동일한 출처 또는 교차 출처에서 권한을 부여할 수 있습니다. 기본적으로 권한은 방문한 사이트와 동일한 출처(즉, 현재 페이지의 최상위 프레임과 동일한 출처)에서 발생한 joinAdInterestGroup() 호출에 대해 부여됩니다.

사용 예시

다음은 사용자가 관심분야 그룹을 정의하고 브라우저에 그룹에 가입하도록 요청하는 방법에 대한 예입니다.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

함수에 전달되는 interestGroup 객체의 크기는 50KiB 이하여야 합니다. 그렇지 않으면 호출이 실패합니다. 두 번째 매개변수는 관심분야 그룹의 기간을 지정하며, 최대 기간은 30일입니다. 연속 호출은 이전에 저장된 값을 덮어씁니다.

필수 속성

관심분야 그룹에 필요한 속성은 owner 및 name뿐입니다.

속성 예 역할
owner https://dsp.example 관심분야 그룹 소유자의 출처입니다.
name custom-bikes 관심분야 그룹의 이름입니다.

선택 속성

나머지 속성은 선택사항입니다.

biddingLogicUrl1, 2
예: https://dsp.example/bid/custom-bikes/bid.js
역할: Worklet에서 실행되는 입찰 JavaScript용 URL.
biddingWasmHelperUrl1, 2
예: https://dsp.example/bid/custom-bikes/bid.wasm
역할: biddingLogicUrl에서 구동된 WebAssembly 코드의 URL.
updateUrl2
예: https://dsp.example/bid/custom-bikes/update
역할: 관심분야 그룹 속성을 업데이트하기 위해 JSON을 반환하는 URL입니다. (잠재고객 데이터 업데이트 및 광고 새로고침 참조).
trustedBiddingSignalsUrl2
예: https://dsp.example/trusted/bidding-signals
역할: 입찰자의 신뢰할 수 있는 키/값 서비스에 대한 키-값 요청의 기본 URL입니다.
trustedBiddingSignalsKeys
예: ['key1', 'key2' ...]
역할: 신뢰할 수 있는 키-값 서비스 요청에 대한 키입니다.
userBiddingSignals
예: {...}
역할: 소유자가 입찰 중에 사용할 수 있는 추가 메타데이터입니다.
ads1
예: [bikeAd1, bikeAd2, bikeAd3]
역할: 이 관심분야 그룹에 대해 렌더링될 수 있는 광고입니다.
adComponents
예: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]
역할: 여러 조각으로 구성된 광고의 구성요소.

1 biddingLogicUrl 및 ads 속성은 선택사항이지만 입찰에 참여하려면 필수입니다. 이러한 속성이 없는 관심분야 그룹을 만드는 사용 사례가 있을 수 있습니다. 예를 들어, 관심분야 그룹 소유자가 아직 운영되지 않은 캠페인 또는 다른 향후 사용을 위해 관심분야 그룹에 브라우저를 추가하거나 일시적으로 광고 예산이 소진되었을 수 있습니다.

2 현재 Protected Audience API 구현에서 biddingLogicUrl, biddingWasmHelperUrl, updateUrl, trustedBiddingSignalsUrl는 소유자와 동일한 출처를 가져야 합니다. 이는 장기적인 제약 조건이 아닐 수 있으며, ads 및 adComponents URL에는 이러한 제약 조건이 없습니다.

관심분야 그룹에 대한 광고 지정

ads 및 adComponents 객체에는 광고 소재의 URL과 선택적으로 입찰 시 사용할 수 있는 임의의 메타데이터가 포함됩니다.

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

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

leaveAdInterestGroup()

관심분야 그룹 소유자는 관심분야 그룹에서 브라우저를 삭제하도록 요청할 수 있습니다. 브라우저가 멤버십 목록에서 관심분야 그룹을 삭제합니다.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

사용자가 브라우저에 관심분야 그룹 추가를 요청한 사이트를 다시 방문하면 관심분야 그룹 소유자는 navigator.leaveAdInterestGroup() 함수를 호출하여 브라우저에서 관심분야 그룹을 삭제하도록 요청할 수 있습니다.

광고 코드는 해당 관심분야 그룹에 대해서도 이 함수를 호출할 수 있습니다.

자주 묻는 질문(FAQ)

단일 사용자에 대한 그룹 소유자당 최대 관심분야 그룹의 수는 몇 개인가요?

Chrome에서는 소유자당 최대 1,000개의 관심분야 그룹과 최대 1,000명의 관심분야 그룹 소유자를 지정할 수 있습니다. 이러한 제한은 가드레일 역할을 하며 일반적인 작동 시에는 준수되지 않습니다.

k-anon 기준을 충족하는 관심분야 그룹 광고를 최대화하려면 어떻게 해야 하나요?

공개 설명에서 언급했듯이, 단일 관심분야 그룹에는 표시될 수 있는 여러 개의 광고가 포함될 수 있으므로, 가장 선호되는 선택이 기준점 미만일 때마다 그룹은 다른 광고 중 '대체 광고' 역할을 하도록 다시 입찰할 수 있습니다. 즉, 여전히 k-익명성 기준점에 미치지 못하는 소규모 특수 광고도 입찰에 참여하도록 선택할 수 있으며, 관심분야 그룹은 더 전문화된 광고의 잠재고객이 충분히 커질 때까지 보다 일반적인 광고로 대체할 수 있습니다.

전술적 관점에서 다음을 고려할 수 있습니다.

  • 새 광고를 게재하려면 광고를 게재하고 싶은 경우에 광고를 게재하기만 하면 됩니다. 별도로 취해야 할 조치는 없습니다.
  • 새 광고가 k-anon이 아닌 경우 사용할 대체 광고를 만들 수 있습니다. 대체 광고 자체가 k-anon이 될 위험이 있으므로 애초에 대체 광고로 입찰하는 것을 고려해 볼 수 있습니다. 예를 들어 대체가 기준점을 넘어설 것으로 예상할 수 있는 수준이라면 1% 의 확률로 이 단계를 반복하세요.

최근의 다른 작동 방식에 관한 논의가 있었으므로 이 메커니즘으로 인해 문제가 될 수 있는 사용 사례가 있다면 API를 개선할 수 있는 방법에 관한 공개 대화에 계속 참여해 주세요.

모든 Protected Audience API 참조

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

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