Visitor ID（訪問者識別子）¶
SDK 1.6.8 以降では、SDK が匿名の訪問者識別子（Visitor ID）を生成・管理できます。有効にすると、一致する URLSession リクエストにカスタムリクエストヘッダーを注入し、Native RUM で visitor_id を関連付けることができます。Native Bridge に対応した Web SDK では、許可された WebView ページで現在の識別子を読み取ることもできます。
この機能はデフォルトで無効です。Visitor ID はユーザーバインド API で設定する user_id とは異なり、ログイン資格情報や認証情報として使用することはできません。
初期化設定¶
先に SDK 初期化 を完了し、有効な FTVisitorIDConfig を FTRumConfig.visitorIDConfig に設定してから RUM を開始します。設定は RUM の初期化前に行う必要があります。
#import <GuanceSDK/GuanceSDK.h>
FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appid];
FTVisitorIDConfig *visitorConfig = [[FTVisitorIDConfig alloc] init];
visitorConfig.header = @"x-visitor-id";
visitorConfig.ttlHours = 24;
[visitorConfig addMatchWithURLPrefix:@"https://api.example.com/"];
rumConfig.visitorIDConfig = visitorConfig;
[[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];
import GuanceSDK
let rumConfig = FTRumConfig(appid: appid)
let visitorConfig = FTVisitorIDConfig()
visitorConfig.header = "x-visitor-id"
visitorConfig.ttlHours = 24
visitorConfig.addMatch(urlPrefix: "https://api.example.com/")
rumConfig.visitorIDConfig = visitorConfig
FTSDKAgent.sharedInstance().startRum(withConfigOptions: rumConfig)
| 設定 | タイプ | デフォルト値 | 説明 |
|---|---|---|---|
FTRumConfig.visitorIDConfig |
FTVisitorIDConfig |
nil |
未設定の場合は Visitor ID が無効になります。設定が無効な場合もこの機能は有効になりません |
FTVisitorIDConfig.header |
NSString |
nil |
必須です。カスタムの小文字 HTTP リクエストヘッダー名（例: x-visitor-id）。認証、Cookie、署名、CSRF、Trace などの予約済みリクエストヘッダーは使用できません |
FTVisitorIDConfig.ttlHours |
NSTimeInterval |
24 |
固定の有効期間（時間単位）です。正の有限値を指定する必要があります。読み取りによって有効期間は延長されません |
また、有効な URL マッチングルールを少なくとも 1 つ追加する必要があります。識別子は SDK が自動生成するため、アプリケーション側からカスタム識別子値を渡すことはできません。
URL マッチングとリクエストヘッダー注入¶
ルールは HTTP(S) URL のみを対象とします。複数のルールは「OR」関係で、いずれかに一致すればマッチとみなされます。ルールで例外がスローされた場合は未マッチとして扱われます。
| メソッド | ルール |
|---|---|
addMatchWithURLPrefix: / Swift addMatch(urlPrefix:) |
完全な URL 文字列のプレフィックスを照合し、scheme、host、有効なポートが一致することも要求します。業務 API にはパス区切り文字を含むプレフィックスを使用することをお勧めします |
addMatchWithRegularExpression: / Swift addMatch(regularExpression:) |
完全な URL 文字列に対して正規表現でマッチングします。完全一致が必要な場合は ^ と $ を使用します |
addMatchWithHandler: / Swift addMatch(handler:) |
URL をカスタム判定します。YES / true を返すとマッチとみなされます。コールバックは高速かつスレッドセーフである必要があり、ネットワーク・ディスク操作や同期待機は避けてください |
NSRegularExpression *expression = [NSRegularExpression
regularExpressionWithPattern:@"^https://api\\.example\\.com/v[12]/"
options:0 error:nil];
[visitorConfig addMatchWithRegularExpression:expression];
[visitorConfig addMatchWithHandler:^BOOL(NSURL *url) {
return [url.host isEqualToString:@"checkout.example.com"];
}];
これらのルールを設定オブジェクトに追加してから、rumConfig.visitorIDConfig に割り当てて RUM を起動します。
注入対象はマッチした URLSession の data、upload、download リクエストであり、プロセス内のすべてのネットワークプロトコルに注入されるわけではありません。この機能は RUM や Trace のサンプリングのヒット有無に依存せず、自動 Resource 収集を有効にする必要もありません。対応する Resource イベントを確認する場合は、Resource 収集とサンプリングを別途設定する必要があります。
有効期間、永続化とリセット¶
識別子はローカルに永続化され、有効期間内であればアプリを再起動しても引き続き使用できます。有効期間は識別子の作成時から計算され、アクセスによってスライディング延長されることはありません。有効期限が切れると、次回識別子を取得したときに新しい値が生成されます。アプリのアンインストールやアプリデータの消去などの操作により、ローカルの識別子が失われる可能性があります。
識別子を意図的にローテーションする場合は次のように呼び出します。
有効時はリセットすると新しい識別子が生成されます。無効時はリセットするとローカルレコードが削除されるだけです。生成済みイベントと送信済みリクエストは、その時点でキャプチャされた識別子を保持し、その後のリセットや有効期限切れによって遡って置き換えられることはありません。
WebView 共有¶
Web ページには、Native Bridge 経由で Visitor ID を取得できる Web SDK を統合し、WebView Bridge の確立を許可する必要があります。現在の識別子は読み取り時点の Native 状態に基づいて返され、リセットまたは TTL の有効期限切れ後は新しい値を読み取ることができます。
- URL マッチングルールは、URLSession リクエストにリクエストヘッダーを注入するかどうか を制御します。
FTSDKConfig.allowWebViewHostは、どの WebView ページで自動 Bridge を使用し Native Visitor ID を読み取れるか を制御します。リクエスト URL ルールとは別に設定します。- Visitor ID の読み取りはメインフレームのみ許可されます。未有効、設定無効、または host が許可されていない場合は、Native の識別子は返されません。
WebView のホワイトリストは SDK 初期化前に設定します。例は WebView データモニタリング を参照してください。Visitor ID のリクエスト URL ルールだけを設定しても、WebView の host 範囲は自動的には制限されません。