Cocos Creator アプリ導入¶

Cocos Creator SDK を使用して、Android および iOS ネイティブゲームの RUM、Log、Trace、Session Replay データを収集します。

参照パス¶

• 初回導入：まずクイックスタートを参照してください。
• インストールとネイティブビルド：引き続き本稿を参照してください。
• パラメータの説明：SDK 初期化、RUM 設定、Log 設定、Trace 設定、Cocos Creator セッションリプレイ（実験的） を参照してください。
• 手動収集：RUM 手動計装 と Logger ログ出力 を参照してください。
• 収集範囲とプライバシー：アプリデータ収集 と データとプライバシー を参照してください。
• 問題解決：トラブルシューティング を参照してください。

サポート範囲¶

Creator 3.0～3.6.2 でも導入を試すことができますが、安定したネイティブビルド拡張 API は 3.6.3 以降で提供されます。

SDK は、Android および iOS のネイティブビルドでのみ Native SDK を呼び出します。ブラウザプレビューや Web ビルドではデータは送信されません。

SDK バージョンと依存要件¶

Cocos SDK のバージョンは、実際にインストールされた npm パッケージが基準となります。対応する Android/iOS ネイティブ SDK のバージョンは、その npm パッケージ内の依存関係設定によって決まります。Android Gradle Plugin は別途組み込む必要があり、次の表の最低バージョン要件を満たしている必要があります。

基本パッケージ @cloudcare/cocos-sdk と、オプションの @cloudcare/cocos-session-replay は、完全に同じバージョンを使用する必要があります。基本パッケージは Replay に依存しません。表中の Session Replay のネイティブ依存関係は、Replay 連携を有効にした場合のみ追加されます。

0.1.0-alpha.7 には、Replay の単一フレームサイズポリシーと、Creator 3 のカメラ・タッチ収集の修正が含まれています。アップグレードする場合は、2 つのパッケージを同時にアップグレードし、インストーラーを再実行し、ネイティブプロジェクトを再ビルドする必要があります。詳細はalpha.7 へのアップグレードを参照してください。

Cocos ビルド拡張は、対応する Android/iOS ネイティブ SDK の依存関係を設定します。Android Gradle Plugin は後述の手順に従って組み込む必要があります。ネイティブホストの Hybrid プロジェクトでも、インストールした npm パッケージに対応するネイティブ SDK のバージョンを使用する必要があります。

前提条件¶

• DataKit をインストールします。
• RUM コレクター を設定します。
• DataKit をパブリックネットワークからアクセス可能にし、IP 地理情報データベースをインストールします。

アプリ導入¶

1. RUM > アプリ作成 > Android/iOS に移動します。
2. Cocos Creator Android と iOS のそれぞれにアプリを作成します。
3. 2 つのアプリのアプリ ID を記録し、後でそれぞれ androidAppId と iosAppId に入力します。

4. アプリの導入方法を選択します。

   • パブリック DataWay：データを直接受信します。DataKit コレクターのインストールは不要です。
   • ローカル環境へのデプロイ：前提条件を満たした後、ローカルの DataKit がデータを受信します。

インストール¶

Creator 2 と Creator 3 は基本 npm パッケージを共用します。RUM、Log、Trace のみを導入する場合は、Cocos プロジェクトのルートディレクトリで次のコマンドを実行します。

npm install @cloudcare/cocos-sdk
npx --no-install guance-cocos install --project .

Session Replay が必要な場合は、2 つのパッケージを同時にインストールし、ネイティブ連携を有効にします。

npm install @cloudcare/cocos-sdk @cloudcare/cocos-session-replay
npx --no-install guance-cocos install --project . --replay

基本パッケージと Replay パッケージのバージョン番号は完全に一致している必要があります。インポートエントリは同じ Creator メジャーバージョンを使用する必要があり、コード内では withSessionReplay() を使用して SDK を組み合わせます。詳細はセッションリプレイ初期化を参照してください。npm パッケージをインストールするだけでは、ネイティブの Replay 連携は自動的に有効になりません。

Replay インストールパラメータ¶

以下のパラメータは、SDK を導入する開発者がプロジェクトのインストール段階で使用するものであり、実行時の初期化パラメータではありません。

連携を無効にする場合は、次のコマンドを実行します。

npx --no-install guance-cocos install --project . --no-replay

変更後は、ネイティブプロジェクトを再生成してコンパイルする必要があります。CocoaPods を使用している場合は、pod install も実行する必要があります。既存の ReplayPrivacy.ts と .meta は保持され、シーンやプレハブの参照が壊れないようにします。ネイティブホストが独自に使用する Replay 依存関係は、引き続きホスト側で管理されます。npm パッケージをアンインストールするか、JS によるフレームキャプチャを停止するだけでは、リンク済みのネイティブライブラリは削除されません。

インストーラーは Cocos Creator のメジャーバージョンを自動的に認識します。プロジェクトのメタデータから認識できない場合は、--creator 2 または --creator 3 を明示的に渡すことができます。

インストーラーは、ビルド拡張とネイティブ Bridge を以下のディレクトリにコピーします。

• Creator 3：extensions/guance-cocos-sdk
• Creator 2：packages/guance-cocos-sdk

--replay を有効にすると、インストーラーは ReplayPrivacy コンポーネントスクリプトを assets/guance-cocos-sdk/ReplayPrivacy.ts にコピーします。これは、シーンやプレハブで Session Replay ノードのマスキングを設定するために使用します。詳細はReplayPrivacy コンポーネントの使用を参照してください。

インストール完了後、Cocos Creator を開き直し、guance-cocos-sdk 拡張が有効になっていることを確認してから、Android または iOS のネイティブプロジェクトを再生成します。インストールコマンドを繰り返し実行すると、同じディレクトリが更新されます。

TypeScript コードでは、Creator のメジャーバージョンに応じてインポートエントリを選択します。Creator 2 では @cloudcare/cocos-sdk/creator2 を、Creator 3 では @cloudcare/cocos-sdk/creator3 を使用します。

ネイティブプロジェクトのビルド¶

Android¶

ビルド拡張は、ネイティブプロジェクトの生成後に以下の設定を自動的に行います。

• Cocos Bridge と Android ネイティブ SDK の依存関係を追加します。
• AndroidX を有効化します。
• compileSdkVersion と Build Tools の最低バージョンを 34 に引き上げます。
• minSdkVersion の最低バージョンを 21 に引き上げます。

基本の連携では ft-sdk と ft-native を追加します。--replay を有効にした場合のみ、追加で Replay Bridge、ft-session-replay、およびそれに必要な AndroidX Fragment の依存関係を追加します。

プロジェクトで既にそれより高いバージョンを使用している場合は、拡張は元の設定を保持します。Cocos Creator のネイティブビルド完了後、Android Studio またはコマンドラインで通常どおりアプリをコンパイルしてください。

iOS¶

デフォルトでは CocoaPods を使用します。0.1.0-alpha.5 以降では、プロジェクト設定から Swift Package Manager を選択することもできます。

CocoaPods（デフォルト）¶

ビルド拡張は、生成されたプロジェクトの Podfile に FTCocosBridge を追加します。iOS プロジェクトを再生成するたびに、Podfile があるディレクトリに移動して次のコマンドを実行します。

pod install

その後、生成された .xcworkspace を使用してアプリをコンパイルします。.xcodeproj は使用しないでください。基本の連携は GuanceSDK/Agent のみに依存します。--replay を有効にすると、拡張は追加でローカルの FTCocosReplayBridge Pod を追加し、その Pod が GuanceSDK/FTSessionReplay に依存します。両者は同じバージョンのネイティブ SDK を共有します。

Swift Package Manager（SPM）¶

Cocos プロジェクトのルートディレクトリ（assets と同じ階層）に cocos-sdk.config.json を作成または変更します。

{
  "ios": {
    "dependencyManager": "spm"
  }
}

このファイルは、ネイティブビルド時の依存関係のインストール方法を制御します。TypeScript 内の SDK 初期化パラメータを変更する必要はありません。未設定の場合は cocoapods が使用されます。

同じ設定は、拡張のインストール時に保存することもできます。

npm install @cloudcare/cocos-sdk
npx --no-install guance-cocos install --project . --ios-dependency-manager spm

設定を変更したら、Creator を開き直して iOS ネイティブプロジェクトを生成します。ビルド拡張は、ローカルの FTCocosBridge Swift Package を自動的に関連付け、固定バージョンの GuanceSDK を解決します。--replay を有効にした場合は、ローカルの FTCocosReplayBridge Swift Package も関連付け、同じバージョンのネイティブ Replay ライブラリを解決します。初回の解決時には、依存関係リポジトリにアクセスできる必要があります。SPM 連携では、iOS SDK が 1.6.8-alpha.5 以上である必要があります。具体的なバージョンは、インストールされている Cocos SDK npm パッケージによって決まります。

SPM のみの新しいプロジェクトでは、pod install を実行する必要はありません。生成された .xcodeproj を直接開いてコンパイルしてください。ネイティブホストが他の依存関係の管理に引き続き CocoaPods を使用している場合は、ホストの .xcworkspace を開いてください。

CocoaPods からの切り替え

• 拡張は、自動生成された SDK Pod 設定ブロックを削除します。既に Pods がインストールされている場合は、pod install が自動的に実行されて連携が更新されるため、移行時には本機で CocoaPods を実行できる必要があります。
• 手動で宣言された FTCocosBridge、FTCocosReplayBridge、GuanceSDK、または同じネイティブ SDK に依存する他の Pod は、先に移行を完了する必要があります。競合が検出された場合は、インストーラーがエラーを報告し、重複リンクを防ぎます。
• ホストの他の Pod 依存関係は、従来の管理方法のまま維持されます。
• CocoaPods に戻す場合は、ios.dependencyManager を cocoapods に変更し、プロジェクトを再生成して pod install を実行します。

Creator 3 が Xcode のビルド中に CMake の再生成をトリガーした場合、拡張は SPM パッケージの参照とリンク設定を自動的に復元します。CMake を単独で実行してプロジェクトを再生成する場合は、Creator のネイティブビルド連携を再実行してから Xcode を開いてください。

SDK の更新¶

npm パッケージをアップグレードした後は、インストーラーを再実行し、ネイティブプロジェクトを再生成する必要があります。

npm install @cloudcare/cocos-sdk
npx --no-install guance-cocos install --project .

Replay を使用するプロジェクトでは、2 つの npm パッケージを同時にアップグレードする必要があります。

npm install @cloudcare/cocos-sdk @cloudcare/cocos-session-replay
npx --no-install guance-cocos install --project . --replay

0.1.0-alpha.5 以前の一体型パッケージからアップグレードする場合は、Replay のインポートと Camera 呼び出しの移行も必要です。パッケージ分割に伴う移行を参照してください。

CocoaPods を使用する iOS プロジェクトでは、pod install を再実行する必要もあります。SPM を使用するプロジェクトでは、Xcode が依存関係を再解決します。インストーラーを再実行する際に --ios-dependency-manager を指定しない場合は、既存のプロジェクト設定が保持されます。

次のステップ¶

インストール完了後、クイックスタートに従って SDK を初期化し、最初のデータを検証します。完全な設定と機能の範囲については、このページ上部の参照パスから対応するトピックを参照してください。