Gizlilik ve Mesajlaşma JavaScript API'sı

Giriş

Bu API, Gizlilik ve mesajlaşma sekmesinin sunduğu mesajlarla etkileşimde bulunmak için araçlar sağlar. Bu araçla şunları yapabilirsiniz:

  • belirli bir kullanıcı için mesajlaşmayı engelleme
  • kullanıcının reklam engelleme durumunu sorgulama
  • kullanıcının izni iptal etmesine izin ver (varsa)

Bu araçları, sektördeki bazı standart protokolleri kullanarak kullanıcı izni almak için de kullanabilirsiniz:

Bu durumlarda, izin durumu bu API'ler aracılığıyla iletilir.

Bu kullanıcı mesajlaşma işlevini sitenizde birkaç şekilde dağıtabilirsiniz:

  1. Çoğu durumda yeniden etiketleme yapmanız gerekmez. Mevcut Google Yayıncı Etiketi veya AdSense etiketi, mesaj alakalı üründe yayınlandıktan sonra kullanıcı mesajlarını dağıtır.
  2. Reklam engelleme iptali mesajını kullanıyorsanız reklam engelleme etiketini sayfanıza açıkça eklemeniz gerekir. Daha fazla bilgi için Ad Manager ve AdSense etiketleme talimatlarına bakın.

googlefc, kullanıcı mesajı işlevinin JavaScript'teki API'sinde Window kullandığı genel ad alanıdır.

Alan Özetleri

Ad Type Tanım
googlefc.controlledMessagingFunction İşlev(!Nesne) Herhangi bir mesajlaşma işlemine devam edilip edilmeyeceğini belirleyen bir işlev. Bu işlev tüm mesaj türleri için desteklenir.
googlefc.callbackQueue !Array<!Object<string, Functions()>> | !Array<Function()> | !googlefc.CallbackQueue Kullanıcı mesajlaşma sorgularının eşzamansız olarak yürütülmesi için geri çağırma sırasına referans.
googlefc.CallbackQueue !Nesne Geri çağırma sırası nesnesinin türü.
googlefc.AdBlockerStatusEnum !Object<dize, sayı> Kullanıcının reklam engelleyici durumunu temsil eden enum.
googlefc.AllowAdsStatusEnum !Object<dize, sayı> Kullanıcının izin verme durumunu temsil eden bir enum.
googlefc.ccpa.InitialCcpaStatusEnum !Object<dize, sayı> Kullanıcının ilk CPRA durumunu temsil eden bir enum.
googlefc.ccpa.overrideDnsLink tanımsız|boole Özel bir Satmayın bağlantısı kullanmak için doğru değerine ayarlanabilen bir boole değeridir.

Yöntem Özetleri

Ad Dönüş türü Tanım
googlefc.showRevocationMessage() tanımsız Kullanıcı için geçerli izin mesajını göstermek amacıyla izin kaydını temizler ve googlefc komut dosyasını yeniden yükler.
googlefc.getAdBlockerStatus() numara Kullanıcının reklam engelleme durumuna bağlı olarak AdBlockerStatusEnum içinde bir değer döndürür.
googlefc.getAllowAdsStatus() numara Kullanıcının reklamlara izin verme durumuna bağlı olarak AllowAdsStatusEnum içinde bir değer döndürür.
googlefc.ccpa.getInitialCcpaStatus() numara Kullanıcının ilk CPRA durumuna bağlı olarak InitialCcpaStatusEnum içinde bir değer döndürür.
googlefc.ccpa.openConfirmationDialog(function(boolean)) tanımsız Varsayılan satış yapma bağlantısı geçersiz kılınırsa CPRA onay iletişim kutusunu açar.

Sitenizde test ve hata ayıklama

Gizlilik ve mesajlaşma, belirli mesajların (veya mesaj kombinasyonlarının) gerçek sitenizde neye benzediğini görmenizi sağlayan hata ayıklama ve test etme işlevini sağlar.

Ön koşullar:

  • Önizlemek istediğiniz mesajlar, test ettiğiniz site altında yayınlanmalıdır

Aşağıdaki hata ayıklama URL parametrelerini kullanarak sitenizde canlı bir önizleme görebilirsiniz:

Hata ayıklama parametresi İzin verilen değerler
fc alwaysshow (hata ayıklama/önizleme modunu tetiklemek için)
fctype ab (Reklam engelleme mesajları), ccpa (CPRA devre dışı bırakma mesajları), gdpr (GDPR kullanıcı rızası alma mesajları), monetization (Teklif duvarı mesajları)

Sitenizde önizleme yapmak için bunu nasıl kullanacağınıza ilişkin bazı örnekler (foo.com):

  • CPRA test mesajları: http://foo.com?fc=alwaysshow&fctype=ccpa
  • GDPR mesajını test edin -- http://foo.com?fc=alwaysshow&fctype=gdpr

Alanlar: Açıklamalar ve örnekler

googlefc.controlledMessagingFunction {function(!Object)}

İletilerin gösterilip gösterilmeyeceğini belirleyen bir işlev. Yayıncı durumu tarafından (ör. abone durumu veya sayfa URL'si) oluşturulan mesajların oluşturulması için kullanılabilir.

Pencerede diğer komut dosyaları yüklenmeden önce googlefc.controlledMessagingFunction tanımladığınızda, siz message.proceed(boolean) çağrısı yapana kadar mesajlar gösterilmez. message.proceed(true) işlevinin çağrılması, mesajların her zamanki gibi işlenmesine, message.proceed(false) işlevinin çağrılması ise mesajların sayfa görüntüleme için gösterilmesini engeller.

Örnek: Giriş yapmış kullanıcının abone olup olmadığını kontrol eden bir eşzamansız işlevi (determineIfUserIsSubscriber()) tanımlayan sayfada bu komut dosyasının bulunduğunu varsayalım.

<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>

Bu, yalnızca abone olmayanlara mesajı göstermek için googlefc.controlledMessagingFunction etiketini nasıl kullanabileceğinize dair bir örnektir.

<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>

Fırsat duvarı kapalı beta sürümünün bir parçası olarak yayıncılar, message.proceed() için ek bir parametre sağlayarak yalnızca Fırsat duvarının atlanması gerektiğini belirtebilir. Bu parametre, googlefc.MessageTypeEnum türünde bir Array şeklindedir. Bugün desteklenen tek numara OFFERWALL ancak ileride daha fazla mesaj türü eklenebilir.

Örnek: Yukarıdakiyle aynı determineIfUserIsSubscriber() işlevine sahip olduğunuzu varsayalım. Bu, diğer mesaj türlerini engellemeden yalnızca abonelere teklif duvarı sunumunu engellemek için googlefc.controlledMessagingFunction kullanılmasıyla ilgili bir örnektir:

<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}

Mesajla ilgili çağrıların eşzamansız olarak yürütülmesi için genel geri çağırma sırasına referans. Herhangi bir işlevi çağırmak için desteklenen tek yöntem, işlevin callbackQueue işlevine eklenmesidir.

Farklı veri türleri farklı zamanlarda kullanılabilir hale geldiğinden, işlev olarak aşağıdaki dizelerden biri anahtar ve değer olarak yürütülecek işlev olarak harita olarak eklenmelidir.

Desteklenen anahtarlar:

Anahtar adı Kullanım Göreli gecikme
CONSENT_API_READY CONSENT_API_READY izniyle geri çağırma sırasına aktarılan işlevler, desteklenen izin çerçeveleri için API'ler tanımlanıp çağrılabildiğinde yürütülür. Bu noktadan itibaren, daha sonra eklenen CONSENT_API_READY anahtarlı işlevlerin yürütülmesi eşzamanlı olur. Çerçeveye özgü ayrıntılar için aşağıdaki IAB çerçeveleri ile ilgili bölümlere bakın. Düşük
CONSENT_DATA_READY Desteklenen bir izin çerçevesi kapsamında toplanan kullanıcı izni (önceki bir yürütmeden veya kullanıcı izin mesajıyla etkileşimde bulunduğunda) CONSENT_DATA_READY anahtarıyla geri çağırma sırasına aktarılan işlevler yürütülür. Bu noktadan itibaren, daha sonra eklenen CONSENT_DATA_READY anahtarlı işlevlerin yürütülmesi eşzamanlı olur. Yüksek
AD_BLOCK_DATA_READY Reklam engelleme verileri akışta kullanılabilir hale geldiğinde AD_BLOCK_DATA_READY anahtarıyla geri çağırma sırasına aktarılan işlevler yürütülür. Bu noktadan itibaren, daha sonra eklenen AD_BLOCK_DATA_READY anahtarlı işlevlerin yürütülmesi eşzamanlı olur. Yüksek
INITIAL_CCPA_DATA_READY CPRA verileri akışta kullanılabilir hale geldiğinde INITIAL_CCPA_DATA_READY ile geri çağırma sırasına aktarılan işlevler yürütülür. CPRA verileriyle ilgili sonraki isteklerin, doğrudan US Privacy API'yi (__uspapi) çağırarak elde edilmesi gerektiğini unutmayın. Aracı

googlefc.CallbackQueue {!Object}

Yöntem özeti:

Ad Type Parametre Dönüş türü Rol
push(data) numara data: Veri kullanılabilirlik türlerinden biri olarak anahtar, yürütülecek JavaScript işlevi olarak değer içeren anahtar/değer çifti. Kabul edilebilir veri kullanılabilirliği anahtarları şunlardır: CONSENT_API_READY, CONSENT_DATA_READY, AD_BLOCK_DATA_READY ve INITIAL_CCPA_DATA_READY. Şu ana kadar eklenen komutların sayısı. Bu, dizinin mevcut uzunluğunu döndürür. İletilen işlevi, verilerin kullanılabilir olma sırasına göre, ardından bu işlevlerin sıraya eklenme sırasına göre yürütür.

Örnek:

<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>}

Kullanıcının farklı reklam engelleme durumlarını gösterir. Farklı durumlar şunlardır:

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>}

Kullanıcının farklı reklam engelleme izin verme durumlarını temsil eder. Farklı durumlar şunlardır:

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>}

Kullanıcının farklı reklam engelleme izin verme durumlarını temsil eder. Farklı durumlar şunlardır:

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}

Varsayılan satış yapma bağlantısını gizlemek ve özel bir satmamanız için bu alanı doğru değerine ayarlayın.

Örnek:

<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>

Yöntemler: açıklamalar ve örnekler

googlefc.getConsentStatus(): {number}

googlefc.getConsentedProviderIds(): {!Array<string>}

  1. Bu komut artık çağrıldığında her zaman boş bir liste döndürüyor.

googlefc.showRevocationMessage(): {undefined}

Mevcut izin kaydını temizler ve bu kullanıcı için geçerli izin mesajını gösterir. Bu işlev için belirtilmesi gereken anahtar CONSENT_DATA_READY şeklindedir.

Örnek:

<button type="button" onclick="googlefc.callbackQueue.push({'CONSENT_DATA_READY': () => googlefc.showRevocationMessage()});">
  Click here to revoke
</button>

googlefc.getAdBlockerStatus(): {number}

Kullanıcının reklam engelleme durumuna bağlı olarak AdBlockerStatusEnum içinde bir değer döndürür. Bu işlev için belirtilmesi gereken anahtar AD_BLOCK_DATA_READY şeklindedir.

Örnek:

<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}

Kullanıcının izin verme durumuna bağlı olarak AllowAdsStatusEnum içinde bir değer döndürür. Bu işlev için belirtilmesi gereken anahtar AD_BLOCK_DATA_READY şeklindedir.

Örnek:

<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}

Kullanıcının CPRA durumuna bağlı olarak InitialCcpaStatusEnum içinde bir değer döndürür. Bu işlev için belirtilmesi gereken anahtar INITIAL_CCPA_DATA_READY şeklindedir. Sonraki CPRA verisi isteklerinin, doğrudan US Privacy API'yi (__uspapi) çağırarak elde edilmesi gerektiğini unutmayın.

Örnek:

<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}

Varsayılan satmama bağlantısı geçersiz kılınmışsa CPRA onay iletişim kutusunu açar. Kullanıcı onay iletişim kutusuyla etkileşimde bulunduğunda, devre dışı bırakmaya karar verirse sağlanan geri çağırma işlevi true ile, aksi takdirde false ile çağrılır.

Örnek:

<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>

IAB TCF v2 çerçevesi kapsamında GDPR izni almak için Google kullanıcı rızası yönetim çözümlerini kullanıyorsanız IAB TCF 2.0 API'sini kullanmanız gerekir.

Bunun için CONSENT_API_READY

İlgili geri çağırmaların yalnızca sayfada IAB TCF v2 API'si tanımlandığında çağrılmasını sağlamak için geri çağırma sıra anahtarı. Eşzamanlı 'getTCData' komutu kullanılarak getirilen kullanıcı rızası, henüz IAB TCF v2 API'nin 'addEventListener' komutuyla birlikte kullanılamayabilir.

Örnek:

<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>

Bunun için CONSENT_DATA_READY

geri çağırma sırası anahtarının kullanılması gerekir. Eşzamanlı yöntemler kullanarak kullanıcının izin durumunu getirebileceğiniz için bu, 'getTCData' komutuyla birlikte kullanılabilir.

Örnek:

<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>

Google'ın kullanıcı rızası yönetim çözümlerini CPRA için IAB GPP çerçevesiyle kullanma

IAB GPP çerçevesi kapsamında CPRA kapsamı dışında kalmayı seçmek için Google kullanıcı rızası yönetim çözümlerini kullanıyorsanız IAB GPP API'sini kullanmanız gerekir.

CPRA düzenlemesinin devre dışı bırakma yapısı nedeniyle geri çağırmanın çağrıldığı zaman IAB GPP API'nin aranabilir olduğundan ve izin verileri döndürdüğünden emin olmak için CONSENT_API_READY veya CONSENT_DATA_READY geri çağırma sıra anahtarını kullanabilirsiniz.

<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>

Özel bir Satmayın Satış bağlantısı ile CPRA için IAB GPP çerçevesiyle Google izin yönetimi çözümlerini kullanma

IAB GPP çerçevesi kapsamında CPRA kapsamı dışında kalmayı seçmek için Google kullanıcı rızası yönetim çözümlerini kullanıyorsanız googlefc.ccpa.overrideDnsLink işaretini true olarak ayarlayarak özel bir Satmayın bağlantısı sağlayabilirsiniz.

<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>

Bu, varsayılan "Satma" bağlantısının oluşturulmamasını sağlar. CPRA'ya uymak için kendi Satışı Yapma bağlantısını oluşturmaktan sorumlu olduğunuzu unutmayın. Ardından, CPRA onay iletişim kutusunu çağırarak özel satmamanız bağlantısıyla kullanıcı etkileşimini yönetmeniz gerekir.

<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>