소개
이 API는 개인 정보 보호 및 메시지 탭에서 제공하는 메시지와 상호작용하는 도구를 제공합니다. 콘솔을 사용하여 다음을 할 수 있습니다.
- 특정 사용자에 대한 메시지를 표시하지 않음
- 사용자의 광고 차단 상태 쿼리
- 사용자가 동의를 취소할 수 있도록 허용 (해당하는 경우)
이러한 도구를 통해 일부 업계 표준 프로토콜을 사용하여 사용자 동의를 수집할 수도 있습니다.
- IAB TCF v2 사양을 사용한 GDPR 동의
- IAB GPP CPRA 사양을 사용한 CPRA 선택 해제
이러한 경우 동의 상태는 해당 API를 통해 전달됩니다.
다음과 같은 두 가지 방법으로 사이트에 이 사용자 메시지 기능을 배포할 수 있습니다.
- 대부분의 경우 태그를 다시 지정할 필요가 없습니다. 메시지가 관련 제품에 게시되면 기존 Google 게시자 태그 또는 애드센스 태그를 통해 사용자 메시지가 배포됩니다.
- 광고 차단 해제 요청 메시지를 사용하는 경우 페이지에 광고 차단 태그를 명시적으로 추가해야 합니다. 자세한 내용은 Ad Manager 및 AdSense 태그 안내를 참고하세요.
googlefc는 사용자 메시지 기능이 JavaScript Window의 API에 사용하는 전역 네임스페이스입니다.
필드 요약
| 이름 | 유형 | 정의 |
|---|---|---|
googlefc.controlledMessagingFunction
|
function(!Object) | 메시지를 진행할지 여부를 결정하는 함수입니다. 이 기능은 모든 메시지 유형에서 지원됩니다. |
googlefc.callbackQueue
|
!Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue | 사용자 메시지 쿼리의 비동기 실행을 위한 콜백 큐에 대한 참조입니다. |
googlefc.CallbackQueue
|
객체 | 콜백 큐 객체의 유형입니다. |
googlefc.AdBlockerStatusEnum
|
!Object<문자열, 숫자> | 사용자의 광고 차단 프로그램 상태를 나타내는 열거형입니다. |
googlefc.AllowAdsStatusEnum
|
!Object<문자열, 숫자> | 사용자의 광고 허용 상태를 나타내는 열거형입니다. |
googlefc.ccpa.InitialCcpaStatusEnum
|
!Object<문자열, 숫자> | 사용자의 초기 CPRA 상태를 나타내는 열거형입니다. |
googlefc.ccpa.overrideDnsLink
|
undefined|boolean | 맞춤 판매 거부 링크를 사용하기 위해 true로 설정할 수 있는 불리언입니다. |
메서드 요약
| 이름 | 반환 유형 | 정의 |
|---|---|---|
googlefc.showRevocationMessage()
|
정의되지 않음 |
동의 기록을 지우고 googlefc 스크립트를 새로고침하여 사용자에게 적용되는 동의 메시지를 표시합니다.
|
googlefc.getAdBlockerStatus()
|
숫자 |
사용자의 광고 차단 상태에 따라 AdBlockerStatusEnum의 값을 반환합니다.
|
googlefc.getAllowAdsStatus()
|
숫자 |
사용자의 광고 허용 상태에 따라 AllowAdsStatusEnum의 값을 반환합니다.
|
googlefc.ccpa.getInitialCcpaStatus()
|
숫자 |
사용자의 초기 CPRA 상태에 따라 InitialCcpaStatusEnum의 값을 반환합니다.
|
googlefc.ccpa.openConfirmationDialog(function(boolean))
|
정의되지 않음 | 기본 판매 안함 링크가 재정의된 경우 CPRA 확인 대화상자를 엽니다. |
사이트에서 테스트 및 디버깅
개인 정보 보호 및 메시지는 특정 메시지 (또는 메시지 조합)가 실제 사이트에서 어떻게 표시되는지 확인할 수 있는 디버깅 및 테스트 기능을 제공합니다.
기본 요건:
- 미리 보려는 메시지는 테스트 대상 사이트에 게시되어야 합니다.
다음 디버깅 URL 매개변수를 사용하여 사이트에서 실시간 미리보기를 볼 수 있습니다.
| 디버그 매개변수 | 허용되는 값 |
|---|---|
fc |
alwaysshow (디버그/미리보기 모드 트리거용) |
fctype |
ab (광고 차단 메시지), ccpa (CPRA 거부 메시지), gdpr (GDPR 동의 메시지), monetization (Offerwall 메시지) |
이를 사용하여 사이트 (foo.com)에서 미리 보는 방법의 예:
- CPRA 메시지 테스트 --
http://foo.com/?fc=alwaysshow&fctype=ccpa - GDPR 메시지 테스트 --
http://foo.com/?fc=alwaysshow&fctype=gdpr
필드: 설명 및 예시
googlefc.controlledMessagingFunction {function(!Object)}
메시지 표시 여부를 결정하는 함수입니다. 구독자 상태 또는 페이지 URL과 같은 게시자 지정 조건에서 메시지 렌더링을 제어하는 데 사용할 수 있습니다.
다른 스크립트를 로드하기 전에 창에서 googlefc.controlledMessagingFunction를 정의하면 message.proceed(boolean)를 호출할 때까지 메시지가 표시되지 않습니다. message.proceed(true)를 호출하면 메시지를 평소와 같이 진행할 수 있지만 message.proceed(false)를 호출하면 페이지 조회에 메시지가 표시되지 않습니다.
예: 로그인한 사용자가 구독자인지 확인하는 비동기 함수 determineIfUserIsSubscriber()를 정의하는 페이지에 이 스크립트가 있다고 가정해 보겠습니다.
<head>
<script>
window.isSubscriber = undefined;
function determineIfUserIsSubscriber() {
if (isSubscriber !== undefined) {
return isSubscriber;
}
return new Promise(resolve => {
setTimeout(() => {
// Change this to true if you want to test what subscribers would see.
window.isSubscriber = false;
resolve(window.isSubscriber);
}, 1000);
});
}
</script>
</head>
다음은 googlefc.controlledMessagingFunction를 사용하여 비구독자에게만 메시지를 표시하는 방법의 예입니다.
<head>
<script>
// Define googlefc and the controlled messaging function on the Window.
window.googlefc = window.googlefc || {};
googlefc.controlledMessagingFunction = async (message) => {
// Determine if the user is a subscriber asynchronously.
const isSubscriber = await determineIfUserIsSubscriber();
if (isSubscriber) {
// If the user is a subscriber, don't show any messages.
message.proceed(false);
} else {
// Otherwise, show messages as usual.
message.proceed(true);
}
}
</script>
</head>
또한 이 기능이 확장되어 Offerwall 비공개 베타 버전에 참여하는 게시자가 Offerwall만 억제하도록 지정할 수 있습니다. 이 기능이 적용되어도 다른 메시지 유형은 영향을 받지 않습니다.
Offerwall 관련 제어 메시지는 추가 매개변수를 googlefc.MessageTypeEnum 유형의 Array인 message.proceed()에 전달하여 실행됩니다.
예: 다음은 다른 메시지 유형을 억제하지 않고 구독자에 대한 Offerwall 제공만 표시하지 않도록 googlefc.controlledMessagingFunction를 사용하는 예입니다.
<head>
<script>
// Define googlefc and the controlled messaging function on the Window.
window.googlefc = window.googlefc || {};
googlefc.controlledMessagingFunction = async (message) => {
// Determine if the Offerwall should display or not.
const shouldDisplayOfferwall = await determineIfUserIsSubscriber();
const applicableMessageTypes = [];
if (!shouldDisplayOfferwall) {
// Do not show the Offerwall, but allow other message types to display.
applicableMessageTypes.push(window.googlefc.MessageTypeEnum.OFFERWALL);
message.proceed(false, applicableMessageTypes);
} else {
// Otherwise, show messages as usual.
message.proceed(true);
}
}
</script>
</head>
메시지 관련 호출의 비동기 실행을 위한 전역 콜백 큐에 대한 참조입니다. 함수를 호출하는 지원되는 유일한 방법은 함수를 callbackQueue에 추가하는 것입니다.
서로 다른 유형의 데이터를 서로 다른 시점에 사용할 수 있으므로 다음 문자열 중 하나를 키로, 실행할 함수를 값으로 사용하여 함수를 맵으로 추가해야 합니다.
지원되는 키:
| 키 이름 | 사용량 | 상대적 지연 시간 |
|---|---|---|
CONSENT_API_READY
|
CONSENT_API_READY 키를 사용하여 콜백 대기열에 푸시된 함수는 지원되는 동의 프레임워크의 API가 정의되고 호출 가능할 때 실행됩니다. 이 시점부터 이후에 추가된 CONSENT_API_READY 키 함수의 실행은 동기식입니다. 프레임워크별 세부정보는 IAB 프레임워크 섹션을 참조하세요.
|
낮음 |
CONSENT_DATA_READY
|
CONSENT_DATA_READY 키를 사용하여 콜백 대기열에 푸시된 함수는 지원되는 동의 프레임워크에서 수집된 사용자 동의가 알려진 경우 (이전 실행에서 또는 사용자가 동의 메시지와 상호작용한 후) 실행됩니다. 이 시점부터 이후에 추가된 CONSENT_DATA_READY 키 함수의 실행은 동기식입니다.
|
높음 |
AD_BLOCK_DATA_READY
|
흐름에서 광고 차단 데이터를 사용할 수 있게 되면 AD_BLOCK_DATA_READY 키를 사용하여 콜백 큐로 푸시되는 함수가 실행됩니다. 이 시점부터 이후에 추가되는 AD_BLOCK_DATA_READY 키 함수의 실행은 동기식입니다.
|
높음 |
INITIAL_CCPA_DATA_READY
|
INITIAL_CCPA_DATA_READY를 사용하여 콜백 큐로 푸시된 함수는 흐름에서 CPRA 데이터를 사용할 수 있게 될 때 실행됩니다. 이후에 CPRA 데이터를 요청하려면 미국 개인 정보 보호 API (__uspapi)를 직접 호출하여 가져와야 합니다.
|
보통 |
googlefc.CallbackQueue {!Object}
메서드 요약:
| 이름 | 유형 | 매개변수 | 반환 유형 | 역할 |
|---|---|---|---|---|
push(data)
|
숫자 |
data: 키를 데이터 가용성 유형 중 하나로, 실행할 자바스크립트 함수 값을 포함하는 키-값 쌍입니다.
허용되는 데이터 가용성 키는 CONSENT_API_READY, CONSENT_DATA_READY, AD_BLOCK_DATA_READY, INITIAL_CCPA_DATA_READY입니다.
|
지금까지 추가된 명령어 수 그러면 배열의 현재 길이가 반환됩니다. | 전달된 함수를 데이터를 사용할 수 있게 된 순서대로 이러한 함수가 대기열에 추가된 순서대로 실행합니다. |
예:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.ccpa = window.googlefc.ccpa || {}
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback on the callbackQueue.
googlefc.callbackQueue.push({
'AD_BLOCK_DATA_READY':
() => {
if (googlefc.getAdBlockerStatus() == googlefc.AdBlockerStatusEnum.NO_AD_BLOCKER) {
// Handle a non-ad blocking user.
}
}
});
</script>
googlefc.AdBlockerStatusEnum {!Object<string, number>}
사용자의 다양한 광고 차단 상태를 나타냅니다. 상태는 다음과 같습니다.
googlefc.AdBlockerStatusEnum = {
// Something failed, in an unknown state.
UNKNOWN: 0,
// The user was running an extension level ad blocker.
EXTENSION_AD_BLOCKER: 1,
// The user was running a network level ad blocker.
NETWORK_LEVEL_AD_BLOCKER: 2,
// The user was not blocking ads.
NO_AD_BLOCKER: 3,
};
googlefc.AllowAdsStatusEnum {!Object<string, number>}
사용자의 다양한 광고 차단 광고 허용 상태를 나타냅니다. 상태는 다음과 같습니다.
googlefc.AllowAdsStatusEnum = {
// Something failed, in an unknown state.
UNKNOWN: 0,
// User is currently using an ad blocker, was never using an ad blocker, or
// allowed ads, but not because they saw the Privacy & messaging message.
ADS_NOT_ALLOWED: 1,
// User is no longer using an ad blocker after seeing the ad blocking message.
ADS_ALLOWED: 2,
};
googlefc.ccpa.InitialCcpaStatusEnum{!Object<string, number>}
사용자의 다양한 광고 차단 광고 허용 상태를 나타냅니다. 상태는 다음과 같습니다.
googlefc.ccpa.InitialCcpaStatusEnum = {
// Something failed, in an unknown state.
UNKNOWN: 0,
// CPRA does not apply to this user.
CCPA_DOES_NOT_APPLY: 1,
// CPPA applies to this user, and the user has not opted out yet.
NOT_OPTED_OUT: 2,
// CPPA applies to this user, and the user has opted out.
OPTED_OUT: 3,
};
googlefc.ccpa.overrideDnsLink{undefined|boolean}
기본 판매 거부 링크를 숨기고 맞춤 판매 거부 링크를 사용하려면 이 필드를 true로 설정합니다.
예:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.ccpa = window.googlefc.ccpa || {}
// Signals that the default DNS link will be overridden.
googlefc.ccpa.overrideDnsLink = true;
</script>
방법: 설명 및 예시
googlefc.getConsentStatus(): {number}
googlefc.getConsentedProviderIds(): {!Array<string>}
- 이제 호출 시 항상 빈 목록이 반환됩니다.
googlefc.showRevocationMessage(): {undefined}
현재 동의 기록을 삭제하고 이 사용자에게 적용되는 동의 메시지를 표시합니다. 이 함수에 지정해야 하는 키는 CONSENT_DATA_READY입니다.
예:
<button type="button" () => googlefc.showRevocationMessage()});">
Click here to revoke
</button>
googlefc.getAdBlockerStatus(): {number}
사용자의 광고 차단 상태에 따라 AdBlockerStatusEnum의 값을 반환합니다. 이 함수에 지정해야 하는 키는 AD_BLOCK_DATA_READY입니다.
예:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.ccpa = window.googlefc.ccpa || {}
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback on the callbackQueue.
googlefc.callbackQueue.push({
'AD_BLOCK_DATA_READY':
() => {
switch (googlefc.getAdBlockerStatus()) {
case googlefc.AdBlockerStatusEnum.EXTENSION_LEVEL_AD_BLOCKER:
case googlefc.AdBlockerStatusEnum.NETWORK_LEVEL_AD_BLOCKER:
// Insert handling for cases where the user is blocking ads.
break;
case googlefc.AdBlockerStatusEnum.NO_AD_BLOCKER:
// Insert handling for cases where the user is not blocking ads.
break;
case googlefc.AdBlockerStatusEnum.UNKNOWN:
// Insert handling for unknown cases.
break;
}
}
});
</script>
googlefc.getAllowAdsStatus(): {number}
사용자의 광고 허용 상태에 따라 AllowAdsStatusEnum의 값을 반환합니다. 이 함수에 지정해야 하는 키는 AD_BLOCK_DATA_READY입니다.
예:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.ccpa = window.googlefc.ccpa || {}
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback on the callbackQueue.
googlefc.callbackQueue.push({
'AD_BLOCK_DATA_READY':
() => {
switch (googlefc.getAllowAdsStatus()) {
case googlefc.AllowAdsStatusEnum.ADS_NOT_ALLOWED:
// Insert handling for cases where the user has not allowed ads.
// The user may have never been an ad blocker.
break;
case googlefc.AllowAdsStatusEnum.ADS_ALLOWED:
// Insert handling for cases where the user saw the ad blocking
// message and allowed ads on the site.
break;
case googlefc.AllowAdsStatusEnum.UNKNOWN:
// Insert handling for unknown cases.
break;
}
}
});
</script>
googlefc.ccpa.getInitialCcpaStatus(): {number}
사용자의 CPRA 상태에 따라 InitialCcpaStatusEnum의 값을 반환합니다. 이 함수에 지정해야 하는 키는 INITIAL_CCPA_DATA_READY입니다. CPRA 데이터에 관한 후속 요청은 US Privacy API (__uspapi)를 직접 호출하여 가져와야 합니다.
예:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.ccpa = window.googlefc.ccpa || {}
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback on the callbackQueue.
googlefc.callbackQueue.push({
'INITIAL_CCPA_DATA_READY':
() => {
switch (googlefc.ccpa.getInitialCcpaStatus()) {
case googlefc.ccpa.InitialCcpaStatusEnum.CCPA_DOES_NOT_APPLY:
// Insert handling for cases where the user is not CPRA eligible.
break;
case googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT:
// Insert handling for cases where the user is CPRA eligible and has
// not opted out.
break;
case googlefc.ccpa.InitialCcpaStatusEnum.OPTED_OUT:
// Insert handling for cases where the user is CPRA eligible and has
// opted out.
break;
}
}
});
</script>
googlefc.ccpa.openConfirmationDialog(function(boolean)): {undefined}
기본 판매 거부 링크가 재정의된 경우 CPRA 확인 대화상자를 엽니다. 사용자가 확인 대화상자와 상호작용하면 제공된 콜백 함수는 사용자가 선택 해제하면 true를 통해 호출되고 그러지 않으면 false로 호출됩니다.
예:
<script>
// This callback will be called with the user CPRA decision.
const ccpaCompletionCallback = (userOptedOut) => {
// Insert handling for user opt-out status here.
}
// Invoke the CPRA confirmation dialog when the user clicks the link.
document.getElementById("your-custom-ccpa-do-not-sell-link").addEventListener(
"click", () => googlefc.ccpa.openConfirmationDialog(ccpaCompletionCallback));
</script>
GDPR용 IAB TCF v2와 함께 Google 동의 관리 솔루션 사용
IAB TCF v2 프레임워크에 따라 Google 동의 관리 솔루션을 사용하여 GDPR 동의를 수집하는 경우 IAB TCF v2 API를 사용해야 합니다.
CONSENT_API_READY 콜백 큐 키를 사용하여 IAB TCF v2 API가 페이지에 정의된 경우에만 상응하는 콜백이 호출되도록 할 수 있습니다. 이는 IAB TCF v2 API의 'addEventListener' 명령어와 함께 사용해야 합니다.
예:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback using the CONSENT_API_READY key on the callbackQueue.
window.googlefc.callbackQueue.push({
'CONSENT_API_READY':
() => __tcfapi('addEventListener', 2.2, (data, success) => {
// Do something with consent data value; this callback may be invoked
// multiple times as user completes consent flow.
})
});
</script>
CONSENT_DATA_READY
콜백 큐 키를 사용하여 IAB TCF v2 API를 사용하여 사용자 동의를 수집하고 액세스할 수 있을 때만 해당하는 콜백이 호출되도록 할 수 있습니다.
이는 'addEventListener' 명령어와 함께 사용할 수 있습니다. TCF v2가 이 사용자에게 적용되는 한 제공된 콜백의 첫 번째 호출에서 제공된 데이터에 사용자의 동의 선택사항이 포함됩니다. TCF v2.2가 출시되면서
'getTCData'
명령어가 지원 중단되었습니다.
예:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback using the CONSENT_DATA_READY key on the callbackQueue.
window.googlefc.callbackQueue.push({
'CONSENT_DATA_READY':
() => __tcfapi('addEventListener', 2.2, (data, success) => {
// Do something with consent data value; this callback may be invoked
// multiple times if user consent selections change.
})
});
</script>
CPRA용 IAB GPP 프레임워크와 함께 Google 동의 관리 솔루션 사용하기
Google 동의 관리 솔루션을 사용하여 IAB GPP 프레임워크에서 CPRA 선택 해제를 수집하는 경우 IAB GPP API를 사용해야 합니다.
CPRA 규정의 거부 특성으로 인해 CONSENT_API_READY 또는 CONSENT_DATA_READY 콜백 큐 키를 사용하여 콜백이 호출될 때 IAB GPP API가 호출 가능하고 동의 데이터를 반환하도록 할 수 있습니다.
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.ccpa = window.googlefc.ccpa || {}
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback on the callbackQueue.
window.googlefc.callbackQueue.push({
'CONSENT_DATA_READY':
() => __uspapi('getUSPData', 1, (data, success) => {
// Do something with consent data value.
})
});
</script>
맞춤 판매 안함 링크가 있는 CPRA용 IAB GPP 프레임워크와 함께 Google 동의 관리 솔루션 사용
Google 동의 관리 솔루션을 사용하여 IAB GPP 프레임워크에서 CPRA 선택 해제를 수집하는 경우 googlefc.ccpa.overrideDnsLink 플래그를 true로 설정하여 맞춤 판매 안함 링크를 제공할 수 있습니다.
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.ccpa = window.googlefc.ccpa || {}
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Signals that the default DNS link will be overridden.
window.googlefc.ccpa.overrideDnsLink = true;
// Register the callback for the initial CPRA data.
window.googlefc.callbackQueue.push({
'INITIAL_CCPA_DATA_READY': () => {
if (googlefc.ccpa.getInitialCcpaStatus() ===
googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT) {
// TODO: Display custom CPRA Do Not Sell link here.
}
}
});
</script>
이렇게 하면 기본 Do Not Sell(판매 안함) 링크가 렌더링되지 않습니다. CPRA를 준수하기 위해 자체 판매 거부 링크를 렌더링할 책임은 개발자에게 있습니다. 그런 다음 CPRA 확인 대화상자를 호출하여 맞춤 판매 거부 링크와의 사용자 상호작용을 처리해야 합니다.
<script>
// This callback will be called with the user CPRA decision.
const ccpaCompletionCallback = (userOptedOut) => {
if (userOptedOut) {
// TODO: Hide custom CPRA Do Not Sell link here.
}
}
// Invoke the CPRA confirmation dialog when the user clicks the link.
document.getElementById("your-custom-ccpa-do-not-sell-link").addEventListener(
"click", () => googlefc.ccpa.openConfirmationDialog(ccpaCompletionCallback));
</script>