이 페이지는 Cloud Translation API를 통해 번역되었습니다.

잠재고객 데이터 정의

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일로 제한합니다. 연속적인 호출은 이전에 저장된 값을 덮어씁니다.

핵심사항: Protected Audience API 메서드의 매개변수로 사용되는 모든 URL은 안전한 출처에서 가져와야 합니다. 모든 리소스는 HTTPS URL을 통해 제공되어야 합니다. 로컬 개발에 HTTPS를 사용하는 방법에서는 Protected Audience API를 로컬에서 실행할 때 이를 사용하는 방법을 설명합니다. 또한 biddingLogicUrl, decisionLogicUrl, trustedBiddingSignals에는 X-Allow-FLEDGE: true HTTP 응답 헤더가 필요합니다.

필수 속성

관심분야 그룹에는 owner 및 name 속성만 필요합니다.

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

선택 속성

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

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

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

² 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 reference guides are available:

Developer guide for the Protected Audience API.
Ad buyer guide to Protected Audience interest groups and bid generation.
Ad seller guide to Protected Audience ad auctions.
Guide to reporting auction results
Best practices for Protected Audience ad auction latency
Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.