Pengantar
API ini menyediakan alat untuk berinteraksi dengan pesan yang ditawarkan oleh tab Privasi & pesan. Dengan cara ini, Anda dapat:
- sembunyikan pesan untuk pengguna tertentu
- mengkueri status pemblokiran iklan dari pengguna
- mengizinkan pengguna mencabut izin (jika berlaku)
Anda juga dapat menggunakan alat ini untuk mengumpulkan izin pengguna menggunakan beberapa protokol standar industri:
- Izin GDPR menggunakan spesifikasi TCF v2 IAB
- Memilih tidak ikut CPRA menggunakan spesifikasi CPRA IAB GPP
Dalam hal ini, status izin dikomunikasikan melalui API tersebut.
Anda dapat men-deploy fungsi pesan pengguna ini di situs Anda dengan beberapa cara:
- Dalam sebagian besar kasus, Anda tidak perlu memberi tag ulang sama sekali - Tag Penayang Google yang ada atau tag AdSense men-deploy pesan pengguna setelah pesan dipublikasikan dalam produk yang relevan.
- Jika menggunakan pesan pemulihan pemblokiran iklan, Anda perlu menambahkan tag pemblokiran iklan ke halaman secara eksplisit. Lihat petunjuk pemberian tag Ad Manager dan AdSense untuk mengetahui informasi selengkapnya.
googlefc
adalah namespace global yang digunakan fungsi pesan pengguna untuk API-nya di Window
JavaScript.
Ringkasan Lapangan
Nama | Type | Definisi |
---|---|---|
googlefc.controlledMessagingFunction
|
function(!Object) | Fungsi yang menentukan apakah akan melanjutkan pengiriman pesan apa pun. Fungsi ini didukung untuk semua jenis pesan. |
googlefc.callbackQueue
|
!Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue | Referensi ke antrean callback untuk eksekusi kueri pesan pengguna secara asinkron. |
googlefc.CallbackQueue
|
!Objek | Jenis objek antrean callback. |
googlefc.AdBlockerStatusEnum
|
!Object<string, number> | Enum untuk mewakili status pemblokir iklan pengguna. |
googlefc.AllowAdsStatusEnum
|
!Object<string, number> | Enum untuk mewakili status iklan yang diizinkan pengguna. |
googlefc.ccpa.InitialCcpaStatusEnum
|
!Object<string, number> | Enum untuk mewakili status CPRA awal pengguna. |
googlefc.ccpa.overrideDnsLink
|
belum ditentukan|boolean | Boolean yang dapat disetel ke benar (true) untuk menggunakan link Jangan Jual kustom. |
Ringkasan Metode
Nama | Jenis hasil yang ditampilkan | Definisi |
---|---|---|
googlefc.showRevocationMessage()
|
belum ditentukan |
Menghapus data izin dan memuat ulang skrip googlefc untuk menampilkan pesan izin yang berlaku bagi pengguna.
|
googlefc.getAdBlockerStatus()
|
nomor |
Menampilkan nilai di AdBlockerStatusEnum bergantung pada status pemblokiran iklan pengguna.
|
googlefc.getAllowAdsStatus()
|
nomor |
Menampilkan nilai di AllowAdsStatusEnum bergantung pada status iklan yang diizinkan dari pengguna.
|
googlefc.ccpa.getInitialCcpaStatus()
|
nomor |
Menampilkan nilai di InitialCcpaStatusEnum bergantung pada status CPRA awal pengguna.
|
googlefc.ccpa.openConfirmationDialog(function(boolean))
|
belum ditentukan | Membuka dialog konfirmasi CPRA jika link default Jangan Jual diganti. |
Pengujian dan proses debug di situs Anda
Privasi & fitur pesan menyediakan fungsi proses debug dan pengujian yang memungkinkan Anda melihat tampilan pesan (atau kombinasi pesan) tertentu di situs Anda yang sebenarnya.
Prasyarat:
- Pesan yang ingin Anda lihat pratinjaunya harus dipublikasikan di situs yang Anda uji
Anda dapat melihat pratinjau langsung di situs menggunakan parameter URL proses debug berikut:
Parameter debug | Nilai yang diizinkan |
---|---|
fc |
alwaysshow (untuk memicu mode debug/pratinjau) |
fctype |
ab (Pesan pemblokiran iklan), ccpa (pesan pilihan tidak ikut CPRA), gdpr (pesan izin GDPR), monetization (pesan Offerwall) |
Beberapa contoh cara menggunakan ini untuk melihat pratinjau di situs Anda (foo.com):
- Uji pesan CPRA --
http://foo.com?fc=alwaysshow&fctype=ccpa
- Menguji pesan GDPR --
http://foo.com?fc=alwaysshow&fctype=gdpr
Kolom: penjelasan dan contoh
googlefc.controlledMessagingFunction {function(!Object)}
Fungsi yang menentukan apakah pesan harus ditampilkan atau tidak. Elemen ini dapat digunakan untuk membatasi rendering pesan pada kondisi yang ditentukan penayang, seperti status subscriber atau URL halaman.
Saat Anda menentukan googlefc.controlledMessagingFunction
di Jendela sebelum pemuatan skrip lain, pesan tidak akan ditampilkan hingga Anda memanggil message.proceed(boolean)
. Memanggil message.proceed(true)
memungkinkan pengiriman pesan ke proses seperti biasa, sedangkan memanggil message.proceed(false)
akan mencegah pesan ditampilkan untuk kunjungan halaman.
Contoh: asumsikan bahwa Anda memiliki skrip ini di halaman yang menentukan fungsi
asinkron determineIfUserIsSubscriber()
yang memeriksa apakah pengguna yang login merupakan
pelanggan.
<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>
Ini adalah contoh cara menggunakan
googlefc.controlledMessagingFunction
untuk hanya menampilkan pesan kepada
non-subscriber.
<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>
Penayang bagian dari offerwall tertutup beta dapat menentukan bahwa hanya Offerwall
yang harus disembunyikan dengan memberikan parameter tambahan ke
message.proceed()
. Parameter ini adalah Array
dari jenis
googlefc.MessageTypeEnum
. Satu-satunya enum yang didukung hari ini adalah OFFERWALL
, tetapi
jenis pesan tambahan mungkin ditambahkan di masa mendatang.
Contoh: asumsikan Anda memiliki fungsi determineIfUserIsSubscriber()
yang sama seperti
di atas. Ini adalah contoh penggunaan googlefc.controlledMessagingFunction
untuk
hanya menyembunyikan penayangan Offerwall untuk pelanggan, tanpa menyembunyikan jenis
pesan lainnya:
<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>
Referensi ke antrean callback global untuk eksekusi asinkron panggilan
terkait pesan. Satu-satunya cara yang didukung untuk memanggil fungsi apa pun adalah dengan menambahkannya ke callbackQueue
.
Karena berbagai jenis data tersedia pada waktu yang berbeda, fungsi harus ditambahkan sebagai peta, dengan salah satu string berikut sebagai kunci dan fungsi yang akan dijalankan sebagai nilai.
Kunci yang didukung:
Nama kunci | Penggunaan | Latensi relatif |
---|---|---|
CONSENT_API_READY
|
Fungsi yang didorong ke antrean callback dengan kunci CONSENT_API_READY dieksekusi saat API untuk framework izin yang didukung ditentukan dan dapat dipanggil. Dari titik ini, eksekusi fungsi dengan kunci CONSENT_API_READY yang ditambahkan berikutnya akan berjalan secara sinkron. Lihat bagian framework IAB di bawah untuk mengetahui detail khusus framework.
|
Rendah |
CONSENT_DATA_READY
|
Fungsi yang didorong ke antrean callback dengan kunci CONSENT_DATA_READY dieksekusi saat izin pengguna yang dikumpulkan berdasarkan framework izin yang didukung diketahui (baik dari eksekusi sebelumnya atau setelah pengguna berinteraksi dengan pesan izin). Dari titik ini, eksekusi fungsi dengan kunci CONSENT_DATA_READY yang ditambahkan berikutnya akan berjalan secara sinkron.
|
Tinggi |
AD_BLOCK_DATA_READY
|
Fungsi yang didorong ke antrean callback dengan kunci AD_BLOCK_DATA_READY dieksekusi saat data pemblokiran iklan tersedia di flow. Dari titik ini, eksekusi fungsi dengan kunci AD_BLOCK_DATA_READY yang ditambahkan berikutnya akan berjalan secara sinkron.
|
Tinggi |
INITIAL_CCPA_DATA_READY
|
Fungsi yang didorong ke antrean callback dengan INITIAL_CCPA_DATA_READY dieksekusi saat data CPRA tersedia dalam alur. Perhatikan bahwa permintaan selanjutnya untuk data CPRA harus diperoleh dengan langsung memanggil US Privacy API (__uspapi ).
|
Sedang |
googlefc.CallbackQueue {!Object}
Ringkasan metode:
Nama | Type | Parameter | Jenis hasil yang ditampilkan | Peran |
---|---|---|---|---|
push(data)
|
nomor |
data : Pasangan nilai kunci dengan kunci sebagai salah satu jenis
ketersediaan data dan nilai sebagai fungsi JavaScript yang akan dieksekusi.
Kunci ketersediaan data yang dapat diterima adalah CONSENT_API_READY ,
CONSENT_DATA_READY , AD_BLOCK_DATA_READY , dan
INITIAL_CCPA_DATA_READY .
|
Jumlah perintah yang ditambahkan sejauh ini. Tindakan ini akan menampilkan panjang array saat ini. | Mengeksekusi fungsi yang diteruskan, sesuai urutan tersedianya data, kemudian dengan urutan fungsi-fungsi tersebut ditambahkan ke antrean. |
Contoh:
<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>}
Mewakili berbagai status pemblokiran iklan pengguna. Status yang berbeda adalah:
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>}
Mewakili berbagai status iklan yang diizinkan pemblokiran iklan milik pengguna. Statusnya berbeda:
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>}
Mewakili berbagai status iklan yang diizinkan pemblokiran iklan milik pengguna. Statusnya berbeda:
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}
Tetapkan kolom ini ke true (benar) untuk menyembunyikan link Jangan Jual default dan gunakan link Jangan Jual kustom.
Contoh:
<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>
Metode: penjelasan dan contoh
googlefc.getConsentStatus(): {number}
googlefc.getConsentedProviderIds(): {!Array<string>}
- Tindakan ini akan selalu menampilkan daftar kosong saat dipanggil.
googlefc.showRevocationMessage(): {undefined}
Menghapus data izin saat ini dan menampilkan pesan izin yang berlaku untuk pengguna ini. Kunci yang harus ditentukan untuk fungsi ini adalah CONSENT_DATA_READY
.
Contoh:
<button type="button" onclick="googlefc.callbackQueue.push({'CONSENT_DATA_READY': () => googlefc.showRevocationMessage()});">
Click here to revoke
</button>
googlefc.getAdBlockerStatus(): {number}
Menampilkan nilai di AdBlockerStatusEnum, bergantung pada status pemblokiran iklan
pengguna. Kunci yang harus ditentukan untuk fungsi ini adalah AD_BLOCK_DATA_READY
.
Contoh:
<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}
Menampilkan nilai dalam AllowAdsStatusEnum
bergantung pada status iklan yang diizinkan dari pengguna. Kunci yang harus ditentukan untuk fungsi ini adalah AD_BLOCK_DATA_READY
.
Contoh:
<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}
Menampilkan nilai di InitialCcpaStatusEnum
bergantung pada status CPRA
pengguna. Kunci yang harus ditentukan untuk fungsi ini adalah INITIAL_CCPA_DATA_READY
. Perhatikan bahwa permintaan selanjutnya untuk data CPRA harus diperoleh dengan langsung memanggil US Privacy API (__uspapi
).
Contoh:
<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}
Membuka dialog konfirmasi CPRA jika link Jangan Jual default
diganti. Setelah pengguna berinteraksi dengan dialog konfirmasi, fungsi callback yang diberikan akan dipanggil dengan true
jika pengguna memutuskan untuk tidak mengaktifkannya, dan false
jika tidak.
Contoh:
<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>
Menggunakan solusi pengelolaan izin Google dengan TCF v2 IAB untuk GDPR
Jika Anda menggunakan solusi pengelolaan izin Google untuk mengumpulkan izin GDPR berdasarkan framework TCF v2 IAB, Anda harus menggunakan API TCF v2 IAB.
Anda dapat menggunakan CONSENT_API_READY
kunci antrean callback untuk memastikan bahwa callback yang sesuai hanya dipanggil saat TCF v2 API IAB ditentukan pada halaman. Ini harus digunakan bersama dengan perintah 'addEventListener'
API TCF v2 IAB karena izin pengguna yang diambil menggunakan perintah 'getTCData'
sinkron mungkin belum tersedia.
Contoh:
<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>
Anda dapat menggunakan CONSENT_DATA_READY
kunci antrean callback untuk memastikan bahwa callback yang sesuai hanya dipanggil saat izin pengguna dikumpulkan dan dapat diakses menggunakan TCF v2 API IAB. Ini dapat
digunakan bersama dengan
perintah 'getTCData'
karena Anda dapat mengambil status izin pengguna menggunakan metode sinkron.
Contoh:
<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>
Menggunakan solusi pengelolaan izin Google dengan framework GPP IAB untuk CPRA
Jika Anda menggunakan solusi pengelolaan izin Google untuk mengumpulkan pilihan tidak ikut CPRA dalam framework GPP IAB, Anda harus menggunakan IAB GPP API.
Karena sifat tidak ikut peraturan CPRA, Anda dapat menggunakan kunci antrean callback
CONSENT_API_READY
atau
CONSENT_DATA_READY
untuk memastikan bahwa GPP API IAB dapat dipanggil dan menampilkan data izin
pada saat callback dipanggil.
<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>
Menggunakan solusi pengelolaan izin Google dengan framework GPP IAB untuk CPRA dengan link Jangan Jual kustom
Jika Anda menggunakan solusi pengelolaan izin Google untuk mengumpulkan pilihan tidak ikut CPRA
dalam framework GPP IAB, Anda dapat memberikan link Jangan Jual kustom
dengan menetapkan tanda googlefc.ccpa.overrideDnsLink
ke 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>
Hal ini memastikan bahwa link Jangan Jual default tidak dirender. Perhatikan bahwa Anda bertanggung jawab untuk merender link Jangan Jual Anda sendiri agar sesuai dengan CPRA. Kemudian, Anda perlu menangani interaksi pengguna dengan link Jangan Jual kustom dengan memanggil dialog konfirmasi 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>