クッキーと同意管理（JavaScript SDK）

このガイドでは、レガシー JavaScript SDK を使用する場合に、Amplitude がどのようにクッキー、ローカルストレージ、オプトイン/オプトアウトオプション、同意管理（フランスのCNIL規制を含む）を扱うかについて説明します。

Amplitudeのクッキー

「クッキー」とは、ブラウザがユーザーのデバイスに保存する ウェブサイト からのデータの一部です。ウェブサイトは機能的または技術的な目的で保存されたデータにアクセスするために、後でクッキーを取得します。 初期化後、Amplitude SDKはプレフィックスで始まりプロジェクトAPIキーの最初の10桁で終わるクッキーAMP_を作成します。このプレフィックスは、SDKのconstants.jsファイル内のCOOKIE_PREFIX定数を使用してカスタマイズできます。SDKはamplitude-client.jsでクッキーの値を定義しています。

たとえば、次のようにプレフィクスにデフォルト値を使用する場合です。

amplitude.getInstance().init("a2dbce0e18dfe5f8e...");

Amplitude Browser 2.0 SDKは、プロジェクトのAPIキーの最初の10文字が続く形式のクッキーAMP_を作成します。

以前のバージョンのSDKでは、このクッキーのキーを初期化時にカスタマイズするためのcookieNameオプションを使用することができました。この方法は現在機能しませんが、古いバージョンのSDKを使用している場合、クッキー名が標準の名前と異なる場合があります。

キーのamplitude_cookie_test後にランダムなbase64サフィックスが続く別のCookieが表示された場合、SDKはそのCookieを使用して、ユーザーがCookieを有効にしているかどうかをテストします。テストが完了すると、SDK はこの Cookie を削除します。 詳細については、SDK の base-cookie.js ファイルを参照してください。

場合によっては、SDK が amplitude_test_cookieCookie を削除しないことがあります。 この場合、CookieはCookieリストに残りますが、使用されません。この Cookie のキーは、SDK の constants.js ファイル内のCOOKIE_TEST_PREFEX定数を使用してカスタマイズできます。

SDKはCookieを使用して次のメタデータを追跡します。

• deviceId: ランダムに生成された文字列です。
• userId：ユーザーがログインしたときにアプリがこの値をAmplitudeに送信した場合、SDKはそれをCookieに保存します。この値を設定すると、ユーザーを一意に識別できます。 Amplitudeはこの値をBase64でエンコードしてから保存します。
• optOut: このデバイスを Amplitude トラッキングから除外するためのフラグです。 このフラグが設定されている場合、Amplitudeはユーザーに関する追加情報を保存しません。
• sessionId：各セッションに対してランダムに生成される文字列です。
• lastEventTime: 前回のイベントの時刻で、有効期限を決定したり、新しいセッション ID を作成したりするために使用されます。
• eventId: イベントを区別するための識別子の増分シーケンスです。
• identifyId: 識別コールを区別する識別子の増分シーケンスです。
• sequenceNumber: イベントを順序付けし、Identifyコールを識別するためのシーケンス番号です。

Amplitude JavaScript SDKがロードされると、Amplitudedevice_id（ユーザーが戻ってきて前回の訪問で生成した場合に存在するdevice_id）のクッキーをチェックします。 検出された場合、SDKはその値を使用します。 そうでない場合（新規ユーザーまたは最近Cookieをクリアしたユーザーの場合）、SDKはランダムに生成し、device_idそれをCookieに保存します。

クッキーのサイズ

クッキーのサイズは、最小 60 バイトから約 120 バイトまでさまざまです。 Amplitudeは2つのクッキー（amp_*およびamp_*.organization.domain）を保存できるため、プロジェクトAPIキーごとにAmplitudeクッキーの安全な平均サイズは120バイトであると仮定してください。

有効期限

Amplitude SDKには、クッキーが期限切れになるまでの日数を設定できるcookieExpirationオプションがあります。 SDKバージョン7.0以前のバージョンでは、デフォルト値は10年でした。SDKバージョン7.0以降では、cookieExpirationのデフォルトは1年間です。ほとんどのブラウザでは、document.cookie設定されたクッキーの有効期限を1日から7日間と制限しています。

Amplitudeのクッキーを削除する

Amplitudeのクッキーをプログラムで削除するには、JavaScript SDKのclearStorage()メソッドを使用してください。 このメソッドを使用すると、すべてのクッキーがクリアされ、そのクッキーに保存されているすべてのメタデータが削除されます。

廃止されたクッキー

以下のクッキーキーは、最新のSDKバージョンでは非推奨となっています。

• amplitude_id_<API_KEY>.your_org_domain: 以前のバージョンの Amplitude JavaScript SDK では、デフォルトの Cookie キーは amplitude_id でした。 これは、6.0.0より前のSDKバージョンを使用しているプロジェクトで発生することがあります。この場合、Cookieキーは amplitude_id_<PROJECT_API_KEY>.organization.domain です。

• amplitude_test.your_org_domain: Amplitude SDK は、この Cookie を使用して、Cookie が利用可能かどうかをより徹底的にテストします。 デフォルトでは、キーは amplitude_cookie_test であり、テスト後にこの Cookie は SDK によって削除されます。

LocalStorageを使用してクッキーを無効にする（オプトアウトクッキー）

このCookieには、Amplitudeが正しく機能するために必要なデータが含まれています。 これにより、deviceId 、sessionId 、および直近のイベントのタイムスタンプが保存されます。 この情報をユーザーのローカルストレージに保存するには、SDKのoptions.jsファイルで disableCookiesをtrue に設定してください。

ローカルストレージに保存されたデータ

クッキーで管理される情報のほかに、Amplitudeはローカルストレージを以下の目的で使用しています：

• オンラインイベント：SDKのoptions.js内のsaveEventsオプションがこのストレージを制御します（デフォルトは true）。 Amplitudeは受信したすべてのイベントを保存し、アップロードが成功した後にイベントを削除します。 falseに設定されている場合、アップロードが完了する前にユーザーが別のページに移動した場合、イベントが失われる可能性があります。
• オフラインイベント: SDKのoptions.jsのsavedMaxCountオプションは、オフラインイベントの数を設定します（デフォルトは1000）。Amplitudeがオフラインで1000件を超えるイベントを記録する場合、SDKは最も古いイベントをストレージから削除します。
• 失敗したイベント: SDKは再試行用に失敗したイベントをここに保存します。

Amplitudeはこのデータを以下のキーに保存します。

• amplitude_unsent_<PROJECT_API_KEY>：未送信のイベントを格納します。この名前は、SDKのoptions.js内にあるunsentIdentifyKeyオプションを使用してカスタマイズできます。
• amplitude_unsent_identify_<PROJECT_API_KEY>：未送信のidentifyコールを格納します。この名前は、SDKのoptions.js内にあるunsentKeyオプションを使用してカスタマイズできます。

自動的に取得されたその他のプロパティは、Cookieの代わりにLocalStorageを使用しても影響を受けません。詳細については、「ユーザープロパティの定義」を参照してください。

このアクションによりCookieの保存は無効になりますが、Amplitudeはユーザーのブラウザのローカルストレージに同じデータを保存します。完全にオプトアウトしたいユーザーにとって有効なオプションではありません。

Cookieとローカルストレージ/セッションストレージを無効にする（オプトアウトストレージ）

クッキーを無効にし、ユーザーがローカルストレージとセッションストレージを無効にすると、SDKが既存のIDを見つけることができないため、Amplitudeはユーザーの訪問ごとに新しいdevice_idIDを作成します。ユーザーがログインしたり、その他の識別情報を提供したりした場合、AmplitudeのID解決システムはさまざまなdevice_id値をそのユーザーIDと結び付けます。 ユーザーは訪問ごとにログインする必要があります。そのため、Amplitudeは識別子をマージできます。

追跡の無効化（追跡のオプトアウト）

ユーザーはクッキーをオプトアウトしたい場合があります（これによりAmplitudeはクッキーにデータを保存できません）、またトラッキングを完全にオプトアウトしたい場合もあります（つまり、Amplitudeはユーザーの閲覧履歴のイベントや記録を保存しません）。 Amplitude SDKは、このリクエストに対応するための機能を提供しています。optOutプログラムで追跡をオプトアウトするには、amplitude.setOptOut(true)を呼び出します。

ブラウザの「追跡拒否」設定（DNTフラグ）

一部のブラウザには、すべての追跡をブロックすることを目的とした「追跡拒否」設定があります。Amplitude はこの設定に準拠していません。 DNT標準は広くサポートされておらず、それが何を無効にするかの範囲も明確ではありません。この設定に従うには、独自のコードを記述してDNTフラグをテストし、SDKでoptOutオプションを設定してください。

クッキーの同意を管理する

一部の管轄区域では、データ収集前に不可欠でないクッキーにユーザーに同意していただく必要があります。 お客様は、お客様が収集してAmplitudeに送信する個人データについて必要な同意を得て必要な開示を行う責任を負います。 また、カスタマーは、カスタマーの特定のユースケースとカスタマーがそれらを使用する管轄区域に基づいて、クッキーポリシーにおいてAmplitudeのクッキーをどのように分類するかを決定する責任を負います。

これらの管轄区域のいずれかでAmplitude SDKを使用する場合、ユーザーがクッキーの使用に同意するまでSDKを初期化しないでください。 Amplitudeの機能（クッキーの保存、ローカルストレージ、イベントの追跡など）は、SDKの初期化時に有効または無効になります。

これをサポートするため、JavaScript SDKではdeferInitializationオプションが提供されています（デフォルト値はnull）。trueに設定されている場合、このオプションは、クッキー（またはローカルストレージへの保存）やすべてのトラッキングなど、SDKのコア機能を明示的に有効にするまで無効にします。SDK インスタンスは、amplitude.getInstance().enableTracking() を呼び出すまでストレージやトラッキングなしでロードされます。

amplitude.getInstance().enableTracking()を呼び出すと、SDKはdeferInitializationに設定され、falseAmplitudeは設定したオプション値を使用してクッキーを作成します（client.jsに示されています）。

/**
 * Enable tracking through logging events and dropping a cookie
 * Intended to be used with the deferInitialization configuration flag
 * This will drop a cookie and reset initialization deferred
 * @public
 */
AmplitudeClient.prototype.enableTracking = function enableTracking() {
  // This will call init (which drops the cookie) and will run any pending tasks
  this._initializationDeferred = false;
  f(this);
  this.runQueuedFunctions();
};
/**
 * Saves deviceId, userId, event meta data to amplitude cookie
 * @private
 */
var _saveCookieData = function _saveCookieData(scope) {
  const cookieData = {
    deviceId: scope.options.deviceId,
    userId: scope.options.userId,
    optOut: scope.options.optOut,
    sessionId: scope._sessionId,
    lastEventTime: scope._lastEventTime,
    eventId: scope._eventId,
    identifyId: scope._identifyId,
    sequenceNumber: scope._sequenceNumber,
  };
  if (scope._useOldCookie) {
    scope.cookieStorage.set(
      scope.options.cookieName + scope._storageSuffix,
      cookieData,
    );
  } else {
    scope._metadataStorage.save(cookieData);
  }
};

これは、amplitude-client.js に示されているように、すでにAmplitudeクッキーを持っているユーザーには影響しません。ユーザーが同意した時点で、Amplitudeがクッキーを合法的に作成するための要件が満たされます。そのユーザーを追跡からオプトアウトするには、そのユーザーに対してすでに存在しているAmplitudeのクッキーをすべて削除する必要があります。

Amplitude Analyticsのクッキーの存在により、Amplitudeがユーザーのイベントを追跡するかどうかが決まります。 ユーザーにこれが設定されている場合は、以下の点を考慮してください。

1. 短い有効期間を手動でcookieExpiration設定した場合、Amplitude Analyticsクッキーの有効期限が切れたときやユーザーがログインしたときにamplitude.getInstance().enableTracking()実行する必要がある場合があります。

2. ユーザーがすべてのクッキーを削除した場合、ユーザーが次回アプリにアクセスするときに同意バナーが再び表示されます。Amplitude Analyticsのクッキーはまだ存在しないため、フローは「クッキーの同意の管理」セクションに記載されているとおりに進行し、deferInitialization = true を使用する際にはストレージとトラッキングのオプションの初期化が待機します。

3. ユーザーが過去にAmplitude Analyticsクッキーに同意しており、その同意が何らかの理由（ウェブサイトのクッキーの削除、同意追跡の期限切れなど）で期限切れになった場合、Amplitudeはユーザーに再度同意を求めます。ユーザーがこれを拒否する場合、Amplitude Analyticsのクッキーを明示的に削除する必要があります。そうしない場合、SDKはユーザーの意思に反してユーザーの情報を収集し続けます。

プロジェクトごとにSDK初期化オプションを取得する

Amplitude JavaScript SDKを使用しているすべてのサイトから、どの初期化オプションが設定されているかを確認できます。 サイトへのアクセスに使用するブラウザ内にあるJavaScriptコンソールから、次のコマンドを実行します：

amplitude.getInstance().options;

コンソールには、各オプションとその値が表示されます。 たとえば、amplitude.comでは次の事項を確認できます。

Amplitude Event Explorer Chrome拡張機能のAPIオプション

Amplitude EventエクスプローラーChrome拡張機能を使用している場合、関心のあるプロジェクトを選択した後で「APIオプション」タブで初期化オプションの値にアクセスできます。

Amplitudeオブジェクトインスタンスがwindowオブジェクトに保存されていない場合、この情報はコンソールやChrome拡張機能から利用できません。 これは通常、JavaScript SDKの代わりにNode.jsを使用している場合に発生します。

コンソールのエラーは次のようになります。

ストレージオプションの説明

この表は、各ストレージ関連オプションの概要を簡単に示しています。

ストレージ用の抽象化レイヤー

ストレージ抽象化レイヤー、利用可能なオプション、保存されているメタデータは、AmplitudeのGitHubで確認できます。

• constants.js
• options.js
• cookiestorage.js
• Cookie.js
• base-cookie.js
• localstorage.js
• metadata-storage.js

SDKは初期化時にオプションを設定します。Cookieとメタデータストレージの場合、これはAmplitudeクライアントのInitメソッドで発生します。

• amplitude-client.js

this.options.apiKey = apiKey;
this._storageSuffix =
  "_" +
  apiKey +
  (this._instanceName === Constants.DEFAULT_INSTANCE
    ? ""
    : "_" + this._instanceName);
this._storageSuffixV5 = apiKey.slice(0, 6);
this._oldCookieName = this.options.cookieName + this._storageSuffix;
this._unsentKey = this.options.unsentKey + this._storageSuffix;
this._unsentIdentifyKey = this.options.unsentIdentifyKey + this._storageSuffix;
this._cookieName = Constants.COOKIE_PREFIX + "_" + this._storageSuffixV5;
this.cookieStorage.options({
  expirationDays: this.options.cookieExpiration,
  domain: this.options.domain,
  secure: this.options.secureCookie,
  sameSite: this.options.sameSiteCookie,
});
this._metadataStorage = new MetadataStorage({
  storageKey: this._cookieName,
  disableCookies: this.options.disableCookies,
  expirationDays: this.options.cookieExpiration,
  domain: this.options.domain,
  secure: this.options.secureCookie,
  sameSite: this.options.sameSiteCookie,
  storage: this.options.storage,
});
const hasOldCookie = !!this.cookieStorage.get(this._oldCookieName);
const hasNewCookie = !!this._metadataStorage.load();
this._useOldCookie =
  !hasNewCookie && hasOldCookie && !this.options.cookieForceUpgrade;
const hasCookie = hasNewCookie || hasOldCookie;

よくある質問

CNIL France - よくある質問