ユーザーIDの理解と管理

顧客を効果的に管理するために、Intercomは2種類のIDを使用します：Intercom IDとuser_id。これらがどのように連携するかを理解することは、データの整合性を維持し、正確な顧客識別を保証するために不可欠です。

Intercom IDについて

Intercom IDは、当社のシステムが各顧客レコードに自動的に生成する識別子です。このIDは一定で変更できません。APIでは、しばしばcontact_idと呼ばれます。

カスタムuser_id（外部ID）

user_idは、独自のデータベースの主キーや一意のIDに合わせて設定できるカスタマイズ可能な識別子です。Intercomを外部システムと統合する柔軟な方法を提供し、API経由で更新可能です。

ユーザーID管理のベストプラクティス

これらのベストプラクティスに従うことで、重複レコードや会話の統合などの一般的なデータ問題を回避できます。

一意で一貫した識別子を割り当てる

各顧客に対して常に一意のuser_idを割り当てるべきです。通常は自社データベースの主キーです。特定の顧客に対する将来のすべてのやり取りやプロフィール更新に同じuser_idを使用することが重要です。

同じメールアドレスに対して異なるuser_idを渡すことは避けてください。これにより重複した顧客レコードが作成されます。

重要：

一貫性のない、または重複するuser_idを使用すると、アカウント間のログインや異なる顧客間の会話統合など、深刻なデータ整合性の問題が発生します。
値-1はIntercomのシステムで内部目的に予約されており、user_idとして使用してはいけません。この値を使うと、会話が誤って別のユーザープロフィールに関連付けられるなど予期しない動作が起こる可能性があります。-1はしばしばデフォルトまたはプレースホルダー値として使われ、ユーザーがこれを持つ場合、一意性が失われ問題を引き起こします。

マルチテナント環境でグローバルに一意なuser_idを使用する

Intercomに送信されるuser_idの値は、ワークスペース全体でグローバルに一意でなければなりません。複数のテナントや組織が同じIntercomワークスペースを共有するマルチテナント環境では、単一テナント内でのみ一意なuser_idがテナント間で衝突し、別々の顧客が同じIntercom連絡先レコードに統合される可能性があります。

これを防ぐために、user_idの値にテナント識別子をプレフィックスとして付けてからIntercomに送信してください。例えば、「user_123」ではなく「tenant_abc:user_123」を送信します。

注意：ユーザーレコードの衝突を防ぎ、安全な識別を確保するためにJWT認証の有効化も必要です。これがないと、悪意のある者が他のユーザーのuser_idを使ってなりすまし、不正に会話履歴やワークスペースデータにアクセスする可能性があります。グローバルに一意なuser_idは偶発的なレコード統合を防ぎ、JWT認証は意図的ななりすましを防ぎます。

デフォルト値やプレースホルダー値の使用を避ける

「undefined」などのデフォルト値を割り当てたり、複数の顧客で同じuser_idを使用したりしないでください。これによりデータエラーが発生し、個々の顧客を正しく識別できなくなります。

user_idのバックフィルまたは更新

以前に不明なuser_idだった顧客レコードを更新する必要がある場合、後で正しい識別子を追加できます。

プロのヒント：自社データベースで正しいuser_idを確認し、CSVインポートやAPIを使ってIntercomの顧客レコードを更新できます。

ステップバイステップ：Intercom IDを使ったuser_idの更新

Search for a Contactエンドポイントを使い、メールアドレスや他の既知の属性で連絡先を検索します。
レスポンスのidフィールドを確認してください。これは連絡先の恒久的なIntercom IDです。
自社データベースから正しいuser_idを調べます。
Update a Contactエンドポイントを呼び出し、Intercom ID（id）と正しいuser_idを渡します。

{
  "id": "contact_intercom_id",
  "user_id": "your_stable_database_id"
}

重要：連絡先の更新対象を指定する際は、必ずIntercom ID（id）を使用してください。メールアドレスや既存のuser_idではありません。これにより、user_idが設定されていない、または誤っている場合でも正しいレコードを更新できます。

誤ったuser_idを設定する統合を防ぐ

CRM同期、分析ツール、データパイプラインなどの統合が誤ったuser_idを設定してしまうことがあります。主な原因は以下の通りです。

安定したデータベースの主キーではなく、セッションID、クッキー、一時トークンをマッピングしている
顧客が認証されていない場合にnull、undefined、0、-1などのプレースホルダー値を送信している
user_idフィールドにメールアドレスを使用している（メールは変更される可能性があり、連絡先の継続性が壊れる）
同じ顧客に対して異なる統合が異なるuser_idを送信している

これを防ぐために：

統合マッピングを監査する — システム内のどのフィールドがIntercomのuser_idにマッピングされているか確認してください。各顧客のデータベースの主キーであるべきです。
送信前に検証する — user_idがnullでなく、空でなく、予約値（-1やundefinedなど）でないことを確認してからIntercomに渡してください。
単一の信頼できる情報源を使う — 複数の統合がIntercomにデータを送信する場合、すべて同じ安定した顧客識別子を使用していることを確認してください。
既知のレコードでテストする — 統合を設定した後、Search for a Contactエンドポイントを使い、いくつかの顧客のuser_idがデータベースと一致するか確認してください。

APIを使ったユーザーID管理

IntercomのAPIを使って、顧客ID管理のための主要な操作をいくつか実行できます。詳細はDeveloper Hubをご覧ください。

連絡先の取得、更新、検索

連絡先を取得する：Intercom ID（id）またはカスタムuser_idを使ってRetrieve a Contactエンドポイントで顧客の詳細を調べます。
連絡先を更新する：Update a Contactエンドポイントを使ってuser_idを設定または修正します。
連絡先を検索する：Search for a Contactエンドポイントを使ってuser_idやメールアドレスなどの識別子を検証します。

統合の監査

定期的な監査により、誤ったuser_idがデータ整合性の問題を引き起こす前に検出できます。統合を監査し、すべての連絡先が正しく安定したuser_idを持っていることを確認するために以下の手順に従ってください。

user_idが欠落または疑わしい連絡先を特定する — Search for a Contactエンドポイントを使い、user_idが空白または既知のプレースホルダー値（-1やundefinedなど）を含む連絡先を検索します。Intercomから連絡先リストをエクスポートし、異常をフィルターすることも可能です。
各user_idの出所を追跡する — 問題のある連絡先ごとに、どの統合が最後にuser_idを設定したかを特定します。統合ログやイベント履歴を確認して値の起源を確認してください。
Intercom IDを使ってuser_idを修正する — 自社データベースから正しいuser_idを調べ、Update a Contactエンドポイントを使って連絡先のIntercom IDで正しい値を設定します。手順はBackfilling or updating user IDsを参照してください。
統合設定を修正する — 今後は正しく安定した識別子にマッピングするよう統合を更新してください。サードパーティツールの場合は、フィールドマッピング設定を確認し、データベースの主キーを指すように更新します。
修正後に検証する — 更新した連絡先を再検索し、user_idが正しい値を反映していることを確認し、数日間新たな発生を監視します。

JWT認証で正しい識別を確保する

ログイン済み顧客の堅牢な認証を確保するために、JSON Web Token（JWT）ペイロードのuser_idにはデータベースの主キーを使用するのがベストプラクティスです。

顧客を識別するためにメールアドレスしかない場合は、JWTペイロードのuser_idとemail属性の両方に顧客のメールアドレスを設定してください。

一般的なユーザーIDエラーのトラブルシューティング

カスタムuser_idのアーカイブ

カスタムuser_id属性をアーカイブしても、デフォルトのIntercom user_idフィールドは自動的に更新されません。レコードを更新するには手動でのバックフィルが必要です。

重複レコードの処理

一貫性のないuser_id値は、単一の訪問者のアクティビティ（ページビューを含む）が複数の連絡先レコードに分割される原因にもなります。この連絡先の断片化により、例えばRecent page viewsアプリで期待する連絡先にページビューが表示されないことがあります。

user_idとメールアドレスの不一致による重複レコードが見つかった場合は、手動またはAPIを使ってレコードをマージまたは削除してクリーンアップする必要があります。

カスタムIDからデフォルトIDへの切り替え

ユーザーデータベースのフィールドを更新する必要がある場合は、開発者に相談してIntercom APIの使用方法を確認するか、CSVインポートのワークフローを利用してください。