Visitor ID¶

ft-sdk >= 1.7.6-alpha04 では、FTRUMConfig.setVisitorIdConfig(...) を利用して匿名のビジター ID を有効化できます。URL が一致する OkHttp HTTP/HTTPS リクエストに指定の Header を注入し、ネイティブ RUM データに visitor_id を関連付けます。この ID はログイン認証には使用されず、bindRumUserData で設定したユーザー情報を置き換えるものではありません。

初期化設定¶

SDK の基本初期化が完了したら、業務用の OkHttpClient を作成する前に Visitor ID を設定します。次の例では、https://api.example.com/v1/ プレフィックスに対応する業務 API にのみ Header を注入します。実際の業務アドレスに置き換えてください。

FTVisitorIdConfig visitorIdConfig = new FTVisitorIdConfig()
    .setHeader("x-visitor-id")
    .setTtlHours(24)
    .addMatch("https://api.example.com/v1/");

FTSdk.initRUMWithConfig(new FTRUMConfig()
    .setRumAppId(RUM_APP_ID)
    .setVisitorIdConfig(visitorIdConfig));

val visitorIdConfig = FTVisitorIdConfig()
    .setHeader("x-visitor-id")
    .setTtlHours(24.0)
    .addMatch("https://api.example.com/v1/")

FTSdk.initRUMWithConfig(
    FTRUMConfig()
        .setRumAppId(RUM_APP_ID)
        .setVisitorIdConfig(visitorIdConfig)
)

設定しない場合、または null を渡した場合はこの機能が無効になります。追加のスイッチを有効にする必要はありません。設定は initRUMWithConfig 時に検証され、そのコピーが保存されます。後から元の設定オブジェクトを変更しても、有効化済みの設定は更新されません。Header、有効期限、またはマッチングルールの検証に失敗した場合、SDK はエラーログを出力して Visitor ID を無効にします。

addMatch では次の 3 種類のルールをサポートしています。

• 文字列: 完全な URL プレフィックスに一致します。プロトコル、ホスト、有効なポートが同じであることも条件です。たとえば https://api.example.com/v1/ は、他のドメインや HTTP アドレスには一致しません。
• java.util.regex.Pattern: 完全な URL に対して matcher.find() を実行します。プロトコル、ドメイン、パスを限定する場合は、式で明示的に範囲を制約してください。
• FTVisitorIdConfig.UrlMatcher: matches(String url) の戻り値で一致するかどうかを判定します。コールバックは並行して実行される可能性があるため、スレッドセーフを確保し、時間のかかる処理は避けてください。実行時例外がスローされた場合、そのルールは不一致として扱われます。

OkHttp 連携と注入範囲¶

ft-plugin による自動インスツルメンテーションを使用する場合、上記の初期化が完了すると、インスツルメントされた OkHttpClient.Builder.build() に Visitor ID インターセプターがインストールされます。すでに作成済みの Client には自動的にはインストールされません。プラグインを使用していない場合や、呼び出し箇所がインスツルメントされていない場合は、Visitor ID の手動導入 に従って設定してください。

• Header の注入は、setEnableTraceUserResource、RUM サンプリング、Trace サンプリングとは独立しています。Visitor ID のみを有効にしても、Resource や Trace の収集が自動的に有効になることはありません。
• 一致したリクエストに同名の Header がすでにある場合、SDK は自身が管理する Visitor ID で上書きし、警告ログを出力します。
• SDK のレポート送信先アドレス、および setResourceUrlHandler の isInTakeUrl が true を返すアドレスには、Visitor ID Header は注入されません。
• リダイレクトやリトライ時にはターゲットアドレスが再判定されます。ターゲットが一致しない場合は SDK が注入した Header が削除され、一致する場合はリクエスト開始時の ID が引き続き使用されます。
• ネイティブの Header 注入は OkHttp HTTP/HTTPS リクエストに適用され、WebSocket ハンドシェイク、HttpURLConnection / HttpsURLConnection、WebView 内のネットワークリクエストには適用されません。

有効期限とリセット¶

Visitor ID はプロセスごとに独立してローカルの SharedPreferences に保存され、有効期限内であれば同じプロセスを再起動しても再利用できます。複数プロセス間では共有されません。永続化に失敗した場合は、期限切れまたは明示的なリセットまで、メモリ内の安定した ID が使用されます。期限切れ後の次の読み取り時に新しい ID が生成されます。

業務側でログアウトやアカウント切り替えを確認した後は、明示的にリセットできます。

FTSdk.resetVisitorId();

FTSdk.resetVisitorId()

リセットすると、すぐに新しい ID が生成されて有効期限が再計算されますが、バインドされているユーザー、RUM セッション、Trace ID、サンプリング設定は変更されません。Visitor ID が有効になっていない場合、この呼び出しは無効です。HTTP 401 や通常のリクエスト失敗だけで自動的にリセットしないでください。すでに開始された OkHttp リクエストと、それに関連する Resource、ネットワーク Error は、リクエスト開始時の ID を保持します。

HttpURLConnection / HttpsURLConnection には Visitor ID Header が注入されません。これらの Resource とネットワーク Error は、ネイティブ RUM のイベントレベルの visitor_id を引き継ぎ、イベント生成時に値が取得され、リクエスト開始時の ID には紐付きません。レポートに visitor_id が存在しても、業務リクエストで同名の Header が送信されたことを意味するわけではありません。

ネイティブ RUM の visitor_id は SDK が管理するため、通常のグローバル属性やイベント属性では上書きできません。ただし、最終的な DataModifier / LineDataModifier でレポートフィールドを変更または削除することは可能です。WebView RUM データは Browser SDK 自身の Visitor ID を保持し、ネイティブコンテキストによって上書きされることはありません。