クッキーと同意管理（ブラウザSDK）

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

Amplitudeのクッキー

クッキーとは、ブラウザがユーザーのデバイスに保存するウェブサイトからのデータの一部です。ウェブサイトは機能的または技術的な目的で保存されたデータにアクセスするために、後でクッキーを取得します。 初期化後、Amplitude Browser SDK 2は特定のプレフィックスで始まり、プロジェクトAPIキーの最初の10桁を含むクッキーを作成します。

たとえば、SDKを次のように初期化する場合：

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init("a2dbce0e18dfe5f8e...");

Amplitude Browser SDK 2は、次の形式のクッキーを作成します。

• ユーザーセッションクッキー: AMP_プロジェクトのAPIキーの最初の10文字が付加されたもの (例: AMP_a2dbce0e18)。
• マーケティング キャンペーン クッキー: AMP_MKTG_ にプロジェクトの API キーの最初の 10 文字が付加されたもの (例: AMP_MKTG_a2dbce0e18)。

テストクッキー

初期化中、SDK は一時的なテスト Cookie を作成して Cookie の機能を検証することがあります。

• AMP_TEST_に続くタイムスタンプ：Cookieが機能するかどうかをテストします。
• AMP_TLDTEST_（その後にタイムスタンプが続く）：Cookieの保存に適したサブドメインを検索します。

SDK はテストが完了した後にこれらのテスト Cookie を削除します。 これらが残る場合は、手動で安全に削除できます。

Cookieデータ

SDKはさまざまな種類の情報をクッキーに保存します：

ユーザーセッションクッキー(AMP_*)

ユーザーセッションクッキーには、SDKが正しく機能するために必要なメタデータが含まれています。

• deviceId：ランダムに生成された文字列で、セッション間も持続します。
• userId：ユーザーがログインしたときにアプリがこの値をAmplitudeに送信した場合、SDKはそれをクッキーに保存します。この値を設定すると、ユーザーを一意に識別できます。 Amplitudeはこの値をBase64でエンコードしてから保存します。
• sessionId: 各セッションに対してランダムに生成された文字列です。
• lastEventTime：前回のイベントの時刻で、有効期限を決定したり、新しいセッションIDを作成したりするのに使用されます。
• lastEventId：イベントを区別するために使用される識別子の増分シーケンスです。

マーケティングキャンペーンのクッキー（AMP_MKTG_*）

マーケティングキャンペーンのクッキーはアトリビューションデータを保存します：

• UTMパラメータ（utm_source、utm_medium、utm_campaign、utm_term、utm_content）。
• リファラー情報 (referrer、referring_domain)。
• クリックID（gclid、fbclid、dclid、gbraid、wbraid、ko_click_id、msclkid、ttclid、twclid、li_fat_id、rdt_cid）。

クッキーのサイズ

Cookieのサイズは、1つのCookieにつき約60バイトから120バイトまで異なります。ユーザーセッションCookieとマーケティングキャンペーンCookieの両方を使用する場合、プロジェクトのAPIキーあたりAmplitudeCookieの合計容量は約240バイトと予想されます。

有効期限

デフォルトでは、Amplitudeのクッキーは365日（1年）後に期限切れになります。 これは cookieOptions.expiration 設定パラメータを使用してカスタマイズできます。

amplitude.init("API_KEY", {
  cookieOptions: {
    expiration: 30, // Set cookies to expire after 30 days
  },
});

Amplitudeのクッキーを削除する

Amplitudeのクッキーをプログラムで削除するには、次のスニペットを実行してください。

const API_KEY = "1234567890abcdefghijklmnopqrstuv"; // Replace it with your API KEY
const cookieName = `AMP_${API_KEY.substring(0, 10)}`;
const cookieNameMktg = `AMP_MKTG_${API_KEY.substring(0, 10)}`;
const cookies = document.cookie.split(";");
cookies.forEach((cookie) => {
  const [name] = cookie.trim().split("=");
  if (name === cookieName || name === cookieNameMktg) {
    document.cookie = `${name}=; Max-Age=0; path=/; SameSite=Lax`;
  }
});

ログアウト後にユーザーを匿名化するには、resetを呼び出します。

amplitude.reset();

reset は次のことを行います:

1. userIdをundefinedに設定します。
2. deviceIdを新しいUUID値に設定します。

未定義のuserIdと新しいdeviceIdがある場合、そのユーザーはAmplitudeでは新規ユーザーとして認識されます。

localStorageを使用してCookieを無効にする

Cookie ではなく localStorage を使用するように SDK を構成するには、identityStorage オプションを設定します。

amplitude.init("API_KEY", {
  identityStorage: "localStorage",
});

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

localStorage を使用する場合、SDK は通常 Cookie が保持するのと同じユーザーセッション情報に加えて以下を保存します。

• 未送信イベント：Amplitudeに正常にアップロードされなかったイベント。
• 失敗したイベント: 送信に失敗し、SDK が再試行のためにキューイングしているイベント。

SDKは、プロジェクトのAPIキーを含むキーを使用して、データをlocalStorageに保存します。

• AMP_unsent_[API_KEY]：未送信のイベントを保存します。

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

identityStorageをnoneに設定することで、すべての永続ストレージを無効にできます：

amplitude.init("API_KEY", {
  identityStorage: "none",
});

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

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

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

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

遅延初期化アプローチ

同意管理のために、クッキーに同意する前のイベントを追跡し、後でSDKを初期化することができます。

// Track events
amplitude.track("Button Clicked");
// Later, when user provides consent,
// initialize the SDK
amplitude.init("API_KEY");

ストレージに関連する構成オプション

Browser SDK 2 の各ストレージ関連オプション：

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

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

• ブラウザSDK 2のソースコード
• 構成タイプ
• クッキー保存の実装

よくある質問

AmplitudeのクッキーがHttpOnlyではないのは、そのオプションの目的がdocument.cookieによるクッキーの読み取りを防ぐことだからです（ブラウザはクライアントとサーバー間の通信にのみこれらを使用するため）。Amplitudeのクッキーの目的はこれとは正反対です。Amplitudeはデータをブラウザに保持し、document.cookiesに保存する必要があります。Amplitudeはクライアント側のコードであるため、Amplitudeをサーバーから読み取ることはできません。

これによりAmplitudeのクッキーが認証情報の盗難に対して脆弱になるのではないかと懸念されているかもしれませんが、その心配はありません。Amplitudeはこのクッキーに認証情報を保存しないため、XSS攻撃の危険性はありません。 攻撃者が仕掛けることができるのは、最悪でもAmplitudeのクッキーを盗み、そのユーザーのデバイスIDとユーザーIDを盗むことです。これらの情報は、そもそもPIIに該当しません。

これがあなたにとって深刻な懸念事項である場合は、Amplitudeのクッキーを無効にしてください。

CNIL France - よくある質問