CookieバナーのパブリックAPI資料

すべてのパブリック APIメソッドは、グローバル名前空間内のCookieFirstオブジェクトで利用可能です。また、windowオブジェクトの所有物としてアクセスすることも可能です。

javascript
const CF = CookieFirst;
// or
const CF = window.CookieFirst;

1. Cookie パネル

開発者がプログラムでCookieパネルを開いたり閉じたりできる2つの方法があります。

1.1 パネルを開く

Cookieパネルが開いてない場合は開いてください。 ステルスモード で Error が表示されます。

タブの名前がそのドメインの有効なタブでなければ、Error と表示されます。

// open the Settings tab by default
CookieFirst.openPanel();
// open the specified tab (possible values are "settings", "cookies", "policy"):
CookieFirst.openPanel("cookies");

1.2. パネルを閉じる

Cookieパネルが開いている場合は、閉じてください。ステルスモードだとError表示されます。

javascript
CookieFirst.closePanel();

2. 訪問者の同意

これらのメソッドとプロパティにより、開発者はドメインに対する訪問者の現在の同意を取得し、それを部分的に変更するなどさまざまなアクションをプログラムで起動することができます。

イベント情報を聞く

const callbackFn = (event) => {
  var consent = event.detail || CookieFirst.consent;
};
// listen for Cookie First initialization event
window.addEventListener("cf_consent", callbackFn);

2.1 訪問者の同意に関する情報の取得

javascript
const consent = CookieFirst.consent;

// if consent is available, it will be an object of this structure:
{
 necessary: true, // necessary category can't be disabled
 performance: true|false,
 functional: true|false,
 advertising: true|false,
}

// otherwise it will be empty
consent === null; // true

2.2 同意の取り消し（）

同意取り消し機能は、訪問者の同意を削除し、その変更を当社の同意ログに記録します。この行為が実行された後、ウェブサイトは再読み込みされ、訪問者がドメインで新しいスタートを切ることができるようになります。バナーは再び表示され、訪問者が再び同意するまでは、同意の変更方法は利用できなくなります。

javascript
CookieFirst.withdrawConsent();

2.3 同意の更新

開発者はこの機能によって、訪問者の同意を更新し、指定された値に設定することができます。これはパラメーターとして同意目的を受け取ります。

javascript
const newConsent = {...CookieFirst.consent};
newConsent.functional = true;
CookieFirst.updateConsent(newConsent);

2.4 カテゴリーを承諾する（）

この機能は上の同じ行為を一行のコードのみで実行可能することができます。

javascript
CookieFirst.acceptCategory("functional");

2.5 全てのカテゴリーを承諾する（）

この機能は訪問者が全てのカテゴリーのCookiesに承諾することを可能にします。

javascript
CookieFirst.acceptAllCategories();

2.6 あらかじめ選択されたカテゴリーを承諾する（）

この機能は、CookieFirst管理画面のドメイン設定画面であらかじめ選択されているカテゴリのみを受け入れることができます。

javascript
CookieFirst.acceptPreselectedCategories();

2.7 全てのカテゴリーを拒否（）

この機能を使うと、1行のコードで、必要なカテゴリだけを受け入れ、それ以外のカテゴリは拒否することができます。withdrawConsent()機能と似ているように見えますが、同意を完全に消去するわけではなく、Cookieのバナーを表示するわけではありません。必要なクッキーのみを有効にするよう同意を更新できます。

javascript
CookieFirst.declineAllCategories();

2.8 カテゴリーを拒否

この機能により、訪問者は1つのCookieカテゴリのみを拒否し、残りの同意は以前保存したまま維持することができます。（機能、広告、パフォーマンスなど）

javascript
CookieFirst.declineCategory("functional");

3. 統合の設定

あなたのサイトでのバナーの動作を制御するために使用できる設定がいくつかあります。これらは、バナー埋め込みコードのデータ属性またはURL属性を使って有効化できます。

データ属性を使用した例：

<script 
src="https://consent.cookiefirst.com/banner.js" 
data-cookiefirst-key="YOUR_API_KEY" 
data-stealth-mode="true"
></script>

URL属性を使用した例：

<script 
src="https://consent.cookiefirst.com/banner.js?stealth-mode=true" 
data-cookiefirst-key="YOUR_API_KEY"
></script>

実際は、URL属性のようにAPIキーも以下のように使用可能です：

<script 
src="https://consent.cookiefirst.com/banner.js?cookiefirst-key=YOUR_API_KEY" 
></script>

複数のURL属性を使用している場合は、& マークを各属性の名前の前に入れ足してある確認してください。例：

src="[...]/banner.js?cookiefirst-key=YOUR_API_KEY&stealth-mode=true"

3.1 ステルスモード

ステルスモードでは、CookieFirst バナーは同意管理のインターフェイスをレンダリングしません。レンダリングされるコンテンツは、サポートするページ上のクッキー宣言のみです。ステルスモードでは、存在しないものを制御することはできないため、プログラムでクッキー・バナーを制御することも不可能です。

データ属性での利用: data-stealth-mode="true" 又は data-stealth-mode="false"

URL属性でに利用: stealth-mode=true 又は stealth-mode=false

3.2 サイレントモード

サイレントモードに設定されている場合は、CookieFirstバナーはブラウザコンソールに情報を入力しません。

データ属性での利用: data-silent-mode="true" 又は data-silent-mode="false"

URL属性でに利用: silent-mode=true 又は silent-mode=false

3.3 言語

バナーに言語の情報が渡されない場合、ユーザーのブラウザをチェックして、ユーザーの優先言語がバナー用に設定された言語のいずれかであるかどうかを判断します。そうでない場合、リストの最初の言語に自動的に戻ります。しかし、バナーの言語をあなたのウェブサイトの言語スイッチと同期させるために、このチェックを避けたい場合があります。これを行うには、language属性を使用することができます。

データ属性での利用: data-language="en" 又は data-language="en"

URL属性でに利用: language=en 又は language=en

注意: 言語においては、二文字のISO-639-1 コードを使用しています。例:en-GB ではなくen

4. イベント

CookieFirst バナーは、そのライフサイクルにおいて様々なイベントを送信し、それらはグローバルwindowウオブジェクト上で聞くことが可能です。

4.1. cf_consent

このイベントは、ユーザーが同意または変更（撤回を含む）するたびに発行されます。同意が得られたときに何らかのアクションを実行したい場合に、このイベントを使用します。同意が更新または撤回されると、バナーはページを再読み込みし、ユーザーの好みに応じて承認されたサードパーティのコードのみが実行されるようにするので、最初の同意を聞くときに特に便利です。

リスナーの例:

window.addEventListener("cf_consent", function(event) {
var newlyGivenConsent = event.detail;
}):

4.2 cf_init

このイベントは、バナーが完全に初期化され、JS APIオブジェクトが利用可能になったときに送信されます。このイベントが発生した後、window.CookieFirstオブジェクトを安全に使用することができます。

リスナーの例:

window.addEventListener("cf_init", function() {
  // use the window.CookieFirst object here
}):

4.3 cf_consent_loaded

このイベントは、バナー初期化プロセスの一部として、ユーザーの以前の同意が利用可能になるとすぐに発行されます。ユーザーの以前の同意に基づくアクションを実行したい場合に使用します。

リスナーの例:

window.addEventListener("cf_consent_loaded", function(event) {
  var previouslySavedConsent = event.detail;
  if(!previouslySavedConsent) {
    // consent hasn't been given yet
  } else {
    // previous consent is available
  }
}):

4.4 cf_layer_ready

このイベントは、同意レイヤーのいずれかが完全にレンダリングされると、すぐに発行されます。このイベントには、レンダリングされた要素が event.detailnに含まれています。

リスナーの例:

window.addEventListener("cf_layer_ready", function(event) {
  var element = event.detail;
  console.log(element); // will show the rendered layer element in console
}):

5. fetchLatestScan()

JS APIを使用すると、Webサイトで見つかったCookieのリストを、最新のスキャン日時と一緒に取得することができます。これを行うには、CookieFirst.fetchLatestScan() メソッドを使用します。これは、以下のレスポンスに解決する約束を果たします。

{
updated_at: "2020-10-29T13:30:23+00:00", // latest scan date and time in ISO 8601 format
cookies: [], // an array of cookies found on your site together with any custom cookies you may have added as well as our own cookies needed for banner to work
}

6. renderEmbeds()