Consent API

Consent API では、Consent Management プログラムのあらゆる側面をプログラムから制御できます。モーダル、同意ステータスの管理、設定済みの利用目的（purpose）に関する情報の取得が含まれます。

Consent API を使うと、Zaraz の同意設定を外部の Consent Management Platform と連携したり、同意モーダルをカスタマイズしたり、特定の地域のユーザーにだけ同意管理を制限したりできます。

Consent API がページ上で完全に読み込まれたタイミングを知ることは役立ちます。メソッドやプロパティを扱うコードを、早すぎるタイミングで呼ばないようにできます。

document.addEventListener("zarazConsentAPIReady", () => {
  // do things with the Consent API
});

このイベントは、ユーザーが同意設定を変更するたびに発火します。同意の変更に応じて処理できます。たとえば、新しい同意設定でツールを更新する場合です。

document.addEventListener("zarazConsentChoicesUpdated", () => {
  // read the new consent preferences using `zaraz.consent.getAll();` and do things with it
});

次は、zaraz.consent オブジェクトのプロパティです。

• modal boolean

  • 同意モーダルダイアログの現在の表示状態を取得または設定します。

• purposes object read-only

  • 設定済みのすべての利用目的を含むオブジェクトです。各要素には ID、名前、説明、順序があります。

• APIReady boolean read-only

  • Consent API が現在ページ上で利用できるかどうかを示します。

zaraz.consent.get(purposeId);

• get(purposeId) : boolean | undefined

利用目的 ID を使って、その利用目的の現在の同意ステータスを取得します。

• true: 同意が付与されています。
• false: 同意が付与されていません。
• undefined: その利用目的は存在しません。

• purposeId string

  • 利用目的を表す ID です。

zaraz.consent.set(consentPreferences);

• set(consentPreferences) : undefined

利用目的 ID を使って、一部の利用目的の同意ステータスを設定します。

• consentPreferences object

  • 設定したい利用目的と、それぞれの同意ステータスを表す { purposeId: boolean } オブジェクトです。

zaraz.consent.getAll();

• getAll() : { purposeId: boolean }

すべての利用目的の同意ステータスを含むオブジェクトを返します。

zaraz.consent.setAll(consentStatus);

• setAll(consentStatus) : undefined

すべての利用目的の同意ステータスを一度に設定します。

• consentStatus boolean

  • 同意が付与されたかどうかを示します。

zaraz.consent.getAllCheckboxes();

• getAllCheckboxes() : { purposeId: boolean }

すべての利用目的のチェックボックス状態を含むオブジェクトを返します。

zaraz.consent.setCheckboxes(checkboxesStatus);

• setCheckboxes(checkboxesStatus) : undefined

利用目的 ID を使って、一部の利用目的の同意ステータスを設定します。

• checkboxesStatus object

  • 設定したいチェックボックスと、それぞれのチェック状態を表す { purposeId: boolean } オブジェクトです。

zaraz.consent.setAllCheckboxes(checkboxStatus);

• setAllCheckboxes(checkboxStatus) : undefined

同意モーダル内のすべての利用目的に対して、checkboxStatus を一度に設定します。

• checkboxStatus boolean

  • 利用目的をチェック済みとしてマークするかどうかを示します。

zaraz.consent.sendQueuedEvents();

• sendQueuedEvents() : undefined

同意がなかったために送信されなかった Pageview ベースのイベントがある場合、同意が付与されたあとにこのメソッドで送信できます。

Zaraz の複数の機能を組み合わせて、一部の訪問者に対して Consent Management を実質的に無効にできます。たとえば、EU からの訪問者にだけ使いたい場合は、同意モーダルの自動表示を無効にして、次のスクリプトを含む Custom HTML ツールを追加します。

<script>
function getCookie(name) {
  const value = `; ${document.cookie}`
  return value?.split(`; ${name}=`)[1]?.split(";")[0]
}

function handleZarazConsentAPIReady() {
  const consent_cookie = getCookie("cf_consent")
  const isEUCountry = "{{system.device.location.isEUCountry}}" === "1"
  if (!consent_cookie) {
    if (isEUCountry) {
      zaraz.consent.modal = true
    } else {
      zaraz.consent.setAll(true)
      zaraz.consent.sendQueuedEvents()
    }
  }
}

if (zaraz.consent?.APIReady) {
  handleZarazConsentAPIReady()
} else {
  document.addEventListener("zarazConsentAPIReady", handleZarazConsentAPIReady)
}
</script>

注: Consent Manager の Cookie 名をカスタマイズしている場合は、上のスニペットの "cf_consent" の代わりに、そのカスタム名を使います。

この Custom HTML ツールを同意要件なしで実行すると、EU からの訪問者にはモーダルが表示され、それ以外の訪問者には同意が自動で付与されます。{{ system.device.location.isEUCountry }} プロパティは、訪問者が EU 加盟国からの場合は 1、それ以外は 0 になります。国コードで同意チェックを制限する {{ system.device.location.country }} など、ほかのプロパティや変数でも、同様に Consent Management の動作をカスタマイズできます。