Cocos Creator アプリの導入¶

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

参照パス¶

初回導入：クイックスタートを最初にお読みください。
インストールとネイティブビルド：この記事を読み進めてください。
パラメータの説明：SDK 初期化、RUM 設定、Log 設定、Trace 設定、Cocos Creator セッションリプレイ（実験的）を参照してください。
手動収集：RUM 手動計測と Logger ログ出力を参照してください。
収集範囲とプライバシー：アプリケーションデータ収集とデータとプライバシーを参照してください。
トラブルシューティング：トラブルシューティングを参照してください。

サポート範囲¶

npm パッケージ	インポートエントリ	Cocos Creator バージョン	Node.js	ネイティブプラットフォーム
`@cloudcare/cocos-sdk`	`@cloudcare/cocos-sdk/creator2`	2.4.5–2.4.15	14+	Android API 21+、iOS 12+
`@cloudcare/cocos-sdk`	`@cloudcare/cocos-sdk/creator3`	3.6.3–3.8.x	16+	Android API 21+、iOS 12+

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

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

現在の SDK バージョン構成¶

この Cocos 導入ドキュメントでは、以下のバージョン構成を統一して使用します。

コンポーネント	バージョン
Cocos SDK	`0.1.0-alpha.6`
Android Agent（`ft-sdk`）	`1.7.6-alpha03`
Android Session Replay（`ft-session-replay`）	`0.1.9-alpha03`
Android Gradle Plugin（`ft-plugin`）	`1.3.9-alpha01`
iOS Agent と Session Replay（`GuanceSDK/Agent`、`FTSessionReplay`）	`1.6.8-alpha.5`

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

Cocos ビルド拡張は、対応する Android/iOS ネイティブ SDK の依存関係を構成します。Android Gradle Plugin は、後述の手順に従って導入する必要があります。ネイティブホストの Hybrid プロジェクトでも、このバージョン構成を使用します。

前提条件¶

注意

RUM Headless サービスを利用している場合は、前提条件が自動的に設定されているため、そのままアプリを導入できます。

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

アプリの導入¶

RUM > 新規アプリ > Android/iOS に移動します。
Cocos Creator Android と iOS 用に、それぞれアプリを作成します。
2 つのアプリのアプリ ID を控え、後でそれぞれ androidAppId と iosAppId に入力します。
アプリの導入方法を選択します：
- パブリック DataWay：データを直接受信するため、DataKit コレクターのインストールは不要です。
- ローカル環境へのデプロイ：前提条件を満たした後、ローカル DataKit がデータを受信します。

インストール¶

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

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

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

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

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

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

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

パラメータ	動作
`--replay`	同じバージョンの Replay npm パッケージを確認し、Replay Bridge、画像処理コード、`ReplayPrivacy` コンポーネントをインストールして、有効化設定を保存します
`--no-replay`	無効化設定を保存します。ネイティブプロジェクトを再生成するときに、インストーラーが管理する Replay ファイル、依存関係、リンク設定を削除します
パラメータなし	初回インストールではデフォルトで無効です。以降のインストールでは、`cocos-sdk.config.json` の `replay.enabled` 設定が引き継がれます

統合を無効にする場合は、次を実行します：

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 またはコマンドラインでアプリを通常どおりコンパイルします。

Guance Android Gradle Plugin

Cocos ビルド拡張は ft-plugin を自動的に適用しません。Android の OkHttp リクエストと起動時間の自動収集には、ft-plugin を併用する必要があります。Cocos Creator が Android ネイティブプロジェクトを生成した後、生成されたプロジェクトで Plugin を設定してください。詳細な手順は Android SDK を参照してください。

Cocos Creator が Android ネイティブプロジェクトを再生成した後、Plugin の設定が引き続き保持されていることを確認してから、Gradle のコンパイルとアプリのパッケージングを実行してください。

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）¶

機能の可用性

SPM 設定エントリは 0.1.0-alpha.5 から提供されています。SDK を更新したら、インストーラーを再実行して Creator 拡張を更新してください。0.1.0-alpha.4 以前のバージョンには、この設定エントリは含まれません。

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

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

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

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

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

設定を変更したら、Creator を開き直して iOS ネイティブプロジェクトを生成します。ビルド拡張は、ローカルの FTCocosBridge Swift Package を自動的にリンクし、ロックされたバージョンの GuanceSDK を解決します。--replay を有効にすると、ローカルの FTCocosReplayBridge Swift Package もリンクし、同じバージョンの GuanceSessionReplay を解決します。初回の解決時には、依存関係リポジトリにアクセスできる必要があります。現在ロックされている iOS SDK のバージョンは 1.6.8-alpha.5 です。

新規の 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@0.1.0-alpha.6
npx --no-install guance-cocos install --project .

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

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6 @cloudcare/cocos-session-replay@0.1.0-alpha.6
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 を初期化し、最初のデータを検証します。完全な設定と機能の範囲については、このページ上部の参照パスから対応するトピックを参照してください。