ガイドと調査 Web SDK。

AmplitudeのガイドとサーベイSDKを使用すると、ウェブサイトやアプリケーションにガイドとサーベイをデプロイできます。

SDKをインストールする

ガイドとサーベイは、既存のAmplitude実装環境（存在する場合）と最適に連携できるように、さまざまなインストールオプションをサポートしています。

Amplitude Browser SDK 2

Amplitude Browser SDK v2を使用している場合は、ガイドとサーベイSDKをスクリプトとともにインストールするか、npmまたはYarnを含むパッケージとしてインストールしてください。

このアプローチでは、Amplitude Browser SDKのプラグインシステムを使用しています。これにより、コアとなるアナリティクスSDKを拡張して追加機能を追加できます。呼び出しによってガイドとサーベイがプラグインとしてamplitude.add(engagementPlugin())登録されます。ガイドとサーベイはアナリティクスと並行して初期化され、同じAPIキーとユーザーIDを共有し、アナリティクスと直接通信します。 これらをinit個別bootに呼び出す必要はありません。

amplitude.init() の前に amplitude.add(engagementPlugin())を呼び出します。これにより、アナリティクス SDK はプラグインの初期化を制御できるようになります。そのため、ガイドとサーベイの起動時にユーザー ID とセッションの準備が整います。

<script src="https://cdn.amplitude.com/script/API_KEY.engagement.js"></script>
<script>
  amplitude.add(window.engagement.plugin());
</script>

await amplitude.init("API_KEY").promise;
amplitude.add(engagementPlugin());

追加の設定については、plugin関数にInitOptions供給してください。 SDK の初期化に移動して、利用可能なオプションについて確認してください。

たとえば、プラグインは自動的に次のことを呼び出すため、プラグイン時に自動更新を設定するためにboot() autoRefreshIntervalSecondsを使用します。

import { plugin as engagementPlugin } from "@amplitude/engagement-browser";
amplitude.add(
  engagementPlugin({
    autoRefreshIntervalSeconds: 3600,
  }),
);

Amplitude Browser Unified SDK

Amplitude Browser Unified SDKには、デフォルトでガイドとサーベイが含まれています。 初期化時にエンゲージメントオプションを提供してください。

import { initAll } from "@amplitude/unified";
initAll("YOUR_API_KEY", {
  // Other Amplitude SDK options...
  engagement: {
    // Guides and Surveys options go here...
  },
});

ガイドとサーベイを表示するには、Amplitudeプロジェクト設定でガイドとサーベイを有効にしてください。 詳細については、Unified SDK のドキュメントを参照してください。

スタンドアロンインストール：その他のAmplitude SDK、サードパーティのアナリティクスプロバイダー、プロキシ設定

次の場合にこのスタンドアロンインストールパスを使用してください。

• Browser SDK 2またはBrowser Unified SDK以外のAmplitude SDKを使用してください。
• サードパーティのアナリティクスプロバイダーを使用してください（Segment、Heap、またはMixpanelなど）。
• Browser SDK 2をプロキシサーバーで使用します。

このインストールには、次の手順が必要です。

1. ガイドとサーベイ SDK を script タグ付きで追加するか、npmまたは yarnを使用して追加します。
2. ガイドとサーベイを初期化し、アナリティクスプロバイダーに接続するために、init と bootを直接呼び出します。

SDKの初期化

バンドルを完全に初期化し、グローバルウィンドウオブジェクトに登録するためにengagement呼び出initしてください。

engagement.init(apiKey: string, options: { serverZone: "US" | "EU", serverUrl: string, cdnUrl: string, mediaUrl: string, logger: Logger, logLevel: LogLevel, locale: string, nonce: string, autoRefreshIntervalSeconds: number, skip: boolean, transport: { headers: Record<string, string> | (() => Record<string, string>), handleHttpRequest: (request: TransportHttpRequest) => Promise<Response> } }): void

例：基本的な初期化

engagement.init("YOUR_API_KEY", {
  serverZone: "US",
  logLevel: LogLevel.Warn,
});

例：プロキシを使用した初期化

プロキシ設定の場合、serverUrl 、cdnUrl 、mediaUrl を指定します。AI アシスタントを使用している場合は以下chatUrlを追加してください。チャットリクエストが別のホストに送信されます：

engagement.init("YOUR_API_KEY", {
  serverUrl: "https://your-proxy-domain.cloudfront.net",
  cdnUrl: "https://your-proxy-domain.cloudfront.net",
  mediaUrl: "https://your-proxy-domain.cloudfront.net",
  chatUrl: "https://your-proxy-domain.cloudfront.net",
});

例：CSP nonce を使用した初期化

コンテンツセキュリティポリシー（CSP）コンプライアンスのため、nonce 値を含めます：

engagement.init("YOUR_API_KEY", {
  nonce: "YOUR_NONCE",
});

例：自動更新による初期化

自動更新を有効にすると、ターゲットデータを定期的に再取得し、設定をリロードできます。

engagement.init("YOUR_API_KEY", {
  autoRefreshIntervalSeconds: 3600,
});

例: スキップによる初期化の遅延

SDKを初期化したり、プロキシを設定したりせずに、ウィンドウオブジェクトにengagementを登録する場合に使用skipします。初期化を完了するために、skipなしでinit後で再度を呼び出し、その後にboot()を呼び出して開始してください。

// Register the engagement object without initializing
engagement.init("YOUR_API_KEY", { skip: true });
// Later, when ready to initialize
engagement.init("YOUR_API_KEY", { serverZone: "US" });
engagement.boot({ user_id: "USER_ID" });

この関数を呼び出した後、SDK 関数にアクセスしてwindow.engagement呼び出すことができます。 ガイドとサーベイは、bootを呼び出すまで完全に機能しません。

起動ユーザー

ユーザーにガイドとサーベイを利用できるようにするには、initafterbootを呼び出してください。スタンドアロンインストールの場合、SDKスクリプトがページにロードされていても、ガイドとサーベイはbootを呼び出すまで機能しません。

パラメータオプション、型定義、使用例など、このメソbootッドに関する詳細なドキュメントについては、Bootを参照してください。

次の例では、ユーザーID、デバイスID、およびユーザープロパティを使用してbootを呼び出します。また、ガイドとサーベイのイベントをアナリティクスプロバイダーにintegrations転送するように指定します。

await window.engagement.boot({
  user: {
    user_id: "user123",
    device_id: "device456",
    user_properties: {
      plan: "premium",
    },
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

イベントの転送

「On event tracked」トリガーを使用するには、アナリティクスプロバイダーからイベントをガイドとサーベイに転送します。ガイドとサーベイ SDK はこれらのイベントを Amplitude に送信しません。SDK はこれらをローカル トリガー評価にのみ使用します。

analytics.on("track", (event, properties, options) => {
  // Example for Segment Analytics
  window.engagement.forwardEvent({
    event_type: event,
    event_properties: properties,
  });
});

セグメントを使用した場合のイベントの起動と転送の例

Googleタグマネージャー

まだお済みでない場合は、Amplitudeテンプレートの最新バージョンに更新してください。 GTMのテンプレートページで更新アイコンを見つけます。

次に、[タグ] ページで、[ガイドとサーベイ] を有効にします。

インストールと初期化の確認

ガイドとサーベイSDKがお客様のサイトまたは開発環境で実行されていることを確認するには、ブラウザの開発者ツールを開き、コンソールに次のように入力します。

window.engagement;

回答が「undefined」の場合、ガイドとサーベイは正しくインストールされていません。

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

組織が厳格なコンテンツセキュリティポリシー（CSP）を定めている場合、ガイドとサーベイは円滑に運用できるようにいくつかの追加を必要とします。次の CSP ディレクティブをポリシーに追加してください。

script-src: https://*.amplitude.com;
connect-src: https://*.amplitude.com;
img-src: https://*.amplitude.com;
media-src: https://*.amplitude.com;
style-src: https://*.amplitude.com;

インラインスタイルをブロックするような厳しいCSP要件を持つ環境では、初期化時にこのnonceパラメータを使用してください。このパラメータを使用すると、ガイドとサーベイは、CSP の nonce 値を含めることで必要なインラインスタイルを実行できます。

engagement.init("YOUR_API_KEY", {
  nonce: "YOUR_NONCE",
});

iframe のサポートと制限事項

ガイドとサーベイは、iframeを使用するアプリケーションに対するサポートが限定されています。ガイドとサーベイをiframeベースのアプリケーションに実装する際には、これらの制限事項を考慮してください。

iframe 内の要素をターゲットに設定するには:

• ピンやツールチップは、親アプリケーションの iframe 内の要素をターゲットにすることはできません。
• 各iframeには、そのiframe内にガイドやサーベイを表示するために、独自のSDKインスタンスが必要です。
• CSS セレクターは iframe の境界を越えることができないため、SDK は iframe 内の要素を検索できません。

SDK インスタンスと複数ステップのエクスペリエンス：

• 各 iframe には、親アプリケーションと同じ API キーで初期化された別個の SDK インスタンスが必要です。
• 親アプリケーションとiframeにまたがるマルチステップツアーはサポートされていません。
• 各SDKインスタンスは独立して動作するため、異なるコンテキスト間でステップを調整することはできません。

イベントトラッキングとユーザー識別：

• iframe内で追跡されるイベントは、親アプリケーション内のイベントとは独立しています。
• すべてのSDKインスタンス間で一貫したユーザー識別情報（ユーザーIDとデバイスID）を確保します。
• 各SDKインスタンスは独自の状態を維持し、他のインスタンスとデータを共有することはありません。

ツールバーとプレビュー：

• 各 SDK インスタンスは独自のデバッグおよびプレビューツールバーをレンダリングするため、iframe を含むページには複数のツールバーが表示されます。
• 各ツールバーにはインスタンス名 (default または iframe: {id}) が付いた色付きのバッジが表示され、他のツールバーと縦方向に重ねられているため、重複しているツールバーは常にアクセス可能です。
• 各ツールバーは独自のインスタンスのみを制御します。 要素の選択とプレビューは、インスタンスが起動したフレームに作用するため、ターゲット要素を保持しているフレームに一致するツールバーを選択してください。

推奨されるアプローチ：

• 親アプリケーションとガイドやサーベイを表示する必要がある各iframeの両方にSDKをインストールしてください。
• ユーザー識別の一貫性を確保するため、すべてのSDKインスタンスに同じAPIキーを使用してください。
• ガイドやサーベイを単一のコンテキスト（親または特定のiframeのいずれか）内で機能するように設計します。

インストールのトラブルシューティング

ガイドとサーベイのインスツルメンテーションが機能しない場合は、次のトピックを確認してください。

ガイドとサーベイのインストールを確認する

1. ブラウザの開発者コンソールを開き、window.engagement と入力します。 返り値が undefinedの場合、ガイドとサーベイのインストールは成功していませんでした。
2. 有効なレスポンスが返された場合は、window.engagement と入力します。window.engagement._.user undefinedが返されると、Amplitude Browser SDK プラグイン設定に問題があることがわかります。
3. その他のデバッグを行うには、window.engagement._debugStatus() と入力します。 出力は次のようになります。

{
  "user": {
    "user_id": "test-base-user-1vxxkg",
    "device_id": "62c5e45a-94ab-4090-b053-3f28e848763f",
    "user_properties": {
      "foo": "bar"
    }
  },
  "apiKey": "6ae8d3d7d48eadfb0b2489db692e14c9",
  "stateInitialized": true,
  "decideSuccessful": true,
  "num_guides_surveys": 2,
  "analyticsIntegrations": 1
}

次のことを確認してください。

• userオブジェクトが存在します。
• apiKey 設定されています。
• stateInitialized は trueです。
• decideSuccessful は trueです。
• num_guides_surveys は、ガイドや調査をページ上に表示する必要がある場合に、 ゼロ以外の整数です。

Amplitude Browser SDK プラグイン設定を確認する

Amplitude Browser SDK 2.0を使用している場合は、ブラウザのコンソールでエラーがないか確認してください。 存在しない場合は、コードがインストール手順と一致していることを確認してください。 特に、コードに amplitude.add(window.engagement.plugin()) が存在することを確認してください。

amplitude is not definedや cannot read properties of undefined .add()などのエラーが表示された場合、Amplitude SDK がロードされる前にガイドとサーベイがロードされることがあります。 コードを確認して、Amplitude Browser SDK がガイドとサーベイ SDK よりも先にロードされることを確認してください。

ガイドとサーベイにはBrowser SDK 2が必要であり、従来のAmplitude JavaScript SDKをサポートしていません。

Google タグマネージャーの設定

Google Tag Managerを使用している場合は、必ず最新のAmplitudeテンプレートに更新してください。

一般的な根本原因

以下の一般的なエラーは、ガイドとサーベイの実行を妨げる原因となります。

boot 複数回実行されます

2回以上呼び出すと、特にすぐに表示されるはずbootのガイドやサーベイでは予期しない動作が発生します。

間違ったプロジェクトが使用されています

提供するAPIキーが以下の条件を満たしていることを確認してください。

• ブラウザSDKの初期化に使用するキーと同じであること。
• ガイドとサーベイの設定を含むプロジェクトに属しています。

ガイドとサーベイ、およびアナリティクスに異なるAPIキーを使用すると、SDKが間違ったプロジェクトからガイドとサーベイを取得し、不完全なアナリティクスデータや不一致なアナリティクスデータが発生します。両方のSDKに常に同じAPIキーを使用することで、それらが同じAmplitudeプロジェクトに関連付けられていることを確認してください。

ローカリゼーション

ガイドやアンケートをローカライズするには、初期化時にlocaleオプションを設定します。

• Amplitude Browser SDK 2プラグインインストールを使用する場合（amplitude.add()を使用して）、ロケールを InitOptions に設定します。
• サードパーティのアナリティクスプロバイダーを使用している場合は、メソengagement.init()ッドoptions内でロケールを設定してください。

SDK の初期化後に言語を動的に更新するには、次のupdateLanguage方法を使用します。 呼び出しを行うと、新しいロケールで設定がupdateLanguage再取得されます。

engagement.updateLanguage(locale: string): Promise<void>

// Example: Update language to French
await window.engagement.updateLanguage("fr");
// Example: Update language to English
await window.engagement.updateLanguage("en");

カスタムHTTPリクエストヘッダー

初期化時にtransportオプションを渡すことにより、ガイドとサーベイSDKからのすべての送信リクエストにカスタムHTTPヘッダーを添付できます。これを使用して、セキュリティ プロキシまたは出力ゲートウェイを介して要求を認証したり、インフラストラクチャに必要なテナント識別ヘッダーを追加したりできます。 これは、serverUrl を通じて構成されたプロキシ設定とよく連携します。

headersヘッダーのキーと値のペアからなる静的オブジェクトを受け入れます：

engagement.init("YOUR_API_KEY", {
  transport: {
    headers: {
      "X-Corp-Auth": "your-gateway-token",
      "X-Tenant-Id": "your-tenant-id",
    },
  },
});

企業ゲートウェイで必要とされる短命な JWT など、ローテーションされる認証情報の場合は、代わりに関数を渡してください。 SDK は各リクエストの前にこの関数を同期的に呼び出すため、SDK を再初期化することなく、この関数が返すヘッダーは常に最新の状態になります。この関数はヘッダーオブジェクトを直接返す必要があります。非同期関数はサポートされていないため、関数内でトークンを取得するのではなく、アプリケーションがトークンを保存している場所から読み取ってください。

engagement.init("YOUR_API_KEY", {
  transport: {
    headers: () => ({
      // Synchronous read of a token your application keeps up to date
      "X-Corp-Auth": getCurrentGatewayJwt(),
    }),
  },
});

次の動作に注意してください。

• カスタムヘッダーはSDK内部ヘッダーの後にマージされるため、同じ名前のカスタムヘッダーがSDK自身の値を上書きします。設定を避けるAuthorization：SDK は内部的にこれを使用してプロジェクトAPIキーを使用して一部のリクエストを認証します。これを上書きすると、これらのリクエストは中断されます。
• ヘッダー関数がスローした場合、SDK は警告を記録し、リクエストを失敗させるのではなく、カスタムヘッダーなしでリクエストを送信します。

ヘッダー以外をカスタマイズするには（たとえば、Cookie認証プロキシのcredentialsポリシーなど）、[カスタムトランスポート]に移動します。

カスタムトランスポート

カスタムヘッダーだけでは不十分な場合（たとえば、セキュリティプロキシがヘッダーではなくcredentialsfetchオプションを必要とするCookieを使用して認証する場合など）は、初期化時にtransport.handleHttpRequestコールバックを提供してください。設定されている場合、SDKはすべての送信リクエストに対して内部的な仕組みの代わりにコールバックを呼び出し、コールバックがHTTP呼び出しを完全に制御しますfetch。これは、セッションリプレイSDKのカスタムトランスポートフックに対応しています。

SDKは完全な形式のリクエストをコールバックに渡します。これには、解決済みのURL（および関連するオプションを考慮した）、マージされたヘッダー（任意のserverUrlを含むtransport.headers）、およびシリアル化されたボディが含まれます。コールバックの唯一の仕事は、リクエストを実行して Response を返すことです。 バッチ処理、シリアル化、再試行、エラー処理は SDK 内に残り、再試行ごとにコールバックを 1 回呼び出します。

Cookie 認証プロキシの場合、ブラウザがサイトの Cookie をプロキシに送信するようにリクエストを credentials: "include"で転送します。

engagement.init("YOUR_API_KEY", {
  serverUrl: "https://your-proxy-domain.example.com/gs",
  transport: {
    handleHttpRequest: ({ url, method, headers, body, signal, keepalive }) =>
      fetch(url, {
        method,
        headers,
        body,
        signal,
        keepalive,
        credentials: "include",
      }),
  },
});

JWT認証プロキシの場合、SDKが提供するヘッダーを展開し、独自のヘッダーを追加してください。

engagement.init("YOUR_API_KEY", {
  transport: {
    handleHttpRequest: ({ url, method, headers, body, signal, keepalive }) =>
      fetch(url, {
        method,
        headers: { ...headers, "X-Corp-Auth": getCurrentGatewayJwt() },
        body,
        signal,
        keepalive,
      }),
  },
});

コールバックが受信するリクエストオブジェクトには、次のフィールドがあります。

次の動作に注意してください。

• 将来のSDKバージョンで追加されるフィールドも含め、受信したすべてのフィールドを転送してください。これにより、キャンセルやページ終了の配信などのSDKの動作は、コールバックを通じて引き続き機能します。
• コールからfetch を修正せずResponseに返却します。 AI アシスタントのチャットリクエストはレスポンスボディから徐々に消費されるため、レスポンスは本物のストリーミングである必要がありますResponse。
• スロー関headers数とは異なり、コールバックエラーはリクエストを失敗させます。 コールバックを設定すると、SDKが組み込みの機能にフォールバックすることはありません。これは、認証されていないリクエストがプロキシの認証をバイパスするためですfetch。
• このコールバックには、コアAPI呼び出し、AIアシスタントRESTリクエスト、SSEストリーム、添付ファイルのアップロードが含まれます。これにはメディアとCDNアセットの読み込みは含まれません。それらには、cdnUrlおよびmediaUrlのプロキシ設定を使用してください。

デスクトップアプリのプレビューモード

デスクトップフレームワーク内でSDKを使用する場合は、ガイドとサーベイのプレビューをサポートするために追加の計測を実行する必要があります。

Amplitudeダッシュボードは、ディープリンクを通じて特別なクエリパラメータをアプリに渡します（例：your-app://?gs-debug-id=123）。 ディープリンク上でこのクエリパラメータをリッスンするためのロジックをアプリ内に追加し、それを使用して_startNudgeDebugSDKメソッドを呼び出します。

次のフレームワークの例を使用してください。

エレクトロン

以下の最小限の例を使用して、Electron内でガイドとサーベイを実装してください。

1. プリロード時にプロセス間通信機能を登録します。
2. メイン プロセスでは、クエリ パラメータをgs-debug-idリッスンして解析します。
3. レンダラープロセスで： メインプロセスからのメッセージを待ち受け、デバッグパラメータを Engagement SDK に渡します。

const { app } = require("electron");
// Handle deep link on macOS
app.on("open-url", (event, url) => {
  const parsedUrl = new URL(url);
  const debugId = parsedUrl.searchParams.get("gs-debug-id");
  if (debugId) {
    mainWindow.webContents.send("start-engagement-debug", {
      debugId: debugId,
    });
  }
});
// Handle deep link on Windows/Linux
app.on("second-instance", (event, commandLine, workingDirectory) => {
  // Find the deep link URL in command line arguments
  const url = commandLine.find((arg) => arg.startsWith(PROTOCOL + "://"));
  if (url) {
    const parsedUrl = new URL(url);
    const debugId = parsedUrl.searchParams.get("gs-debug-id");
    if (debugId) {
      mainWindow.webContents.send("start-engagement-debug", {
        debugId: debugId,
      });
    }
  }
});

ライフサイクル SDK メソッド

起動

ガイドとサーベイ SDK を初期化し、ユーザーに利用できるようにするには、boot呼び出してください。Amplitude Browser SDK v2 または Amplitude Browser Unified SDK を使用していない場合、SDK スクリプトがページにロードされていてもboot、ガイドとサーベイは を呼び出すまで機能しません。このメソッドは、ライブガイドとサーベイのターゲティング解決をトリガーし、ガイドとサーベイ SDK からアナリティクスプロバイダーへの接続を確立します。アクティブ ユーザーを変更する必要がない限り、セッションごとにboot一度呼び出してください。

engagement.boot(options: BootOptions): Promise<void>

エンドユーザーのタイプ

このEndUserタイプには次のプロパティが含まれます。

**必須フィールド：**少なくともuser_id またはdevice_id を入力する必要があります。どちらのフィールドも指定しない場合、メソッドはエラーを記録し、即座に終了します。

連携タイプ

このIntegrationタイプには次のような 1 つのプロパティが含まれます。

ブート例

例 1: ユーザーオブジェクトの基本的な使用法

await window.engagement.boot({
  user: {
    user_id: "user123",
    user_properties: {
      name: "John Doe",
      plan: "premium",
      signupDate: "2023-01-15",
    },
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

例 2: アナリティクス連携を使用した場合

await window.engagement.boot({
  user: {
    user_id: "user123",
    device_id: "device456",
    user_properties: {
      plan: "premium",
    },
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

例 3: 動的なユーザーデータ用の関数プロバイダーの使用

await window.engagement.boot({
  user: () => {
    return {
      user_id: getCurrentUserId(),
      device_id: getDeviceId(),
      user_properties: getUserProperties(),
    };
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

例 4: シンプルなユーザー ID

await window.engagement.boot({
  user: "user123",
  integrations: [],
});

ブート使用の要件

• 非同期メソッド： bootは非同期メソッドです。 常にPromise として使用awaitまたは処理してください。
• 必須: ガイドやサーベイが表示される前に、必ずboot呼び出しを行う必要があります。
• キュー処理: 起動呼び出しは、SDKのメソッドキューで最初に処理されます。
• セッションごとに1回のコール: 通常、ユーザーセッションごとにboot1回のコールが発生します。

シャットダウン

ガイドとサーベイSDKを終了します。このメソッドは、すべてのアクティブなガイドとサーベイを閉じ、ガイドとサーベイがトリガーされるのを停止します。このメソッドは、ユーザーがログアウトしたときなど、SDKを完全にクリーンアップする必要がある場合に使用します。

engagement.shutdown(): void

shutdown()を呼び出した後、SDKは機能しなくなります。ガイドとサーベイを再度利用するには、再度呼び出してくださいboot()。

ターゲティングを更新

decideエンドポイントに新しいリクエストを送信することにより、バックエンドからターゲティング評価を再取得します。このメソッドを使用して、最新のターゲティングルールとユーザー状態に基づいて表示できるガイドやサーベイを更新できます。SDK はユーザーまたはユーザープロパティが変更されたときにターゲティングを自動的に更新します。 ターゲティングを手動で更新することは、サーバー側でユーザープロパティを更新する場合や、最新のコホートメンバーシップ状態が必要な場合に便利です。

engagement.decide(): Promise<void>

自動更新間隔を設定する

ターゲティングデータの自動定期更新を設定します。有効にすると、SDKは自動的にdecideデータを再取得し、エンドユーザーストアを更新し、指定された間隔で設定をリロードします。自動更新は、ユーザー状態やターゲット設定ルールが変更される可能性がある長時間実行されるセッションに役立ちます。一般的なユースケースはデスクトップアプリケーションで、このアプリケーションではブラウザ環境よりもページのリロード頻度が低くなります。

engagement.setAutoRefreshInterval(intervalSeconds?: number): void

// Set auto-refresh to every hour
window.engagement.setAutoRefreshInterval(3600);
// Set auto-refresh to every 30 minutes
window.engagement.setAutoRefreshInterval(1800);
// Disable auto-refresh
window.engagement.setAutoRefreshInterval(0);

autoRefreshIntervalSecondsオプションを設定することで、ブート時の自動更新を有効にすることもできます。

await window.engagement.boot({
  user: {
    user_id: "user123",
    device_id: "device456",
  },
  autoRefreshIntervalSeconds: 3600,
});

SDK メソッドのスタイル設定

テーマを管理

アプリケーションがライトモードとダークモードをサポートしている場合は、ビジュアルテーマモードを設定してください。

engagement.setThemeMode(mode: ThemeMode): void

// Automatically detect user's system preferences
window.engagement.setThemeMode("auto");
// Set dark mode explicitly
window.engagement.setThemeMode("darkMode");
// Set light mode explicitly
window.engagement.setThemeMode("lightMode");

計装SDKメソッド

イベントを転送する

サードパーティの アナリティクス イベントを ガイド and サーベイ SDK に転送することで、On イベント追跡トリガーを使用するガイドやサーベイをトリガーできます。

engagement.forwardEvent(event: Event): void

コールバックを登録する

ガイドとサーベイ SDK でコールバックを登録します。ガイドまたはサーベイボタンの「コールバックを実行」アクションを設定して、コールバックを実行します。

engagement.addCallback(name: string, callback: () => void): void

window.engagement.addCallback("toggle_dark_mode", () => {
  setTheme("darkMode");
  window.engagement.setThemeMode("darkMode");
});

ルータの設定

ガイドとサーベイがシングルページアプリケーション(SPA)でURLを処理する方法を設定します。これにより、リロードなしでURLを更新できるようになります。

engagement.setRouter(routerFn: (url: string) => void): void

// React Router v6 implementation
import { useNavigate } from "react-router-dom";
const MyComponent = () => {
  const navigate = useNavigate();
  React.useEffect(() => {
    window.engagement.setRouter((newUrl) => navigate(newUrl));
  }, []);
};

// Angular implementation
import { Component } from "@angular/core";
import { Router } from "@angular/router";
@Component({
  /* ... */
})
export class AppComponent {
  constructor(private router: Router) {
    window.engagement.setRouter((url: string) => {
      this.router.navigateByUrl(url);
    });
  }
}

Angularアプリの場合は、ルートのAppComponent（または初期化子）でRouterサービスとnavigateByUrlを使用します。このメソッドは、setRouter期待されるシグニチャと一致する(url: string) => void完全な URL 文字列を受け入れます。

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

現在のセッションのユーザープロパティを設定します。これらのプロパティをガイドやサーベイのコンテンツ内の変数として使用するには、@{{ property.propertyName }}構文を使用してください。

amplitude.identify()を使用してユーザープロパティを共有する場合、_setUserProperties() を使用する必要はありません。

engagement._setUserProperties(userProperties: Record<string, any>): void

例

// Supply user properties manually through engagement SDK
const userProperties = { firstName: "john" };
engagement._setUserProperties(userProperties);
// For testing, view the current user properties
engagement._.user.user_properties;

セッションプロパティを設定する

現在のセッションのセッションプロパティを設定します。セッションプロパティは、ガイドやサーベイがいつトリガーされるかを制限するための追加の方法を提供します。トリガー時に、ガイドまたはサーベイが表示されるのは、設定されたセッション プロパティ条件が一致した場合だけです。

セッションのプロパティが変更されると、SDKは表示できるガイドやサーベイを確認します。セッション プロパティは「immediately」トリガーと連動し、セッション プロパティの条件が真になるとすぐにコンテンツを表示します。

engagement.setSessionProperty(key: string, value: any): void

例

// Various session properties to control guide/survey targeting
window.engagement.setSessionProperty("subscriptionTier", "premium");
window.engagement.setSessionProperty("isFeatureXEnabled", true);
window.engagement.setSessionProperty("userScore", 85);

ガイドとアンケート管理SDKメソッド

表示する

特定のガイドやアンケートを表示します。SDK は、ページのターゲット設定以外のターゲット設定ルールや制限を無視します。 ボタンのonclickハンドラなどからオンデマンドでガイドや調査を表示するために使用しますshow。

engagement.gs.show(key: string, stepIndex?: number): void

例: クリックしたボタンから表示する

ビルダーでガイドまたはサーベイトリガーを**「なし」**に設定し、ユーザーがその体験を選択したときにonclickボタンのshowハンドラーから呼び出して体験を開きます。

<button onclick="window.engagement.gs.show('my-guide-key')">Open guide</button>

すべて閉じる

アクティブなすべてのガイドとサーベイを閉じます。

engagement.gs.closeAll(): void

リセット

ガイドやサーベイを特定のステップにリセットできます。

engagement.gs.reset(key: string, stepIndex?: number)

List

すべてのライブガイドとサーベイのリストとそのステータスを取得できます。

engagement.gs.list(): Array<GuideOrSurvey>

interface GuideOrSuvey {
  id: number;
  status: "visible" | "active";
  step: number;
  title: string
}

リソースセンターSDKメソッド

アプリケーションコードからリソースセンターウィジェットを制御できます。 これらのメソッドは、デフォルトのSDKインスタンス(window.engagement)でのみ機能します。

リソースセンターを開きます。

リソースセンターウィジェットを開きます。 必要に応じて、特定の記事で直接開くこともできます。

engagement.rc.open(options?: { url?: string }): void

// Open the Resource Center
window.engagement.rc.open();
// Open the Resource Center directly on a specific article
window.engagement.rc.open({
  url: "https://help.example.com/articles/getting-started",
});

リソースセンターを閉じる

リソースセンターウィジェットを閉じます。

engagement.rc.close(): void

リソースセンターを切り替える

リソースセンターウィジェットを開くか閉じるかを切り替えます。

engagement.rc.toggle(): void

持続状態をクリアする

リソースセンターは、開いている状態や最小化された状態、検索クエリ、ブラウザで最後に表示されたページなどの状態を保存します。 この保存状態を削除するために呼び出しを実行してください。これにより、リソースセンターは次のページ読み込み時に新しく起動しますclearState。

engagement.rc.clearState(): void

タグによるコンテンツのフィルタリング

リソースセンターのコンテンツをタグごとに制限するためのフィルタを設定します。 このフィルタは、リソースセンターの検索結果とオートパイロットの推奨事項に適用されます。

engagement.setResourceCenterFilter(filter: TagFilter | null): void

このTagFilterタイプはネストされたAND/ORロジックをサポートしています。

type TagFilter =
  | { tags: string[] }
  | { and: TagFilter[] }
  | { or: TagFilter[] };

// Filter to content tagged "billing" or "payments"
window.engagement.setResourceCenterFilter({
  tags: ["billing", "payments"],
});
// Complex filter with AND/OR logic
window.engagement.setResourceCenterFilter({
  and: [{ tags: ["billing", "payments"] }, { tags: ["enterprise"] }],
});
// Clear the filter
window.engagement.setResourceCenterFilter(null);

複数のSDKインスタンス

複数の分離されたガイドとサーベイSDKインスタンスを同じページ上で実行できます。1つのページで複数のAmplitudeプロジェクトからコンテンツを読み込む必要がある場合にこれを使用します。たとえば、テナント固有の体験を独自のガイドやサーベイとともに埋め込んでいるホストアプリケーションなどです。

名前付きインスタンスごとに、独自のAPIキー、設定、ターゲット設定データ、エンドユーザーの状態、アナリティクスルーティングがあります。デフォルトのインスタンスである window.engagementは変更なく引き続き動作し、下位互換性を維持しています。

分離の仕組み

各名前付きインスタンスは独自のものを維持します。

• インスタンスのAPIキーを使用して取得された設定とターゲティング(決定)データ。
• Valtioストアとエンドユーザーストア。
• ガイドやサーベイをレンダリングするためのDOMコンテナです。
• アナリティクス連携ルーティングにより、イベントがインスタンス間で漏洩することはありません。
• スタイルとテーマの変数。
• localStorageキー。APIキーによってスコープが設定されます。

すべてのインスタンスはページ上の単一の#engagement-wrapper要素を共有します。 デフォルトのインスタンスは #engagement-container にレンダリングされます。 各名前付きインスタンスは #engagement-container-{instanceName} にレンダリングされます。

制限事項

• スタンドアロンインストールが必要: SDKバンドルのロード後に、createInstanceで名前付きインスタンスを作成してください。Amplitude Browser SDK 2プラグインとAmplitude Browser Unified SDKパスは、デフォルトのインスタンスのみを管理します。
• 最初にデフォルトインスタンスが必要です: createInstanceを呼び出す前にデフォルトインスタンス (window.engagement) を作成して起動します。 デフォルトのインスタンスは createInstance を公開します。
• ガイドとサーベイのみ: 名前付きインスタンスは、ガイド（チェックリストを含む）とサーベイをサポートします。リソースセンターとアシスタントは、デフォルトのインスタンスでのみサポートされています。
• ユニークなインスタンス名: 名前付きインスタンスごとにユニークな instanceName が必要です。 既存の名前でインスタンスを作成すると、以前の名前が上書きされ、警告が記録されます。
• 独立したターゲティング: 各インスタンスは独自のターゲティングデータを取得し、トリガーを独立して評価します。 マルチステップツアーはインスタンス間で調整できません。
• 独立したユーザーID: 各インスタンスは独自のエンドユーザー状態を管理します。 インスタンスがユーザーを共有できるようにするには、同じuser_idまたはdevice_idを各boot呼び出しに渡します。

インスタンスを作成する

デフォルトの SDK を呼び出して、追加の名前付きインスタンスを作成します。createInstance このメソッドは、新しいインスタンスに解決される Promise Promiseを返します。返されたインスタンスを呼び出してユーザーを識別し、インスタンスをアクティブbootにします。

window.engagement.createInstance(instanceName: string, apiKey: string, options?: InitOptions): Promise<EngagementSDK>

例：2つ目のインスタンスを作成して起動する

const tenantB = await window.engagement.createInstance(
  "tenant-b",
  "API_KEY_FOR_TENANT_B",
  {
    serverZone: "US",
    locale: "fr",
  },
);
await tenantB.boot({
  user: {
    user_id: "user-456",
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

起動後、デフォルトのインスタンスと同様に、返されたインスタンスでSDKメソッドを呼び出します。

tenantB.gs.show("tenant-b-onboarding");
tenantB.gs.closeAll();
tenantB.setThemeMode("darkMode");

既存のインスタンスを取得する

デフォルトのSDKを呼び出して、以前に作成されたインスタンスを名前でgetInstance取得します。インスタンスが存在しない場合undefinedに返されます。

window.engagement.getInstance(instanceName?: string): EngagementSDK | undefined

const tenantB = window.engagement.getInstance("tenant-b");
if (tenantB) {
  tenantB.gs.show("tenant-b-welcome");
}

アクティブなインスタンスを一覧表示

デフォルトのSDKを呼び出して、デフォルトを含むすべてのアクティブなインスタンスの名前を取得しますlistInstances。

window.engagement.listInstances(): string[]

// Returns something like ['$default', 'tenant-b']
const instanceNames = window.engagement.listInstances();

名前付きインスタンスをシャットダウンする

名前付きインスタンスに対してshutdownを呼び出し、そのインスタンスを停止してレジストリから削除します。シャットダウン後、getInstance はインスタンスを返さなくなります。デフォルトのインスタンスで shutdown を呼び出しても、そのインスタンスがレジストリから削除されることはありません。

const tenantB = window.engagement.getInstance("tenant-b");
tenantB?.shutdown();