セッションリプレイ React Native スタンドアロン SDK

セッションリプレイ React Native スタンドアロン SDK はモバイルセッションを記録し、Amplitude Analytics SDK を使用せずに Amplitude にアップロードします。別のアナリティクス・プロバイダーがすでにアプリを実装している場合や、Amplitude deviceIdとsessionIdをご自身で管理している場合に使用してください。アプリがすでに Amplitude React Native アナリティクス SDK を使用している場合は、代わりにセッションリプレイ React Native SDK プラグインをインストールしてください。

Amplitude APIキーが必要です。 パッケージをインストールした後、ネイティブ アプリを再構築してください。 Expo Go にはこのネイティブモジュールが含まれていないため、開発ビルドまたはプレビルドクライアントを使用してください。

変更履歴の詳細については、GitHub 上のパッケージ変更履歴を参照してください。

SDKをインストールする

npm install @amplitude/session-replay-react-native --save

クイックスタート

init() はSDKを設定しますが、キャプチャを開始しません。 一致するdeviceIdとsessionIdの値を渡した後に、start()を呼び出してください。

import { init, start } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  sampleRate: 0.1,
  privacyConfig: {
    maskLevel: "medium",
  },
});
await start();

リプレイとアナリティクスイベントを関連付ける

スタンドアロン SDK とアナリティクス SDK が同じ deviceIdおよび sessionId を送信した場合、セッションリプレイはリプレイとアナリティクス・イベントを合わせます。 これらの値を init() に渡し、いずれかの識別子が変更されるたびに setDeviceId() および setSessionId() を呼び出します。

import {
  setDeviceId,
  setSessionId,
} from "@amplitude/session-replay-react-native";
await setDeviceId("new-device-id");
await setSessionId(Date.now());

スタンドアロン SDK は、ユーザーに代わってセッションを管理しません。 アプリまたはサードパーティのアナリティクス連携では、両方の識別子を同期させておく必要があります。

設定

この設定を init() に渡してください。

メソッド

init

セッションリプレイ SDK を設定します。他のセッションリプレイメソッドの前にこれを呼び出します。init() はキャプチャを開始しません。

import { init } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
});

start

セッションリプレイの記録を開始します。 キャプチャを再開したい場合は、init() の後、および以前に stop() 呼び出した後に、これを呼び出してください。

import { start } from "@amplitude/session-replay-react-native";
await start();

stop

セッションリプレイを停止します。

import { stop } from "@amplitude/session-replay-react-native";
await stop();

setSessionId

セッション識別子を更新します。 アナリティクスイベントのセッション ID が変更されるたびに、これを呼び出してください。

import { setSessionId } from "@amplitude/session-replay-react-native";
await setSessionId(Date.now());

setDeviceId

デバイス識別子を更新します。 アナリティクスイベントのデバイス ID が変更されるたびにこの呼び出しをしてください。デバイス ID をクリアするには、null を渡します。

import { setDeviceId } from "@amplitude/session-replay-react-native";
await setDeviceId("new-device-id");
await setDeviceId(null);

getSessionId

セッションリプレイ SDK から現在のセッション識別子を返します。または、SDK を初期化していない場合は null を返します。

import { getSessionId } from "@amplitude/session-replay-react-native";
const sessionId = await getSessionId();

setOptOut

実行時にオプトアウトを更新します。リプレイコレクションを無効にするには、true を渡します。サンプリングおよびすでにstart()を呼び出しているかどうかに応じて、再びデータ収集を許可するにはfalseを渡します。

import { setOptOut } from "@amplitude/session-replay-react-native";
await setOptOut(true);
await setOptOut(false);

フラッシュ

保留中のセッションのリプレイデータをただちにアップロードします。

import { flush } from "@amplitude/session-replay-react-native";
await flush();

ティアダウン

ネイティブのセッションリプレイをシャットダウンし、JavaScript のライフサイクル状態をクリアします。他のセッションリプレイメソッドを実行する前に、再度init()を呼び出してください。

import { init, start, teardown } from "@amplitude/session-replay-react-native";
await teardown();
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
});
await start();

画面上のデータをマスクする

セッションリプレイは、機密データや PII を含むビューを隠したり、難読化したりします。 対象の領域をAmpMaskViewでラップし、maskをamp-mask、amp-unmask、またはamp-blockに設定します。AmpMaskViewは通常のViewと同様にレイアウトされるため、Viewに使用しているものと同じレイアウトスタイルを適用できます。

import { AmpMaskView } from "@amplitude/session-replay-react-native";
<AmpMaskView mask="amp-mask">
  <Text>{title}</Text>
</AmpMaskView>;

AmpMaskViewは通常の React Native レイアウトノードなので、Viewと同様にレイアウトに参加し、レイアウト上で透過的に扱われることはありません。既存のコンテンツをラップする場合は、flex: 1、明示的widthとheight、またはalignItemsなど、AmpMaskViewにそのコンテンツが依存しているサイズ指定やフレックススタイルを自体に適用してください。これらのスタイルがないと、ラッパーはラッピングした領域を縮小したりサイズを変更したりすることがあります。

ビューのマスク解除

グローバルなマスクレベルではマスクされるビューをアンマスクにするには、maskを amp-unmaskに設定します。

import { AmpMaskView } from "@amplitude/session-replay-react-native";
<AmpMaskView mask="amp-unmask">
  <Text>{title}</Text>
</AmpMaskView>;

ビューのブロック

ビューを同じサイズの空のプレースホルダーに置き換えるには、maskをamp-blockに設定します。

import { AmpMaskView } from "@amplitude/session-replay-react-native";
<AmpMaskView mask="amp-block">
  <Text>Session Replay doesn't capture this content</Text>
</AmpMaskView>;

マスキングにおけるプラットフォームの違い

Android と iOS は異なるネイティブのセッションリプレイ・ライブラリでAmpMaskViewを解決するため、同一のマークアップでもプラットフォームごとに異なる動作をすることがあります。リリース前に両方のプラットフォームでマスクをテストしてください。

セッションリプレイは各フレームをキャプチャするときにこれらの表現をデバイスに適用するため、アップロードされた再生データには元のテキストやピクセルの代わりにマスクされた表現が保持されます。プレイヤーはマスクされたコンテンツを後で復元することはできません。

両方のプラットフォームでリージョンを表示できるようにするには、そのラッパーを 1 つの amp-maskおよび amp-blockリージョン内にネストするのではなく、すべての amp-unmaskおよび リージョンの外側に配置します。

マスキングレベルを選択する

init()にprivacyConfig.maskLevelを設定します。

セッションリプレイ設定ページのリモート設定は、SDK よりも優先されます。 この SDK は、ネイティブの iOS および Android セッションリプレイライブラリにenableRemoteConfigを転送します。Amplitude のセッションリプレイのプライバシー設定では、リモート設定を有効にした場合でもロードに失敗した場合、セッションリプレイはセッションをキャプチャしません。

ウェブビューの追跡（ベータ）

デフォルトでは、セッションリプレイはWebビューをブロックし、それらを追跡しません。ウェブビューをトラッキングするには、それを AmpMaskView でラップし、maskを amp-unmaskに設定します。

import { AmpMaskView } from "@amplitude/session-replay-react-native";
import { WebView } from "react-native-webview";
<AmpMaskView mask="amp-unmask" style={{ flex: 1 }}>
  <WebView source={{ uri: "https://reactnative.dev/" }} style={{ flex: 1 }} />
</AmpMaskView>;

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

セッションリプレイは、EU データセンターを使用する Amplitude プロジェクトをサポートしています。初期化時にserverZoneを'EU'に設定します。

import { init, start } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  serverZone: "EU",
});
await start();

サンプリングレート

デフォルトでは、セッションリプレイはセッションの 0% をキャプチャします。録画したいセッションの割合に合わせてsampleRateに設定します。

import { init, start } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  sampleRate: 0.1,
});
await start();

sampleRateを設定する際は、セッションリプレイプランの月クォータを考慮してください。 たとえば、月間割り当て量が2,500,000セッションで、月間平均セッション数が3,000,000の場合、割り当て量は平均セッション数の83%です。サンプリングを月内を通して継続させるには、sampleRateを.83以下に設定します。

次のクォータの詳細を覚えておいてください。

• 月間のセッションクォータに達すると、Amplitudeはリプレイ用のセッションのキャプチャを停止します。
• セッションクォータは毎月 1 日にリセットされます。
• 最初にクォータをフルに活用するのではなく、サンプルレートを使用して月全体にセッションクォータを分配してください。
• たとえば、.01 のように低いレートから始めます。この値で十分なリプレイが記録されない場合は、数日間かけてレートを上げてください。キャプチャされたリプレイのボリュームをモニターするには、キャプチャされたセッション数の表示 に移動します。

セッションリプレイはリモートサンプリングレート設定をサポートしています。組織は、コードを変更することなく、実装後にプロジェクトのサンプリングレートを更新できます。 競合が発生した場合、セッションリプレイはデフォルトでリモートの設定に設定されます。詳細については、アカウント設定に参照してください。

ユーザーのオプトアウト

初期化時に収集をスキップするには、optOutをtrueに設定します。これを後で変更するには、setOptOut() を呼び出します。オプトアウトを変更する目的だけでinit()を再実行しないでください。

import { init, setOptOut, start } from "@amplitude/session-replay-react-native";
await init({
  apiKey: "YOUR_API_KEY",
  deviceId: "YOUR_DEVICE_ID",
  sessionId: Date.now(),
  optOut: true,
});
await setOptOut(false);
await start();

トラブルシューティング

リプレイが表示されない

• init() の後に start()を呼び出します。init()は SDK を設定するだけで、キャプチャは開始しません。
• ゼロ以外の sampleRate を使用するか、セッションリプレイ設定ページでリモートサンプリングレートを確認してください。
• アナリティクスイベントで使用するdeviceIdとsessionIdの同じものを渡し、変更があった場合は両方を更新します。
• パッケージをインストールした後、ネイティブ アプリを再構築してください。 iOS の場合、再構築前にpod installを実行してください。
• この SDK を Expo Go で実行しないでください。 代わりに、開発ビルドまたはプレビルドクライアントを作成してください。