migrate-from-intercom

Intercom から Gleap への移行

コードベースで Intercom を Gleap に置き換える手順を説明します。クライアント側 SDK の置き換えとサーバー側 API の移行を扱います。

Intercom の検出

コードベースを検索して Intercom の統合を確認します。Grep を使って次を検索します。

パッケージ参照

• package.json：@intercom/messenger-js-sdk、intercom-client、@intercom/intercom-react-native
• Podfile：pod 'Intercom'
• build.gradle：io.intercom.android:intercom-sdk
• pubspec.yaml：intercom_flutter
• composer.json：intercom/intercom-php
• Gemfile：intercom-rails、intercom-ruby

コードパターン（クライアント側 JavaScript — すべてのウェブフレームワークで使用）

• JavaScript：Intercom(、window.intercomSettings、widget.intercom.io、@intercom/messenger-js-sdk
• iOS：import Intercom、Intercom.setApiKey、Intercom.loginUser
• Android：import com.intercom、Intercom.initialize、Intercom.client()
• React Native：import Intercom from '@intercom/intercom-react-native'、IntercomModule
• Flutter：import 'package:intercom_flutter'、Intercom.instance
• サーバー：intercom-client、intercom-php、intercom-ruby、intercom-go、intercom-java、Intercom.Dotnet

作業を進める前に、見つかった項目をすべてユーザーに報告してください。

API キーの確認

ユーザーに Gleap API キーを尋ねる前に、次の場所を順番に確認してください。

1. 会話内でユーザーが提供している場合 — そのキーを直接使用します
2. プロジェクトのルートにある .env ファイル — GLEAP_API_KEY=... を探します
3. 環境変数 — echo $GLEAP_API_KEY を実行して、GLEAP_API_KEY が設定されているか確認します
4. 見つからない場合 — ユーザーに尋ねます（https://app.gleap.io > Project Settings > Security > API Key から取得できます）

キーが見つかった場合、またはユーザーから提供された場合は、.env に保存することを提案してください（必要に応じて .env を .gitignore に追加します）。

ワークフロー

1. 上記のパターンを使って Intercom を検出します。影響を受けるプラットフォームとファイルを報告してください。
2. ユーザーに 移行の範囲を確認します。移行する対象（クライアント SDK、サーバー API、またはその両方）を確認してください。
3. 上記の API キー確認手順に従って Gleap API キーを確認します。
4. このスキルのディレクトリにある、検出したプラットフォームの マッピングファイルを読み込みます。
5. Intercom SDK を削除します。パッケージをアンインストールし、スクリプトタグを削除して、インポートと設定を削除します。
6. Gleap SDK をインストールします。マッピングファイルのインストール手順に従います（またはインストール済みの場合は gleap-sdk-setup スキルを参照します）。
7. API 呼び出しを置き換えます。マッピングテーブルを使って、すべての Intercom 呼び出しを対応する Gleap の呼び出しに変換します。初期化コードには確認した API キーを使用してください。
8. 該当する場合は サーバー側コードを移行します。Intercom REST API 呼び出しを Gleap REST API 呼び出しに置き換えます。mapping-server-api.md を参照してください。
9. クリーンアップします。Intercom 固有の設定（API キー、アプリ ID、intercomSettings、プッシュ通知ハンドラー）を削除します。
10. 検証します。プロジェクトをビルドして実行します。intercom の参照が残っていないか検索してください。

マッピングファイル

検出したプラットフォームに応じて、適切なファイルを読み込みます。

• JavaScript / Web：mapping-javascript.md — クライアント側で JavaScript SDK を使用するため、すべてのサーバー側ウェブフレームワーク（Laravel、Django、Rails、ASP.NET、Spring Boot、Phoenix など）にも適用されます
• iOS（Swift / Objective-C）：mapping-ios.md
• Android（Kotlin / Java）：mapping-android.md
• React Native：mapping-react-native.md
• Flutter：mapping-flutter.md
• サーバー側 REST API：mapping-server-api.md

複数のプラットフォームを使用するプロジェクトでは、関連するファイルをすべて読み込みます。よくある組み合わせは次のとおりです。

• ウェブフレームワーク + サーバー SDK（例：intercom-php を使用する Laravel、intercom-ruby を使用する Rails）：クライアント側には mapping-javascript.md、サーバー側には mapping-server-api.md を使用します
• React Native + サーバー API：mapping-react-native.md と mapping-server-api.md を使用します

重要な注意事項

• Intercom では app_id と api_key を使用します（iOS／Android で別々です）。Gleap では https://app.gleap.io からプロジェクトごとに 1 つの API キーを取得して使用します。
• Intercom の boot() は初期化とユーザー識別を組み合わせています。Gleap ではこれらは別々に行い、initialize() の後に identify() を実行します。
• Intercom の shutdown() は Gleap の clearIdentity() に相当します。
• Intercom の update() は Gleap の updateContact() に相当します。
• Intercom のカスタムユーザー属性は、Gleap の customData オブジェクトに対応します（キーは最大 35 個で、プリミティブ型のみ指定できます）。
• Intercom の会社データは、identify における Gleap の companyId と companyName フィールドに対応します。
• Gleap に直接相当する機能がないものとして、プロダクトツアー（startTour）、チケットビュー（showTicket）、ニュース項目（showNews）があります。代替手段が必要であることをユーザーに伝えてください。
• サーバーサイドでは、Intercom REST API は Bearer トークン認証を使用します。Gleap では Api-Token ヘッダー（レガシー）または Bearer と Project ヘッダー（v3 API）を使用します。