gleap-sdk-setup

Gleap SDK のセットアップ

Gleap SDK をプロジェクトに統合する手順を案内します。JavaScript、iOS、Android、React Native、Flutter、Ionic/Capacitor、Cordova、FlutterFlow に対応しています。

プラットフォームの検出

作業を進める前に、ユーザーのプラットフォームを検出します。ユーザーがプラットフォームを明示している場合は、検出を省略します。

自動検出の優先順位

次の順に確認します（最初に一致したものを採用します）。

1. pubspec.yaml が存在するか？

   • flutterflow の参照が含まれている、またはユーザーが FlutterFlow に言及している場合 -> FlutterFlow（platform-flutterflow.md）
   • それ以外の場合 -> Flutter（platform-flutter.md）

2. package.json が存在するか？ 内容を読み取り、dependencies と devDependencies を確認します。

   • react-native が存在する -> React Native（platform-react-native.md）
   • @capacitor/core または capacitor-core が存在する -> Ionic/Capacitor（platform-ionic-capacitor.md）
   • cordova が存在する、または <widget> を含む config.xml が存在する -> Cordova（platform-cordova.md）
   • @angular/core が存在する -> JavaScript（Angular）
   • react が存在する（react-native は存在しない） -> JavaScript（React）
   • vue が存在する -> JavaScript（Vue）
   • next が存在する -> JavaScript（Next.js）
   • nuxt が存在する -> JavaScript（Nuxt）
   • その他、またはフレームワークがない -> JavaScript（一般的な npm）
   • すべての JavaScript バリアントで platform-javascript.md を使用します

3. *.xcodeproj、*.xcworkspace、または Podfile が存在するか？ -> iOS（platform-ios.md）

4. build.gradle、build.gradle.kts、または app/build.gradle が存在するか？ -> Android（platform-android.md）

5. index.html が存在する（package.json はない）か？ -> JavaScript CDN 方式（platform-javascript.md）

6. サーバーサイドの Web フレームワークが検出されたか？ これらはすべて、クライアント側で JavaScript SDK を使用します（platform-javascript.md）。

   • composer.json が存在する（PHP / Laravel）— JS ビルドパイプラインの有無に応じて CDN または npm を使用します
   • rails を含む Gemfile が存在する（Ruby on Rails）— レイアウトでは CDN を使用します。Webpacker/esbuild/importmap が存在する場合は npm を使用します
   • django または flask を含む requirements.txt / pyproject.toml が存在する（Python）— ベーステンプレートで CDN を使用します
   • *.cshtml / *.csproj ファイルが存在する（.NET / ASP.NET）— レイアウトビューで CDN を使用します
   • Spring Boot（Java）を含む pom.xml / build.gradle が存在する — Thymeleaf テンプレートで CDN を使用します
   • その他の Web フレームワーク（Go、Elixir/Phoenix など）— CDN 方式を使用します
   • 注：プロジェクトにフロントエンドフレームワークを含む package.json もある場合は、手順 2 で検出済みです。

7. 何も検出されない場合 -> 対象のプラットフォームをユーザーに尋ねます。

検出コマンド

Glob を使用して、次の主要ファイルを検索します。

• pubspec.yaml
• package.json
• **/*.xcodeproj
• **/*.xcworkspace
• Podfile
• build.gradle
• build.gradle.kts
• app/build.gradle
• config.xml
• index.html
• composer.json
• Gemfile
• requirements.txt
• pyproject.toml

package.json が見つかった場合は、Read を使用して dependencies と devDependencies のキーを確認します。

API キーの確認

ユーザーに API キーを尋ねる前に、次の場所を順番に確認します。

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

キーが見つかった場合、またはユーザーから提供された場合は、今後も使用できるように、プロジェクトの .env ファイルに保存することを提案します（必要に応じてファイルを作成し、まだ .gitignore に追加されていない場合は .env を追加します）。

ワークフロー

以下の手順を順番に実行します。

1. 最新の SDK バージョンを取得する：このスキルのディレクトリから scripts/get-latest-versions.sh を実行します。ハードコードされたバージョン番号の代わりに、取得したバージョンをすべてのインストールコマンドで使用します。
2. プラットフォームを検出する：上記の優先順位ルールを使用します。
3. API キーを解決する：上記の API キー解決手順を使用します。
4. ユーザーに確認する：検出したプラットフォームを伝え、確認を求めます。ユーザーがすでにプラットフォームを指定している場合は、この手順を省略します。
5. プラットフォームガイドを読む：このスキルのディレクトリにある、該当する platform-{name}.md ファイルを読みます。
6. SDK をインストールする：手順 1 で取得した最新バージョンを使用して、依存関係のインストールをユーザーに案内します。ユーザーの承認を得てからインストールコマンドを実行します。インストールが成功したことを確認します。
7. SDK を初期化する：解決した API キーを使用して初期化コードを追加します。
8. プラットフォームを設定する：プラットフォームガイドに記載された必要な権限、マニフェストのエントリ、その他の設定を適用します。
9. 確認する：統合が機能することを確認するため、プロジェクトのビルドまたは実行を提案します。

セットアップ後の API に関するガイダンス

セットアップ後、ユーザーから Gleap API の使用方法について質問された場合は、該当するプラットフォームファイルの「Common API Usage」セクションを参照します。一般的なタスクは次のとおりです。

• ユーザーを識別する：セッションをユーザーデータ（名前、メールアドレス、プラン、カスタムデータ）に関連付けます。
• イベントをトラッキングする：アプリ内の重要なタイミングでカスタムイベントを記録します。
• カスタムデータ：フィードバックチケットにコンテキストデータを添付します。
• ウィジェットを制御する：Gleap ウィジェットをプログラムから開閉します。

メソッドのシグネチャはプラットフォームによって異なるため、正しいシグネチャを確認するには、プラットフォームファイルの API セクションを読み直してください。

重要な注意事項

• initialize() はアプリケーションのライフサイクル内で必ず 1 回だけ呼び出してください。
• クロスプラットフォームフレームワーク（React Native、Flutter、Ionic/Capacitor）では、iOS と Android の両方でプラットフォーム固有の設定（権限）が必要です。
• JavaScript CDN 方式はあらゆる Web コンテキストで動作し、npm は必要ありません。
• ID 検証では、プロジェクトのシークレットキーを使用して、ユーザーハッシュをサーバー側で生成する必要があります。
• カスタムデータでサポートされるのはプリミティブ値（文字列、数値、ブール値）のみで、キーの上限は 35 個です。

よくあるトラブルシューティング

• pod install が失敗する：最初に pod repo update を実行してから、もう一度試してください。
• Gradle の同期が失敗する：minSdkVersion が 21 以上であることを確認してください。
• Flutter のバージョン競合：AndroidManifest.xml に tools:overrideLibrary="io.gleap.gleap_sdk" を追加してください。
• Web でウィジェットが表示されない：Content Security Policy ヘッダーで sdk.gleap.io が許可されていることを確認してください。
• ソフトリロードでウィジェットが消える（Rails/Turbo）：リロード後に Gleap.getInstance().softReInitialize() を呼び出してください。
• Android のハードウェアアクセラレーション：アプリケーションレベルで android:hardwareAccelerated="false" を設定しないでください。