ビジター ID Visitor ID¶
SDK 0.4.3 以降でサポートされます。
Visitor ID は SDK が生成・管理する匿名のビジター識別子です。有効化すると、一致する HTTP(S) リクエストにカスタムリクエストヘッダーを注入し、RUM データに visitor_id を関連付けることができます。対応する Web SDK を統合した WebView ページも Native の識別子を読み取ることができます。
この機能はデフォルトで無効です。Visitor ID は bindRUMUserData() で設定するユーザー識別子とは異なり、ログイン資格情報や認証情報として使用することはできません。識別子は SDK が自ら生成するものであり、アプリケーションから識別子の値を指定することはできません。
初期化設定¶
まず SDK 初期化 を完了し、次に FTRUMConfig.visitorIdConfig を使用して RUM を設定・初期化します:
import {
FTMobileReactNative,
FTReactNativeRUM,
FTRUMConfig,
FTVisitorIdConfig,
} from '@cloudcare/react-native-mobile';
const rumConfig: FTRUMConfig = {
androidAppId: 'android_app_id',
iOSAppId: 'ios_app_id',
visitorIdConfig: {
header: 'x-visitor-id',
ttlHours: 24,
urlPrefixes: ['https://api.example.com/'],
},
};
await FTReactNativeRUM.setConfig(rumConfig);
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| header | string | はい | 小文字のカスタム HTTP リクエストヘッダー名(例:x-visitor-id)。認証、Cookie、署名、CSRF、Trace などの予約済みリクエストヘッダーは使用できません |
| ttlHours | number | いいえ | 固定有効期間(時間単位、デフォルト 24)。読み取りによって延長されることはありません。小数をサポートし、ミリ秒に換算した値が 1 以上かつ 2^63 未満である必要があり、NaN や Infinity は指定できません |
| urlPrefixes | string[] | 条件付き必須 | 完全な HTTP(S) URL プレフィックス。マッチングは同じプロトコル、ホスト、有効なポートに限定されます。regularExpressions と合わせて少なくとも 1 つのルールを指定する必要があります |
| regularExpressions | string[] | 条件付き必須 | 完全な URL に対して正規表現マッチングを行う式文字列。urlPrefixes とは「OR」の関係です |
visitorIdConfig を省略するか null に設定すると、無効になります。設定が不正な場合、FTReactNativeRUM.setConfig() は失敗した Promise を返すため、設定を修正してから初期化してください。
URL マッチングとリクエストヘッダー注入¶
複数のルールは「OR」の関係にあり、いずれか 1 つに一致すればヒットします。React Native は URL プレフィックスと正規表現の 2 つのマッチング方式を提供します:
- URL プレフィックス:完全な URL 文字列のプレフィックスでマッチングし、プロトコル、ホスト、有効なポートが一致していることも要求します。
orders-historyなどのパスへの誤マッチを避けるため、https://api.example.com/orders/のようにパス区切り文字を含むプレフィックスの使用を推奨します。 - 正規表現:完全な URL 内でマッチングを検索します。開始位置を制限したり完全一致させたりする場合は
^、$を使用します。文字列として渡されるため、バックスラッシュはエスケープが必要です。式は iOS と Android の両方の正規表現構文に互換している必要があります。
例えば、/orders/ 配下のリクエスト、または /v1/、/v2/ 配下のリクエストに識別子を注入するには次のようにします:
const visitorIdConfig: FTVisitorIdConfig = {
header: 'x-visitor-id',
urlPrefixes: ['https://api.example.com/orders/'],
regularExpressions: ['^https://api\\.example\\.com/v[12]/'],
};
// RUM の初期化前に、これを rumConfig.visitorIdConfig に代入します。
FTVisitorIdConfig と FTRUMConfig は同じ React Native メイン SDK パッケージからインポートします。
リクエストヘッダー注入は、SDK が統合済みの HTTP(S) ネットワークリクエストに適用され、WebSocket リクエストには注入されません。Android 側では ft-plugin のネットワーク統合設定を完了する必要があります。カスタムネットワーククライアントを使用する場合も、そのクライアントが SDK に統合されていることを確認してください。
Visitor ID のリクエストヘッダー注入は、RUM または Trace のサンプリングにヒットするかどうかに依存せず、自動 Resource 収集を有効にする必要もありません。プラットフォーム上で対応する Resource データを確認する必要がある場合は、引き続き Resource 収集を有効にし、適切なサンプリングを設定する必要があります。
有効期間、永続化とリセット¶
識別子はローカルに永続化され、ストレージが正常で有効期間が終了していない場合、アプリを再起動しても引き続き使用できます。有効期間は識別子の作成時点から計算され、アクセスや読み取りによって延長されることはありません。有効期間が切れると、次に識別子を取得するタイミングで新しい値が生成されます。
アプリのアンインストールやアプリデータの消去などの操作により、ローカルの識別子が失われる可能性があります。ローカルストレージが使用できない場合、識別子は現在のプロセス内でのみ保持されます。Android のマルチプロセスアプリでは、識別子はプロセスごとに独立して管理されます。
Visitor ID を有効にした後、識別子を能動的に変更する必要がある場合は次を呼び出します:
リセットすると新しい識別子が生成され、以降のリクエストと読み取りでは新しい値が使用されます。キャッシュ済みのデータや、すでに送信されたリクエスト内の識別子が遡って置き換えられることはありません。
WebView 共有¶
Web ページには、Native Bridge を通じて Visitor ID を取得する機能をサポートする Web SDK を統合し、WebView 統合 を完了する必要があります。有効な visitorIdConfig を設定すると、Web SDK は現在の Native 識別子を読み取ることができます。Visitor ID が無効な場合、Native 識別子は返されません。
2 種類のルールはそれぞれ異なる範囲を制御します:
visitorIdConfig.urlPrefixes、regularExpressionsは、業務 HTTP(S) リクエストに Visitor ID リクエストヘッダーを注入するかどうかを制御します。- React Native の
FTMobileConfig.allowWebViewHostは WebView の host 範囲を設定し、この機能をサポートする Web SDK が Native 識別子を読み取る際に使用します。詳細は WebView host 設定 を参照してください。iOS ではさらにメインフレームからの読み取りに制限されます。
FTMobileConfig.allowWebViewHost は SDK の初期化時に設定し、SDK と RUM の初期化が完了した後に WebView ページを読み込んでください。リクエスト URL のマッチングルールのみを設定しても、WebView ページの範囲が自動的に制限されることはありません。TTL の期限切れまたはリセット後は、以降の読み取りで新しい現在の識別子が使用されるため、Web 側で古い値を永続的にキャッシュしないでください。