개인 정보 보호 및 메시지 자바스크립트 API

소개

이 API는 개인 정보 보호 및 메시지 탭에서 제공하는 메시지와 상호작용하는 도구를 제공합니다. 콘솔을 사용하여 다음을 할 수 있습니다.

  • 특정 사용자에 대해 메시지 차단
  • 사용자의 광고 차단 상태 쿼리하기
  • 사용자가 동의를 취소할 수 있도록 허용 (해당하는 경우)

다음 도구를 사용하여 일부 업계 표준 프로토콜을 사용하는 사용자 동의를 수집할 수도 있습니다.

이러한 경우 해당 API를 통해 동의 상태가 전달됩니다.

이 사용자 메시지 기능을 사이트에 배포하는 방법에는 두 가지가 있습니다.

  1. 대부분의 경우 태그를 다시 지정할 필요가 없습니다. 관련 제품에 메시지가 게시되면 기존 Google 게시자 태그 또는 애드센스 태그가 사용자 메시지를 배포합니다.
  2. 광고 차단 해제 요청 메시지를 사용하는 경우 페이지에 광고 차단 태그를 명시적으로 추가해야 합니다. 자세한 내용은 Ad Manager애드센스 태그 지정 안내를 참조하세요.

googlefc는 사용자 메시지 기능이 자바스크립트 Window에서 API에 사용하는 전역 네임스페이스입니다.

필드 요약

이름 유형 정의
googlefc.controlledMessagingFunction 함수(!Object) 메시지를 진행할지 여부를 결정하는 함수입니다. 이 기능은 모든 메시지 유형에서 지원됩니다.
googlefc.callbackQueue !Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue 사용자 메시지 쿼리의 비동기 실행을 위한 콜백 큐 참조
googlefc.CallbackQueue !객체 콜백 큐 객체의 유형입니다.
googlefc.AdBlockerStatusEnum !Object<문자열, 숫자> 사용자의 광고 차단 프로그램 상태를 나타내는 enum입니다.
googlefc.AllowAdsStatusEnum !Object<문자열, 숫자> 사용자의 광고 허용 상태를 나타내는 enum입니다.
googlefc.ccpa.InitialCcpaStatusEnum !Object<문자열, 숫자> 사용자 초기 CPRA 상태를 나타내는 열거형입니다.
googlefc.ccpa.overrideDnsLink 정의되지 않음|불리언 맞춤 판매 안함 링크를 사용하기 위해 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 (오퍼월 메시지)

이를 사용하여 사이트 (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>

오퍼월 비공개 베타에 참여하는 게시자는 message.proceed()에 추가 매개변수를 제공하여 오퍼월만 표시하지 않도록 지정할 수 있습니다. 이 매개변수는 googlefc.MessageTypeEnum 유형의 Array입니다. 현재 지원되는 유일한 enum은 OFFERWALL이지만 향후 메시지 유형이 추가될 수 있습니다.

예: 위와 동일한 determineIfUserIsSubscriber() 함수가 있다고 가정합니다. 다음은 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>

googlefc.callbackQueue {!Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue}

메시지 관련 호출의 비동기 실행을 위한 전역 콜백 큐 참조 함수를 호출하는 유일한 방법은 함수를 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 데이터에 관한 후속 요청은 US Privacy 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>}

  1. 이제 호출하면 항상 빈 목록이 반환됩니다.

googlefc.showRevocationMessage(): {undefined}

현재 동의 기록을 지우고 이 사용자에게 적용되는 동의 메시지를 표시합니다. 이 함수에 지정해야 하는 키는 CONSENT_DATA_READY입니다.

예:

<button type="button" onclick="googlefc.callbackQueue.push({'CONSENT_DATA_READY': () => 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>

Google TCF 관리 솔루션을 사용하여 IAB TCF v2 프레임워크에 따른 GDPR 동의를 수집하는 경우 IAB TCF v2 API를 사용해야 합니다.

CONSENT_API_READY

콜백 대기열 키를 사용하여 페이지에서 IAB TCF v2 API가 정의된 경우에만 해당 콜백이 호출되도록 해야 합니다. 동기식 'getTCData' 명령어를 사용하여 가져온 사용자 동의가 아직 제공되지 않을 수 있으므로 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.0, (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를 사용하여 사용자 동의를 수집하고 액세스할 수 있는 경우에만 콜백이 호출됩니다. 동기 메서드를 사용하여 사용자의 동의 상태를 가져올 수 있으므로 '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('getTCData', 2.0, (data, success) => {
      // Do something with consent data value.
    })
  });
</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>

이렇게 하면 기본 판매 안함 링크가 렌더링되지 않습니다. 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>