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

このガイドでは、レガシーJavaScript SDKを使用する場合のAmplitudeのクッキー、ローカルストレージ、オプトイン/オプトアウトオプション、および同意管理（フランスのCNIL規制を含む）の動作に関して、機能的および技術的な情報を提供します。

Amplitudeのクッキー

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

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

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

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

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

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

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

クッキーは、SDKに関する以下のメタデータを追跡します。

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

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

クッキーのサイズ

クッキーのサイズは、最小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では、クッキーキーはデフォルトでamplitude_idに設定されていました。これは、6.0.0より前のSDKバージョンを使用しているプロジェクトで発生することがあります。この場合、クッキーキーはamplitude_id_<PROJECT_API_KEY>.organization.domainです。
• amplitude_test.your_org_domain：Amplitude SDKは、このクッキーを使用して、クッキーが利用可能かどうかをより徹底的にテストします。デフォルトでは、キーはamplitude_cookie_testです。テスト終了後、SDKによってこのクッキーは削除されます。

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

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

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

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

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

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

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

自動的に取得されたその他のプロパティは、クッキーの代わりにローカルストレージを使用しても影響を受けません。詳細については、こちらの記事を参照してください。

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

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

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

追跡を無効にする（追跡をオプトアウトする）

ユーザーはクッキーをオプトアウトしたい場合があります（これによりAmplitudeはクッキーにデータを保存できません）、また追跡を完全にオプトアウトしたい場合もあります（つまり、Amplitudeはユーザーの閲覧履歴のイベントや記録を保存しません）。Amplitude SDKは、この要求に対応するためのoptOutオプションを提供します。 プログラムで追跡をオプトアウトするには、SDKメソッドamplitude.setOptOut(true)を使用してください。

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

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

クッキーの同意管理

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

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

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

amplitude.getInstance().enableTracking()を呼び出すと、AmplitudeはdeferInitializationオプションをfalseに設定し、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初期化オプションを取得する

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

amplitude.getInstance().options;

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

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

Amplitude Event Explorer 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。

Amplitude は初期化時にオプションを設定します。 クッキーとメタデータストレージの場合、これは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 - よくある質問