カスタムエンリッチメントプラグイン

カスタムエンリッチメントプラグインは、SDK がイベントをアップロードする前に、ブラウザ SDK がトラッキングするすべてのイベントに対してエンリッチメント関数を実行します。Amplitudeはその機能をプロジェクトのリモート設定に保存するため、サイトの新しいビルドを出荷することなくその機能を変更できます。

このプラグインはデフォルトではオフになっています。customEnrichment設定オプションを使用して有効にしてください。

このプラグインは、ユーザーが作成するプラグインに影響を与えません。

このプラグインは、amplitude.add() を使用して追加するカスタムプラグインとは別物です。customEnrichmentを有効化または無効化にしても、独自のプラグインには影響しません。このプラグインを有効にしているかどうかにかかわらず、独自のプラグインは引き続き動作します。

要件

@amplitude/analytics-browserバージョン 2.37.0 以降。
リモート設定が有効になりました。SDK はデフォルトでリモート設定を取得します。 remoteConfig.fetchRemoteConfigをfalseに設定した場合、プラグインはロードされますが関数を受け取らないため、すべてのイベントは変更されずにそのまま残ります。リモート設定を参照してください。
プロジェクトのリモート設定で定義されているエンリッチメント関数です。SDK はローカル設定から関数を読み取ることはありません。

プラグインを有効にする

SDK を初期化するときにcustomEnrichmentを true に設定します。

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init(AMPLITUDE_API_KEY, {
  customEnrichment: true,
});

名前	概要	デフォルト値
`customEnrichment`	`boolean`。 SDK が Custom Enrichment プラグインを追加するかどうか。	`false`

Amplitudeのリモート設定でもプラグインを有効にできます。ただし、例外が1つあります。初期化時にcustomEnrichment: falseを設定した場合、リモート設定で再度有効にすることはできません。リモート設定でプラグインを制御する場合は、オプションをfalseに設定するのではなく、オプション自体を指定しないでください。

SDK はリモート設定からのみエンリッチメント機能を読み取ります。ローカル設定で関数本体を渡しても効果はありません。

プラグインの仕組み

セットアップ時に、プラグインはプロジェクトのリモート設定内のconfigs.analyticsSDK.browserSDK.customEnrichmentキーを購読します。
リモート設定から関数本体が配信されると、プラグインはそれを評価し、イベントを受け取ってイベントを返す関数を生成します。
イベントが SDK のエンリッチメントステージを通過する際に、プラグインはオートキャプチャされたイベントを含むすべてのイベントに対して、その関数を実行します。
リモート設定が有効な関数ボディを送信しない場合、プラグインはすべてのイベントをそのまま受け渡します。

プラグインはリモート設定を一度読み取るのではなくサブスクライブしているため、エンリッチメント関数が更新されると、ページを再読み込みしなくてもアクティブなセッションに反映されます。

戻り値

エンリッチメント関数が返す内容によって、Amplitudeが受信する内容が決まります。

イベントを返します。SDK は返されたイベントをアップロードします。このようにして、関数はプロパティを追加、変更、または削除します。
何も返されません。SDK はイベントをドロップし、イベントは Amplitude に到達しません。イベントを返すことを忘れるエンリッチメント関数は、すべてのトラフィックを静かに廃棄します。
エラーをスローします。SDK はエラーを記録し、エンリッチされていないオリジナルのイベントをアップロードします。

設定された関数本体が関数と評価されない場合、プラグインはエラーを記録し、すべてのイベントをそのまま受け渡します。

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

このプラグインは、実行時にリモート設定からエンリッチメント関数を評価します。サイトで script-src を制限するコンテンツセキュリティポリシーを設定している場合、そのポリシーはプラグインが関数を構築できるようにunsafe-evalする必要があります。この機能がないと、ブラウザは評価をブロックし、プラグインはエラーを記録し、イベントは変更なく通過します。

ブラウザ SDK に必要なその他のポリシー調整については、「コンテンツセキュリティポリシー（CSP）」を参照してください。

トラブルシューティング

プラグインの動作を記録するには、logLevelをDebugに設定します:

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init(AMPLITUDE_API_KEY, {
  customEnrichment: true,
  logLevel: amplitude.Types.LogLevel.Debug,
});

ログメッセージ	ITが意味すること
`Adding custom enrichment plugin`	SDK によってプラグインが有効化され、追加されました。
`Installing @amplitude/plugin-custom-enrichment-browser`	プラグインのセットアップが開始されました。
`Remote config client is not provided, skipping remote config fetch`	このプラグインはリモート設定に到達できないため、イベントは変更されません。リモート設定がオンになっていることを確認してください。
`Custom enrichment body did not evaluate to a function`	リモート設定により、関数ではないボディが配信されました。イベントは変わらずに進行します。
`Could not create custom enrichment function`	プラグインはボディを評価できませんでした。コンテンツセキュリティポリシーを確認してください。
`Could not execute custom enrichment function`	エンリッチメント関数がエラーをスローしました。 SDK は元のイベントをアップロードします。

ログに Adding custom enrichment plugin が含まれていない場合、SDK はプラグインを有効にしていません。初期化オプションで customEnrichment が false に設定されていないことを確認してください。

Googleタグマネージャー

Amplitude ブラウザー SDK GTM テンプレートでは、このプラグインがinitタグの カスタムエンリッチメントプラグインを有効にする チェックボックスとして公開されています。 Google タグマネージャー（クライアント）を参照してください。

Was this helpful?