Javascript SDK

これは、Amplitude Analytics JavaScript SDK の公式ドキュメントです。

インストール

Amplitude Analytics JavaScript SDKをプロジェクトにインストールします。

<script type="text/javascript">
  (function (e, t) {
    var n = e.amplitude || { _q: [], _iq: {} };
    var r = t.createElement("script");
    r.type = "text/javascript";
    r.integrity =
      "sha384-5fhzC8Xw3m+x5cBag4AMKRdf900vw3AoaLty2vYfcKIX1iEsYRHZF4RLXIsu2o+F";
    r.crossOrigin = "anonymous";
    r.async = true;
    r.src = "https://cdn.amplitude.com/libs/amplitude-8.21.4-min.gz.js";
    r.onload = function () {
      if (!e.amplitude.runQueuedFunctions) {
        console.log("[Amplitude] Error: could not load SDK");
      }
    };
    var s = t.getElementsByTagName("script")[0];
    s.parentNode.insertBefore(r, s);
    function i(e, t) {
      e.prototype[t] = function () {
        this._q.push([t].concat(Array.prototype.slice.call(arguments, 0)));
        return this;
      };
    }
    var o = function () {
      this._q = [];
      return this;
    };
    var a = [
      "add",
      "append",
      "clearAll",
      "prepend",
      "set",
      "setOnce",
      "unset",
      "preInsert",
      "postInsert",
      "remove",
    ];
    for (var c = 0; c < a.length; c++) {
      i(o, a[c]);
    }
    n.Identify = o;
    var l = function () {
      this._q = [];
      return this;
    };
    var u = [
      "setProductId",
      "setQuantity",
      "setPrice",
      "setRevenueType",
      "setEventProperties",
    ];
    for (var p = 0; p < u.length; p++) {
      i(l, u[p]);
    }
    n.Revenue = l;
    var d = [
      "init",
      "logEvent",
      "logRevenue",
      "setUserId",
      "setUserProperties",
      "setOptOut",
      "setVersionName",
      "setDomain",
      "setDeviceId",
      "enableTracking",
      "setGlobalUserProperties",
      "identify",
      "clearUserProperties",
      "setGroup",
      "logRevenueV2",
      "regenerateDeviceId",
      "groupIdentify",
      "onInit",
      "onNewSessionStart",
      "logEventWithTimestamp",
      "logEventWithGroups",
      "setSessionId",
      "resetSessionId",
      "getDeviceId",
      "getUserId",
      "setMinTimeBetweenSessionsMillis",
      "setEventUploadThreshold",
      "setUseDynamicConfig",
      "setServerZone",
      "setServerUrl",
      "sendEvents",
      "setLibrary",
      "setTransport",
    ];
    function v(t) {
      function e(e) {
        t[e] = function () {
          t._q.push([e].concat(Array.prototype.slice.call(arguments, 0)));
        };
      }
      for (var n = 0; n < d.length; n++) {
        e(d[n]);
      }
    }
    v(n);
    n.getInstance = function (e) {
      e = (!e || e.length === 0 ? "$default_instance" : e).toLowerCase();
      if (!Object.prototype.hasOwnProperty.call(n._iq, e)) {
        n._iq[e] = { _q: [] };
        v(n._iq[e]);
      }
      return n._iq[e];
    };
    e.amplitude = n;
  })(window, document);
  amplitude.getInstance().init(AMPLITUDE_API_KEY);
</script>

SDKをインストールしたら、プロジェクトにamplitudeをインポートします。

import amplitude from "amplitude-js";

// initialize the client
var instance1 = amplitude.getInstance().init(AMPLITUDE_API_KEY);

// send an event
const event = "œButton Clicked";
amplitude.getInstance().logEvent(event);

コア機能

以下の関数がAmplitude Analytics JavaScript SDKの中核を構成しています。

初期化する

実装を行う前に、AmplitudeプロジェクトのAPIキーを使用してSDKを初期化する必要があります。

初期化によってデフォルトのインスタンスが作成されますが、getInstance を文字列名とともに使用することで、追加のインスタンスを作成できます。

var instance1 = amplitude.getInstance().init("AMPLITUDE_API_KEY"); // initializes default instance of Amplitude client
var instance2 = amplitude
  .getInstance("instance-name")
  .init("AMPLITUDE_API_KEY"); // initializes named instance of Amplitude client

オプションによる初期化

initメソッドにカスタムオプションを渡します。 GitHub 上のオプションの一覧を参照してください。

var options = {};
var instance = amplitude
  .getInstance("instance")
  .init(AMPLITUDE_API_KEY, null, options); // initializes with the given options

設定

バッチ処理の動作を設定する

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 SDKは、このメソッドがメモリに記録するすべてのイベントをlogEventキューに格納します。SDKはバックグラウンドで、イベントをバッチ単位でフラッシュします。eventUploadThresholdおよび eventUploadPeriodMillisを使用してバッチ動作をカスタマイズできます。 デフォルトでは、serverUrl は https://api.amplitude.com です。 このSDKはバッチモード、つまりバッチAPIエンドポイントをサポートしていません。

amplitude.getInstance().init(apiKey, null, {
  // Events queued in memory will flush when number of events exceed upload threshold
  // Default value is 30
  eventUploadThreshold: 50,
  // Events queue will flush every certain milliseconds based on setting
  // Default value is 30000 milliseconds
  eventUploadPeriodMillis: 100000,
});

EU域内のデータレジデンシー

バージョン8.9.0以降では、クライアントを初期化した後にAmplitudeのEUサーバーにデータを送信するようにサーバーゾーンを設定できます。

サーバゾーン設定は、動的設定もサポートしています。

以前のバージョンの場合、クライアントを初期化した後にapiEndpointプロパティを設定してください。

バージョン 8.9.0 以降 / 以前のバージョン

// No need to call setServerUrl for sending data to Amplitude's EU servers
amplitude.getInstance().init(euApiKey, null, {
  serverZone: "EU",
  serverZoneBasedApi: true,
});

amplitude.getInstance().init(euApiKey, null, {
  apiEndpoint: "https://api.eu.amplitude.com",
});

設定 userID

クライアントを初期化するとき、またはsetUserIdメソッドを使用して初期化した後userIDに設定してください。

var userId = "12345";
amplitude.getInstance().init(AMPLITUDE_API_KEY, userId); // initializes client with the given userId

イベントを送信

基本イベント

イベントは、ユーザーとアプリとのやり取りを表します。 たとえば、"Button Clicked"は追跡したいアクションかもしれません。

const event = "Button Clicked";
amplitude.getInstance().logEvent(event);

イベントプロパティ

イベントには、イベントに関するコンテキストを与えるプロパティがあります。 たとえば、"hover time"は"Button Clicked"イベントに関連するプロパティです。

var event = "Button Clicked";
var eventProperties = {
  "hover time": "100ms",
};
amplitude.getInstance().logEvent(event, eventProperties);

イベントプロパティ内の配列

イベントプロパティ値は配列にできます。 配列のイベントプロパティは、配列内の個々のプロパティの任意のサブセットによってクエリできます。

var event = "Button Clicked";
var eventProperties1 = {
  selectedColors: ["red", "blue"],
};
amplitude.getInstance().logEvent(event, eventProperties1);
var eventProperties2 = {
  selectedColors: ["red", "green"],
};
amplitude.getInstance().logEvent(event, eventProperties2);

ユーザープロパティ

ユーザープロパティは、ユーザーがアプリ内で何らかのアクションを実行した時点でのユーザーの状況を把握するのに役立ちます。 たとえば、デバイスの詳細、好み、言語などについて学ぶことができます。

ユーザープロパティを設定する

Amplitude Identify オブジェクトは、ユーザープロパティの設定方法を制御します。 まず、Identify オブジェクトのインスタンスを作成し、次にそのインスタンスで Identify メソッドを呼び出し、次にクライアントが Identify オブジェクトを使用して呼び出しを行います。

new amplitude.Identify(); // does nothing, must call one of the following methods and pass to client
var identify = new amplitude.Identify();
amplitude.getInstance().identify(identify); // makes identify call to amplitude with the properties of the identify object

set

ユーザープロパティの値を設定します。 また、複数のsetコールを連結することもできます。

var identify1 = new amplitude.Identify().set("key1", "value1");
var identify2 = new amplitude.Identify()
  .set("key2", "value2")
  .set("key3", "value3");
amplitude.getInstance().identify(identify1);
amplitude.getInstance().identify(identify2);

setOnce

setOnce は、ユーザープロパティの値を 1 回だけ設定します。 Amplitudeは、setOnceを使用した後続の呼び出しを無視します。

var identify = new amplitude.Identify().setOnce("key1", "value1");
amplitude.getInstance().identify(identify);

add

addを使用してユーザープロパティを数値ずつ増やします。 ユーザープロパティに値がまだ設定されていない場合、このプロパティは 0 に初期化されます。

var identify = new amplitude.Identify().add("value1", 10);
amplitude.getInstance().identify(identify);

複数のユーザープロパティを設定する

複数のユーザープロパティを一度に設定するための短縮形としてsetUserProperties使用できます。 たとえば、ユーザーの都市を次のコードで設定します。

var userProperties = {
  city: "San Francisco",
};
amplitude.getInstance().setUserProperties(userProperties);

ユーザープロパティ内の配列

ユーザープロパティは配列にすることができます。 配列を直接設定するか、append または を使用して配列を生成します。

var values = ["value1", "value2"];
var identify = new amplitude.Identify().set("key1", values);
amplitude.getInstance().identify(identify);

prependおよびappend

• append は、ユーザー プロパティ配列に 1 つまたは複数の値を追加します。
• prepend は、ユーザープロパティ配列の前に 1 つまたは複数の値を付加します。

ユーザープロパティに値がまだ設定されていない場合、SDK は新しい値を追加する前にそのプロパティを空のリストに初期化します。 ユーザープロパティに既存の値があり、その値がリストでない場合、SDK はその値をリストに変換し、新しい値を追加します。

ユーザーグループ

Amplitudeでは、ユーザーをグループに割り当てたり、それらのグループに対して「ユニーク数による集計」などのクエリを実行したりすることができます。 グループの少なくとも1人のメンバーが特定のイベントを実行した場合、そのグループはカウントに含まれます。

たとえば、「orgId」を使用して、ユーザーが所属する組織に基づいてユーザーをグループ化したい場合などです。 Joeは'orgId' '10'に属し、Sueは'orgId' '15'に属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。

グループを設定する際には、groupTypeとgroupNameを定義してください。 前の例では、「orgId」はgroupTypeで、「10」と「15」はgroupNameの値です。 groupTypeのもう1つの例としては、「tennis」や「baseball」などのgroupName値を持つ「sport」があります。

グループを設定すると、groupType:groupName もユーザープロパティとして設定され、そのユーザーの groupType に設定されている既存groupNameの値と対応するユーザープロパティ値が上書きされます。groupType は文字列であり、ユーザーが複数のグループに属していることを示すために文字列または文字列の配列を使用できます。groupName

amplitude.getInstance().setGroup("orgId", ["10", "16"]);

また、logEventWithGroups を使用してイベントレベルのグループを設定することもできます。 イベントレベルのグループの場合、グループの指定は SDK がログに記録する特定のイベントにのみ適用され、setGroup で明示的に設定しない限り、ユーザーに持続することはありません。

var eventProperties = {
  key: "value",
};
amplitude
  .getInstance()
  .logEventWithGroups("initialize_game", eventProperties, { sport: "soccer" });

グループ識別

Group Identify API を使用して、特定のグループのプロパティを設定または更新します。次の点に留意してください。

• 更新は将来のイベントにのみ影響を与え、過去のイベントを更新することはありません。
• 最大5つの固有のグループタイプと合計10のグループを追跡できます。

このgroupIdentifyメソッドは、グループタイプの文字列パラメータとグループ名のオブジェクトパラメータ、および SDK がグループに適用する Identify オブジェクトを受け取ります。

var groupType = "plan";
var groupName = "enterprise";
var identify = new amplitude.Identify().set("key1", "value1");
amplitude.getInstance().groupIdentify(groupType, groupName, identify);

オプションのコールバック関数を groupIdentify の 4 番目の引数として指定できます。

収益の追跡

ユーザーにとって収益を追跡する最良の方法は、logRevenueV2()提供されている収益インターフェイスと併用することです。 収益インスタンスは各収益トランザクションを保存し、AmplitudeのイベントセグメンテーションとレベニューLTVチャートで使用されるいくつかの特別な収益プロパティ（revenueTypeやproductIdentifier）を定義できます。 eventPropertiesフィールドを使用してイベントプロパティを収益イベントに追加することもできます。 これらの収益インスタンスオブジェクトを に渡して、収益イベントとしてlogRevenueV2Amplitudeに送信します。 その後、Amplitudeはプラットフォーム内の収益に関連するデータを自動的に表示します。 この方法で、アプリ内購入とアプリ内購入以外の購入の両方を追跡できます。

ユーザーからの収益を追跡するには、logRevenueV2()ユーザーが収益を上げるたびに電話をかけます。 次に例を示します。

var revenue = new amplitude.Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3);
amplitude.getInstance().logRevenueV2(revenue);

コールはlogRevenueV2収益イベントタイプを生成します：

• [Amplitude] Revenue：検証を有効にしているかどうかに関係なく、SDK はすべての収益イベントについてこのイベントを記録します。

生データでこれらのクライアント側の収益イベントに付与されているデフォルトの名前を変更することはできませんが、表示名を変更することはできます。 収益の追跡に関する詳細については、「収益の追跡」を参照してください。

ユーザーを追跡から除外する

指定したユーザーのログをオフにするにはsetOptOut次のように呼び出します。

amplitude.getInstance().setOptOut(true);

setOptOutが有効になっている間、SDK はイベントをサーバーに保存したり送信したりしません。 オプトアウト設定はページ読み込み後も継続されます。 ログ記録を再度有効にするには、次を呼び出してください:

amplitude.getInstance().setOptOut(false);

特定のフィールドの追跡を無効にする

デフォルトでは、JavaScript SDK は一部のプロパティを自動的に追跡します。 SDKの初期化時に、trackingOptionsという名前のオブジェクトを渡すことでこの動作をオーバーライドできます。 適切なオプションを false に設定します。

カスタムユーザーIDを設定する

アプリにユーザーを追跡したいログインシステムがある場合は、いつでも次のように呼び出すsetUserIdことができます。

amplitude.getInstance().setUserId("USER_ID");

ユーザーIDを引数としてinit呼び出しに追加することもできます。

amplitude.getInstance().init(AMPLITUDE_API_KEY, "USER_ID");

ユーザーには変更可能なユーザーIDを割り当てないでください。これは、それぞれの一意のユーザーIDがAmplitude内で一意のユーザーを表すためです。 詳細については、 を参照してください。 ヘルプセンターでAmplitudeの一意のユーザーを追跡します。

ログアウト済みユーザーと匿名ユーザー

Amplitudeはユーザーデータを統合するため、既知のuserIdまたはdeviceIdに関連付けられたイベントは、既存のユーザーに紐付けられます。 ユーザーがログアウトした場合、Amplitudeはそのユーザーのログアウト後のイベントを、そのユーザーのレコードに統合することができます。 この動作を変更して、代わりに匿名ユーザーにこれらのイベントを記録することができます。

匿名ユーザーにイベントをログに記録するには：

1. userIdをnullに設定します。
2. 新しいdeviceIdを生成します。

現在のユーザーまたはデバイスから送信されたイベントは、Amplitudeでは新しいユーザーとして表示されます。 注: この方法を実行すると、2人のユーザーが同じデバイスを使用していたことがわかることはありません。

amplitude.getInstance().setUserId(null); // not string 'null'
amplitude.getInstance().regenerateDeviceId();

セッション追跡

30分以内に発生したイベントは、現在のセッションにカウントされます。 最初のイベントが発生した時刻はセッションの開始時刻を示し、最後にトリガーされたイベントはセッションの終了時刻を示します。 セッションのタイムアウト時間枠は、SDK 設定オプションフィールド sessionTimeoutから変更できます。

セッションIDを取得する

JavaScript SDKでは、ヘルパーメソッドgetSessionIdを使用して現在の値を取得できますsessionId：

const sessionId = amplitude.getInstance().getSessionId();

HTTPヘッダーの設定

カスタムHTTP要求ヘッダーを必要とするドメインプロキシを使用している場合は、初期化時にそれらをoptions.headers で設定してください。

amplitude.getInstance().init(AMPLITUDE_API_KEY, null, {
  headers: {
    "x-session-id": appToken,
    "Content-Type": "application/json;charset=utf-8",
  },
});

イベントを複数のプロジェクトに記録する

複数のAmplitudeプロジェクトにイベントをログ記録したい場合は、Amplitudeプロジェクトごとに別々のインスタンスが必要です。 各インスタンスでは、独立した apiKeys、userIds 、deviceIds 、および設定が可能です。

各Amplitudeプロジェクトとインスタンスに名前を割り当て、そのインスタンスを取得して関数を呼び出す際にはその名前を一貫して使用する必要があります。

インスタンス名は、null以外かつ空でない文字列でなければなりません。 名前は大文字と小文字を区別しません。各インスタンスの名前を呼び出すことで取得できます。

新しいインスタンスにはそれぞれ独自の apiKey、 userId、 deviceId、および設定があります。

次に、2 つの別々のプロジェクトにイベントを設定してログ記録する方法の例を示します。

// existing project, existing settings, and existing API key
amplitude.getInstance().init("12345", null, { batchEvents: true });
// new project, new API key
amplitude
  .getInstance("new_project")
  .init("67890", null, { includeReferrer: true });
// need to reconfigure new project
amplitude.getInstance("new_project").setUserId("joe@gmail.com");
amplitude.getInstance("new_project").setUserProperties({ gender: "male" });
amplitude.getInstance("new_project").logEvent("Clicked");
var identify = new amplitude.Identify().add("karma", 1);
amplitude.getInstance().identify(identify);
amplitude.getInstance().logEvent("Viewed Home Page");

ウェブアトリビューション

AmplitudeのJavaScript SDKはデフォルトではウェブアトリビューションデータを取り込みませんが、セットアップは簡単です。 アトリビューション設定オプションを有効にすると、SDKはこの情報を自動的に取り込むことができます。

Amplitudeは、SDK設定オプションを通じて以下のことを自動的に追跡することをサポートしています：

• includeUtmユーザーのブラウザ Cookie または URL パラメータから取得した 5 つの標準 UTM パラメータです。
• includeReferrerから参照されている URL とドメイン。
• URL パラメータから includeGclid までの範囲の Google クリック識別子です。
• Facebook から includeFbclid までのURLパラメータから取得したクリック識別子。

UTMパラメータを追跡する

UTMパラメータはUrchin Traffic Monitorパラメータの略で、さまざまな広告キャンペーンや参照サイトの効果を分析するのに役立ちます。 UTMパラメータは大文字と小文字を区別するため、Amplitudeは大文字が異なる場合にこれらのパラメータを異なる値として扱います。

標準UTMパラメータには次の5種類があります。

• utm_source: これはトラフィックを送信したウェブサイトを識別します（例：Google、Facebook）。
• utm_medium: これは使用されたリンクの種類を識別します（例: バナー、ボタン、メール）。
• utm_campaign: これは使用されている特定のキャンペーンを識別します (例: "summer_sale")。
• utm_term: これは使用されている有料検索用語を識別します (例: 製品 + 分析)。
• utm_content: これはユーザーをサイトに誘導したものを識別し、A/B テストによく使用されます (例: 「バナーリンク」、「テキストリンク」)。

以下はURLの例です。

https://www.amplitude.com/?utm_source=newsletter&utm_campaign=product_analytics_playbook&utm_medium=email&utm_term=product%20analytics&utm_content=banner-link

SDK経由で有効化

Amplitudeでは、includeUtmオプションをtrueに設定すると、JavaScript SDKは自動的に参照元URLからUTMパラメータを抽出し、関連するすべてのイベントのユーザープロパティとしてそれらを含めます。

• includeGclid：Gclid（Google クリック識別子）は Google が使用するグローバルにユニークなトラッキングパラメータです。 使用する場合、Google は実行時に URL に固有のパラメータ（例："?gclid=734fsdf3"）を追加します。 これを「true」に設定すると、SDKは initial_gclidおよび gclidをユーザープロパティとしてキャプチャします。
• includeFbclid：Fbclid (Facebook Click Identifier) は、Facebook が使用するグローバルにユニークなトラッキングパラメータです。 使用する場合、Facebook は実行時に一意のパラメータ（例："?fbclid=392foih3"）を URL に追加します。 これを「 true」に設定すると、SDKは initial_fblidおよび fbclidをユーザープロパティとしてキャプチャします。
• includeUtm：true の場合、 は URL またはブラウザ Cookie から標準の UTM パラメータを検索し、それらをユーザープロパティとして設定します。 このオプションは、utm_source、utm_medium、utm_campaign、utm_term、utm_content、およびinitial_utm_source、initial_utm_medium、initial_utm_campaign、initial_utm_term、initial_utm_contentをユーザーのユーザープロパティとして設定します。 デフォルトでは、SDKはセッションごとに1回UTMパラメータをキャプチャします。キャプチャはユーザーがサイトとAmplitude SDKを初めてロードしたときに発生します。 saveParamsReferrerOncePerSession 設定オプションを使用して、セッションごとに1回の制限を無効にできます。 SDKが新しいセッションを開始する必要があることを検出した場合、 SDKは、その時点で利用可能なUTMパラメータをプルします。 SDKはこれらのUTMパラメータをユーザープロパティとして設定します。このプロパティは、今後ユーザーのすべてのイベントに対して持続します。 ただし、SDK はsetOnce操作を通じて各ユーザーについて初期 UTM パラメータを 1 回だけ取得します。

リファラーを追跡

ユーザーがどのようにウェブサイトに到達しているかを追跡したい場合は、リファラー（参照サイト）を追跡してください。

Amplitudeは以下のフィールドを自動的に追跡することをサポートしています：

• referrer: ユーザーが最後に閲覧したページです (例: <https://amplitude.com/behavioral-analytics-platform?ref=nav>)。
• referring_domain: ユーザーが最後にいたドメイン (例: amplitude.com)。

SDK経由で有効化

includeReferrerオプションを true に設定すると、Amplitudeは各セッションのreferring_domain と referrerをキャプチャし、関連イベントのユーザープロパティとしてそれらを設定します。

• includeReferrer: trueの場合、referrer はセッションごとの および referring_domainをユーザープロパティとしてキャプチャし、initial_referrer および initial_referring_domainユーザープロパティをユーザーごとに一度だけキャプチャします。 リファラはURL全体であり、referring_domain はユーザーがアクセスしたドメイン名です。

Amplitudeは、setOnce操作を通じて各ユーザーの初期参照情報を1回取得します。

ファーストタッチのアトリビューション

Amplitudeは、各ユーザーの初期UTMパラメータとリファラー情報を取得できます。 Amplitudeは、ユーザーのヌル以外のUTMパラメータを初めて検出したときに、ファーストタッチのアトリビューション値を設定します。 Amplitudeはこれらのユーザープロパティを一度だけ設定します：

• initial_utm_source
• initial_utm_medium
• initial_utm_campaign
• initial_utm_term
• initial_utm_content
• initial_referrer
• initial_referring_domain
• initial_gclid
• initial_fbclid

JavaScript SDKの設定オプション includeReferrer、 includeUtm、includeFbclid および includeGclidを trueに設定することで、これらのパラメータを取得できます。

ラストタッチのアトリビューション

Amplitudeは、以下のユーザープロパティを設定することで、各セッションでユーザーがどこから来たかを把握します。

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• referrer
• referring_domain
• gclid
• fbclid

これを使用するには、JavaScript SDKの設定オプション includeReferrer、includeUtm 、includeFbclid および includeGclidを true に設定します。 デフォルトでは、SDKはセッションの開始時にのみ値を保存します。そのため、ユーザーが何らかのフローをトリガーして、同じセッション内で異なるUTMパラメータセットを使用してサイトに再びアクセスした場合、SDKは第2セットを保存しません。

マルチタッチアトリビューション

JavaScript SDKの設定でsaveParamsReferrerOncePerSession にfalse設定した場合、SDKは常にユーザーから新しい値をキャプチャします。これにより、これらのユーザープロパティが変更された場合、セッション全体で更新されます。

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• referrer
• referring_domain
• gclid
• fbclid

一部のお客様は、これらのユーザープロパティを配列として計測し、SDK が単一ユーザーの同一セッション内で検出したすべてのアトリビューションパラメータを追跡することもできます。

キャプチャされたアトリビューション値をAmplitude経由で記録

これは高度なユースケースです。

JavaScript SDKの設定でlogAttributionCapturedEventをtrueに設定した場合、SDK はユーザーから新しいアトリビューション値を取得するたびに、Amplitude イベントをログに記録します。

イベント名：[Amplitude]アトリビューションがキャプチャされました

イベント プロパティ：

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• referrer
• referring_domain
• gclid
• fbclid

Googleタグマネージャー

AmplitudeのJavaScript SDKは、Google Tag Managerとの連携をサポートしています。セットアップ手順については、GitHub 上のデモ アプリを参照してください。

トラブルシューティングとデバッグ

デバッグ方法

ブラウザーでのデバッグは、コードの実装に関連する問題や、使用している SDK 内の潜在的な問題を特定するのに役立ちます。 ここでは、デバッグのためにブラウザに標準搭載されている開発者ツール（DevTools）の使い方について、基本的な手順を解説します。

コンソール

JavaScript エラーは、「検査」>「コンソール」で確認できます。このページには、問題を引き起こしたコード行とファイルの詳細情報が含まれている可能性があります。 また、コンソールでは JavaScript コードをリアルタイムで実行することもできます。

• 次の手順に従ってデバッグ モードを有効にします。 デフォルトのロガーを使用すると、SDK のパブリックメソッドを呼び出すたびに、SDK はデバッグに役立つ追加の関数コンテキスト情報を開発者コンソールに出力します。
• AmplitudeはSDKの遅延初期化をサポートしています。 SDK は、初期化呼び出しの後、初期化前に追跡されたイベントをディスパッチします。 イベントを送信できないが、ブラウザコンソールに入力した後にamplitude.init(API_KEY, 'USER_ID')イベントを正常に送信できた場合は、コードベースで呼び出しがトリガーされていないか、amplitude.init初期化時に正しい Amplitude インスタンスを使用していない可能性があります。実装を確認してください。

Instrumentation エクスプローラー/Chrome拡張機能

Amplitude Instrumentation エクスプローラーは、Google Chromeウェブストアで入手できる拡張機能です。この拡張機能は、ユーザーがトリガーする各 Amplitude イベントをキャプチャし、それを拡張機能のポップアップに表示します。 SDK がイベントを正常に送信したことを確認し、イベントペイロード内のコンテキストを確認します。

一般的な問題

以下は、ブラウザSDKに固有の一般的な問題です。

ADブロッカー

Ad Blocker イベントがドロップされる原因となる可能性があります。 次のエラーは、Ad Blocker がトラッキングに影響を及ぼすことを示しています。 script タグを使用してロードする場合、SDK スクリプトのロード中にコンソール/ネットワークタブにエラーが表示されることがあります。npm パッケージを使用してロードする場合、SDK がサーバーにイベントを送信しようとしたときに、ネットワーク タブにエラーが表示されることがあります。 エラーはブラウザによって異なる場合があります。

• Chrome（Ubuntu、MacOS） コンソール： error net::ERR_BLOCKED_BY_CLIENT ネットワーク：ステータス（ブロック：その他）
• Firefox（Ubuntu） Console: エラーテキストにブロック固有の情報は含まれていません ネットワーク：転送された列には、uBlockオリジンによってブロックされているプラグインの名前が含まれています
• Safari（MacOS） コンソール：エラーにはテキストが含まれています コンテンツブロッカーにより、フレーム ... は ... からリソースをロードできませんでした。 ネットワーク：ブロックされたリクエストはリストにないようです。 それらを表示できるかどうかは不明です。

Amplitudeは、この状況を回避するためにプロキシサーバーを使用することを推奨しています。

Cookie関連

SDK がクッキーに保存する情報については、「クッキー管理」を参照してください。 クッキーを無効にしたり、プライベートブラウザ/ウィンドウ/タブを使用したりするなどのクライアントの動作は、クッキーに保存されたこれらの値の持続性に影響します。 これらの値が持続していない場合や、1 つずつ増加していない場合は、それが原因である可能性があります。

CORS

クロスオリジンリソース共有 (CORS) は、ブラウザがウェブページが異なるドメインからリソースをリクエストする方法を制限するために使用するセキュリティ対策です。 CORS を使用している場合、この問題が発生する可能性がありますsetServerURL。

Access to fetch at 'xxx' from origin 'xxx' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

クロスオリジンリソース共有(CORS)は、悪意のあるサイトが権限なく他サイトのデータを読み取ることを防ぎます。このエラーメッセージは、アクセスしようとしているサーバーが、オリジンがリクエストされたリソースにアクセスすることを許可していないことを示しています。 この原因は、サーバーの応答にAccess-Control-Allow-Originヘッダーが欠落していることです。

• サーバーを制御できる場合は、サーバーのCORSポリシーを更新できます。サーバーの応答にAccess-Control-Allow-Originヘッダーを追加します。 この変更により、オリジンがリクエストを行うことができます。 Access-Control-Allow-Originの値は、すべてのオリジンを許可するか、ウェブページの特定の URL を許可するか*です。
• サーバーを制御できない場合は、必要な CORS ヘッダーを追加するプロキシサーバーを設定できます。 ウェブページはプロキシにリクエストを送信し、プロキシが実際のサーバーにリクエストを送信します。 プロキシはレスポンスにAccess-Control-Allow-Originヘッダーを追加した後で、そのレスポンスをウェブページに返送します。

APIプロキシを設定し、選択したプラットフォームでそれに関連する設定の問題が発生した場合、それはもはやSDKの問題ではなく、アプリケーションとサービスプロバイダー間の連携の問題です。

イベントが発生したが、ネットワークリクエストが発生しなかった

ロガーを「デバッグ」レベルに設定し、開発者コンソールに呼び出しのトラックが表示された場合、SDK はこのtrack()メソッドを呼び出しました。 Amplitude、Amplitude Instrumentation エクスプローラーChrome拡張機能、またはブラウザのネットワークリクエストタブに該当するイベントが表示されない場合、SDKはイベントをAmplitudeに送信していません。SDK は、呼び出しが成功するとイベントを発行して SDK の内部キューに配置しますが、これらのキューに登録されたイベントが正常に送信されない場合がありますtrack()。 これは、ブラウザが進行中のHTTPリクエストをキャンセルした場合に発生することがあります。 たとえば、ブラウザを閉じたり、ページを離れたりした場合などです。

この問題に対処するには、次の 2 つの方法があります。

1. 標準的なネットワーク要求を使用する場合は、初期化時に transport を beaconに設定するか、ページ終了時に transport を beaconに設定してください。sendBeacon はバックグラウンドでイベントを送信し、4xx や 5xxなどのサーバー応答を返さないため、この場合機能しません。 その結果、失敗しても再試行は行われません。sendBeacon はスケジュール済みの要求だけをバックグラウンドで送信します。 詳細については、「sendBeacon」セクションを参照してください。
2. track() を同期させるには、呼び出しの前にawaitキーワードを追加します。

高度なトピック

動的な設定

バージョン8.9.0以降では、動的設定を使用するようにアプリを設定できるようになりました。 この機能は、アプリユーザーの所在地に基づいて最適なサーバー URL を自動的に検出します。

使用するには、useDynamicConfig をtrue に設定してください。

• 独自のプロキシサーバーを持ち、apiEndPointAPIを使用している場合は、動的設定をオフにしておいてください。
• 中国本土にユーザーがいる場合、Amplitudeは動的設定の使用を推奨しています。
• デフォルトでは、この機能はAmplitudeの米国サーバーのサーバーURLを返します。 AmplitudeのEUサーバーにデータを送信する必要がある場合は、setServerZoneを使用してEUゾーンに設定してください。

amplitude.getInstance().init(euApiKey, null, {
  useDynamicConfig: true,
});

COPPA制御

Amplitudeの他のSDKのCOPPAコントロールは、IDFA、IDFV、都市、ロケーションデータ（location_latおよびlocation_lng）、IPアドレスの追跡を無効にします。 SDKが、location_lat、location_lngIDFA、またはIDFVを追跡しないため、JavaScript SDKにはCOPPA制御用のインターフェイスがありません。代わりに、city および ip_addressとのトラッキングを無効にすることができますtrackingOptions。

var trackingOptions = {
  city: false,
  ip_address: false,
};

デバイスIDを取得する

次のコードを使用して、ユーザーの現在のデバイスIDを取得します。

var deviceId = amplitude.getInstance().getDeviceId(); // existing device ID

構成オプションを設定する

Amplitudeを設定するには、initの第3引数としてオブジェクトを渡します。

amplitude.getInstance().init(AMPLITUDE_API_KEY, null, {
  // optional configuration options
  saveEvents: true,
  includeUtm: true,
  includeReferrer: true,
});

Cookieの管理

SDK によって作成される Cookie

初期化時に、SDK はプレフィックス で始まり、amp_API キーの最初の 6 桁で終わる Cookie を作成します。 たとえば、amplitude.getInstance().init("a2dbce0e18dfe5f8e74493843ff5c053") はキーを使用してCookieを作成しますamp_a2dbce。

この Cookie は、SDK に関する次のメタデータを追跡します。

• ランダムに生成されたデバイス ID
• 現在のセッションID
• 現在のユーザーID（ユーザーIDが設定されている場合）
• 最終イベント時間
• イベントを正しい順序で配置し、操作を識別するためのシーケンスID

Cookieを無効にする

disableCookiesオプションを使用して、SDKによって作成されたCookieを無効にします。 Cookie を無効にすると、JavaScript SDK はデフォルトで localStorage を使用してデータを保存します。 LocalStorage は便利な代替手段ですが、ドメイン間で Cookie を追跡することはできません。 ブラウザは localStorageへのアクセスをサブドメインごとに制限しているため、プロダクトのサブドメイン全体にわたって匿名ユーザーを追跡することはできません (例: www.amplitude.comと analytics.amplitude.com)。

SameSite

JavaScript SDK はデフォルトで、その Cookie の SameSite オプションを None に設定しています。 これは、sameSiteCookie オプションで上書きできます。 AmplitudeはLaLaxxの使用を推奨します。ただし、お客様のサイトにフォームを``POSTPOSTするサードパーティサイトがある場合は例外です。

HTTPのみのクッキー

HTTPOnlyオプションは、SDKが作成するCookieに対して技術的に実現できません。 SDKはクライアント側でCookieを設定し、Cookieをクライアント側のデータストアとして使用します。SDK CookieはHTTPOnlyフラグを設定できません。

レガシーCookieのアップグレード

SDKが作成したレガシーCookieは、よりコンパクトな新しいCookieよりも大きかったです。 古いCookieを持つユーザーの場合、オプションが cookieForceUpgrade に設定されている場合、SDKは古いCookieのみを削除し、新しいCookie形式の使用を開始します。true SDKを複数の製品で使用し、それらの製品間で匿名ユーザーを追跡する場合は、これらのすべての製品でこのオプションを設定してください。

RequireJS

RequireJSを使用してJavaScriptファイルを読み込む場合、読み込みスニペットを使用する代わりに、RequireJSを使用してAmplitude JavaScript SDKスクリプトを直接読み込むことができます。 このアプローチを取ると、スニペットの重要な利点の1つを失うことになります。この利点は、Amplitudeが完全にダウンロードされるのを待たずにアプリを起動してAmplitude SDKを使用できるようにすることです。

<script src="scripts/require.js"></script>
<!-- loading RequireJS -->
<script>
  require([
    "https://cdn.amplitude.com/libs/amplitude-6.2.0-min.umd.gz.js",
  ], function (amplitude) {
    amplitude.getInstance().init(AMPLITUDE_API_KEY); // replace AMPLITUDE_API_KEY with your Amplitude API key.
    window.amplitude = amplitude; // You can bind the amplitude object to window if you want to use it directly.
    amplitude.getInstance().logEvent("Clicked Link A");
  });
</script>

また、RequireJS設定で次のようにパスを定義することもできます：

<script src="scripts/require.js"></script>
<!-- loading RequireJS -->
<script>
  requirejs.config({
    paths: {
      amplitude: "https://cdn.amplitude.com/libs/amplitude-6.2.0-min.umd.gz.js",
    },
  });
  require(["amplitude"], function (amplitude) {
    amplitude.getInstance().init(AMPLITUDE_API_KEY); // replace AMPLITUDE_API_KEY with your Amplitude API key.
    window.amplitude = amplitude; // You can bind the amplitude object to window if you want to use it directly.
    amplitude.getInstance().logEvent("Clicked Link A");
  });
</script>
<script>
  require(["amplitude"], function (amplitude) {
    amplitude.getInstance().logEvent("Page loaded");
  });
</script>

クロスドメイン追跡（JavaScript）

2つの異なるドメインにわたって匿名の行動を追跡できます。 Amplitudeは匿名ユーザーをデバイスIDで識別します。このIDはドメイン間で渡す必要があります。 例えば：

• サイト 1：www.example.com
• サイト 2：www.example.org

サイト 1 で作業を開始し、サイト 2 に移動するユーザーは、サイト 1 から生成されたデバイス ID をパラメータとしてサイト 2 に渡す必要があります。その後、サイト 2 はデバイス ID を使用してSDKを初期化する必要があります。 deviceIdFromUrlParamが有効になっている場合、SDKはURLパラメータを自動的に解析できます。

1. サイト 1 から、デバイス ID を amplitude.getInstance().options.deviceId から取得します。
2. ユーザーがナビゲートするときに、URLパラメータを通じてデバイスIDをサイト2に渡します（例：www.example.com?amp_device_id=device_id_from_site_1）。
3. amplitude.init(AMPLITUDE_API_KEY, null, {deviceIdFromUrlParam: true})を使用してサイト2でAmplitude SDKを初期化します。

UTMパラメータ、リファラ、およびgclidのトラッキング（JavaScript）

Amplitudeは自動トラッキングをサポートしています：

• 初期化時に設定オプションが true に設定されている場合、ユーザーの Cookie または URL パラメータから得られる標準 UTM パラメータincludeUtm。
• 初期化時に設定オプションincludeReferrerが true に設定されている場合の参照元 URL。
• gclid (Google Click ID) は、初期化時に設定オプション includeGclid が true に設定されている場合の URL パラメータから取得されます。

トラッキングを有効にすると、SDK はセッションごとに一度値をユーザープロパティとして設定します (例: referrerまたは utm_source)。 これは「ラストタッチアトリビューション」と呼ばれます。 また、SDKはinitial_referrer操作を使用して、setOnce初期値を保存します。initial_utm_source SDK がこれらの値を設定した後は、これらの値は変更されません。 これはファーストタッチアトリビューションと呼ばれます。

saveParamsReferrerOncePerSession

デフォルトでは、SDK はセッションの開始時にのみ値を保存します。 たとえば、ユーザーが初期のUTMパラメータセットを使用してサイトにアクセスし、ユーザーを誘導する何らかのフローをトリガーした場合 同じAmplitudeセッション内で異なるUTMパラメータセットを使用してサイトに再度アクセスする場合、SDKは2番目のセットを保存しません。 この制限を解除するために設定オプションを saveParamsReferrerOncePerSessionに設定できます。これにより、SDK は常にユーザーから新しい値を収集falseできます。

unsetParamsReferrerOnNewSession

デフォルトでは、SDK は新しいセッションの開始時に既存の UTM パラメータとリファラーの値を継承します。 例えば：ユーザーのセッションが期限切れになると、SDK はユーザーの Referrer と UTM パラメータを既存の値にマップします。 SDK が新しいセッションをインスタンス化するときにこれらの値を null にリセットするには、unsetParamsReferrerOnNewSession に設定しますtrue。

logEvent、identify 、redirect のコールバック

コールバック関数を logEvent および identifyに渡すことができます。この関数は SDK がサーバーからの応答を受信した後に呼び出します。 これは、ブラウザがウェブページから離れる前にタイミングが原因でSDKがイベントのキャプチャを逃す可能性がある場合に役立ちます。 logEventメソッドのコールバックにナビゲーションを記述することで、SDK はナビゲーションが発生する前にイベントを確実にキャプチャできます。 以下は logEvent の例です。

amplitude.getInstance().logEvent("EVENT_TYPE", null, callback_function);

次に、identifyの例を示します。

var identify = new amplitude.Identify().set("key", "value");
amplitude.getInstance().identify(identify, callback_function);

SDK はステータスとレスポンス本文をサーバーからコールバック関数に渡します。これは役に立つ場合があります。 以下は、レスポンス後にブラウザを別のサイトにリダイレクトするコールバック関数の例です。

var callback_function = function (status, response) {
  if (status === 200 && response === "success") {
    // do something here
  }
  window.location.replace("URL_OF_OTHER_SITE");
};

また、この機能を使用して、ウェブサイトへのアウトバウンドリンクを追跡することもできます。 たとえば、次のようなリンクがあるとします。

<a href="javascript:trackClickLinkA();">Link A</a>

次に、ユーザーがリンクをクリックしたときに実行される関数を次のように定義します。

var trackClickLinkA = function () {
  amplitude.getInstance().logEvent("Clicked Link A", null, function () {
    window.location = "LINK_A_URL";
  });
};

optOutが trueである場合、SDK はイベントをログに記録しませんが、コールバックを呼び出します。 batchEvents が true の場合、logEvent を呼び出したときにバッチ要件の eventUploadThreshold と eventUploadPeriodMillis が満たされていなくても、SDK はリクエストを送信しませんが、コールバックは呼び出します。 このような場合、SDK は入力ステータスを 0 とし、「リクエストは送信されていません」という応答でコールバックを呼び出します。

エラーコールバック

イベントのネットワークリクエストが失敗した場合に SDK が呼び出す 2 つ目のコールバックを、logEvent と identify に渡すことができます。 これは、ユーザーが広告ブロッカーを使用しているかどうかを検出する場合や、イベント形式の問題が原因でAmplitudeサーバーからエラーが発生しているかどうかを検出する場合に役立ちます。 エラーコールバックは、次のように成功コールバックと組み合わせて使用できます。

var successCallback = function () {
  console.log("the event was logged successfully");
};
var errorCallback = function () {
  console.log("there was an error logging the event");
};
amplitude.getInstance().logEvent("event", null, successCallback, errorCallback);

init コールバック

また、SDK が非同期読み込みを完了した後に呼び出すコールバック関数を init に渡すこともできます。 SDKはインスタンスをコールバックの引数として渡します：

amplitude
  .getInstance()
  .init(AMPLITUDE_API_KEY, "USER_ID", null, function (instance) {
    console.log(instance.options.deviceId); // access Amplitude's deviceId after initialization
  });

sendBeaconを使用する

SDK バージョン 8.5.0 以降では、SDK はブラウザに組み込まれている navigator.sendBeacon API を使用してイベントを送信できます。 標準的なネットワーク要求とは異なり、sendBeacon はユーザーがブラウザを閉じたりページを離れたりしても、バックグラウンドでイベントを送信します。

sendBeacon を使用してイベントを送信するには、2 つの方法のいずれかでトランスポート SDK オプションを 'beacon' に設定します

// set transport to 'beacon' when initializing an event
amplitude
  .getInstance()
  .init(AMPLITUDE_API_KEY, "USER_ID", { transport: "beacon" });
// set transport to 'beacon' after initialization
amplitude.getInstance().setTransport("beacon");
// this event will be sent using navigator.sendBeacon
amplitude.getInstance().logEvent("send event with beacon");
// set transport back to the default 'http' value
amplitude.getInstance().setTransport("http");
// this event will be sent using the standard xhr mechanism
amplitude.getInstance().logEvent("send event with http");

ページを終了するときにのみ sendBeacon を使用する

JavaScript SDK には、ユーザーがページを終了したときにのみ実行されるコールバック関数があります。 コールバックで送信されたすべてのログについて、転送を「ビーコン」に自動的に切り替えます。 このコールバックはonExitPageで呼び出されるもので、次のように初期化時にSDKに渡します。

var exitCallback = function {
 amplitude.getInstance().logEvent('Logging a final event as user exits via sendBeacon');
};
amplitude.getInstance().init(AMPLITUDE_API_KEY, 'USER_ID', { onExitPage: exitCallback });

デバイスIDのライフサイクル

SDKはデバイスIDを次の順序で初期化し、デバイスIDを最初に検出した有効な値に設定します。

1. 初期化時の設定内のデバイス ID。
2. URLパラメータからの「amp_device_id」値（configuration.deviceIdFromUrlParamtrueの場合）。詳細については、「クロスドメイン追跡」を参照してください。
3. クッキーストレージ内のデバイスID。詳細については、「クッキーの管理」を参照してください。
4. ランダムに生成された 22 文字の base64 ID です。 この ID は、同じ 128 ビット範囲を持つ 36 文字の UUID よりもコンパクトです。

デバイス ID が変更されるのはいつですか

デバイスIDはさまざまなシナリオで変更されます。

Amplitude Analytics SDKは、実験SDKとアイデンティティストアを共有します。

setDeviceIdまた、IDストアを更新して新しいユーザー情報を実験SDKに伝播し、デバイスIDが変更された場合に取得をトリガーします。

• setDeviceId()明示的に呼び出します。
• デフォルトでは、SDKはデバイスIDをCookieに保存するため、ユーザーがCookieをクリアしたり、別のデバイスを使用したり、プライバシーモードを使用したりすると、デバイスIDは変更されます。
• deviceIdFromUrlParamが有効になっている場合、SDK は初期化時にデバイス ID を URL パラメータからamp_device_id取得します。

カスタムデバイスID

setDeviceId()を使用して、新しいデバイスIDを割り当てることができます。 カスタムデバイスIDを設定する場合は、値が十分に一意であることを確認してください。AmplitudeはUUIDの使用を推奨しています。

デフォルトでは、デバイス ID はランダムに生成された base64 ID です。 カスタムデバイス ID は、設定オプションとして設定するか、setDeviceId を呼び出すことで定義できます。

amplitude.getInstance().setDeviceId("DEVICE_ID");

デバイスIDを取得する

Amplitudeが使用しているデバイスIDは、Amplitude.getInstance().getDeviceId()またはAmplitude.getInstance('YOUR-INSTANCE-NAME').getDeviceId()カスタムインスタンス名を定義している場合はで取得できます。このメソッドは、SDK が deviceIdをまだ生成していない場合に返すことができますnull。

const deviceId = amplitude.getInstance().getDeviceId();

現在のデバイスIDを別のインスタンスと共有する

複数のAmplitude JavaScript SDKインスタンスがセットアップされており、デバイスIDをインスタンス間で共有したい場合があります。

• 方法1: 設定内のデバイスIDを使用してもう一方のインスタンスを初期化する

// Initialize an instance with default configuration
// Device Id of this instance is created by default
var instanceDev = amplitude.getInstance("amplitude-dev");
instanceDev.init("API-KEY-1");
// Initialize another instance with a different API key
// And pass the deviceId from the previous instance to the configuration
var instanceProd = amplitude.getInstance("amplitude-prod");
instanceProd.init("API-KEY-2", undefined, {
  deviceId: instanceDev.getDeviceId(),
});

• 方法2：初期化後、デバイスIDを同じにする必要があるときにいつでも設定する

var instanceDev = amplitude.getInstance("amplitude-dev");
instanceDev.init("API-KEY-1");
var instanceProd = amplitude.getInstance("amplitude-prod");
instanceProd.init("API-KEY-2");
// Before the line blow, the device Ids of the two instances are different
instanceProd.setDeviceId(instanceDev.getDeviceId());

• 方法3：URLパラメータにデバイスIDを渡しますamp_device_id。詳細については、「クロスドメイン追跡」を参照してください。

コンテンツセキュリティポリシー（CSP）

ウェブアプリがセキュリティ上の懸念から厳格なコンテンツセキュリティポリシー（CSP）を設定している場合は、Amplitudeドメインを許可するようにポリシーを調整してください：

• 「スニペット」を使用する場合は、script-src に追加してくださいhttps://*.amplitude.com。
• https://*.amplitude.comをconnect-srcに追加してください。