トラブルシューティング¶

初期化後にデータがない¶

次の順に確認してください。

Android または iOS のネイティブビルドを使用する必要があります。ブラウザプレビューと Web ビルドではデータは送信されません。
npx --no-install guance-cocos install --project . を実行済みであることを確認し、Cocos Creator を開き直して guance-cocos-sdk 拡張機能を有効にしてください。
npm パッケージをアップグレードまたは再インストールした場合は、必ずネイティブプロジェクトを再生成してください。
datakitUrl、または datawayUrl と clientToken の設定が正しいことを確認してください。
Android では androidAppId、iOS では iosAppId を指定する必要があります。
初期化時に debug: true を設定し、Cocos とネイティブのログを確認してください。
sampleRate が 0 でないことを確認してください。
ローカル環境でデプロイしている場合は、DataKit にデータがない問題をさらに確認してください。

インストーラーが Cocos プロジェクトを見つけられない¶

次のエラーが表示される場合：

No Cocos project found ... (missing assets directory)

--project は assets ディレクトリを含む Cocos プロジェクトのルートディレクトリを指定する必要があります。

npx --no-install guance-cocos install --project /absolute/path/to/cocos-project

Creator のエントリーポイントが誤っている¶

Creator 2 と Creator 3 は同じ @cloudcare/cocos-sdk npm パッケージを使用しますが、インポートのエントリーポイントが異なります。

Creator 2：@cloudcare/cocos-sdk/creator2
Creator 3：@cloudcare/cocos-sdk/creator3

インポートのエントリーポイントを変更したら、インストーラーを再実行し、ネイティブプロジェクトを生成してください。インストーラーが Creator のバージョンを認識できない場合は、--creator 2 または --creator 3 を明示的に指定してください。

Android Bridge または依存関係のエラー¶

ClassNotFoundException が発生する、FTCocosBridge が見つからない、またはネイティブ SDK のクラスが欠落している場合：

生成されたプロジェクトに cocos-sdk-native/android が含まれていることを確認してください。
アプリケーションモジュールの build.gradle に COCOS_SDK_BEGIN マーカーブロックが存在することを確認してください。
Gradle が https://mvnrepo.guance.com/repository/maven-releases にアクセスできることを確認してください。
AndroidX が有効になっていることを確認してください。
Compile SDK と Build Tools が 34 以上、Min SDK が 21 以上であることを確認してください。
インストーラーを再実行してプロジェクトを再生成してください。古い Native プロジェクトを再利用するだけでは不十分です。

iOS Bridge または CocoaPods のエラー¶

以下の確認事項は、CocoaPods を使用するプロジェクトに該当します。

生成されたプロジェクトに cocos-sdk-native/ios が含まれていることを確認してください。
Podfile に pod 'FTCocosBridge' が存在することを確認してください。
Podfile があるディレクトリで pod install を再実行してください。
.xcodeproj ではなく .xcworkspace を使用してください。
Xcode の Build Folder をクリーンしてから再ビルドしてください。

Creator 2 プロジェクトの iOS 最低バージョンは 12.0 に引き上げられます。Xcode 15 互換のリンクパラメータは、ビルド拡張機能によって生成設定に自動的に書き込まれます。

iOS SPM 設定が反映されない、またはビルドに失敗する¶

SDK パッケージ 0.1.0-alpha.5 以降をインストールし、インストーラーを再実行して Creator 拡張機能を更新したことを確認してください。機能の利用可否は SPM 導入の説明を参照してください。
cocos-sdk.config.json が Cocos プロジェクトのルートディレクトリにあり、ios.dependencyManager が spm であることを確認し、その後 iOS プロジェクトを再生成してください。
生成ディレクトリ内の cocos-sdk-native/FTCocosBridge/Package.swift と、アプリの target の FTCocosBridge パッケージ依存関係を確認してください。初回の解決に失敗した場合は、Xcode がマニフェスト内の Git リポジトリとバージョンタグにアクセスできることを確認してください。
手動で宣言した SDK の Pod や他の Pod が同じネイティブ SDK に依存しているというメッセージが表示される場合は、まずこれらの依存関係の移行を完了してください。既存の Pods の更新に失敗した場合は、ローカルの pod コマンドとエラーメッセージを確認してから再試行してください。
Creator 3 で、旧式のビルド位置が Packages をサポートしていない、または CMake 再生成後にパッケージ参照が失われるというメッセージが表示される場合は、更新後の Creator ビルド拡張機能を再実行してください。拡張機能がビルド位置の設定を調整し、Xcode で CMake の再生成がトリガーされた後に SPM 統合を復元します。
新しい SPM プロジェクトでは .xcodeproj を開いてください。ホストに他の Pods がある場合は引き続き .xcworkspace を使用してください。リンクエラーを解決するために Bridge やネイティブ SDK を手動で追加しないでください。

RUM はあるが View がない¶

autoTrack.scenes: true を有効にする。または
ビジネスシーンに入るときに guanceSdk.rum.startView() を呼び出し、離れるときに stopView() を呼び出します。

初期化が最初のシーン起動より遅い場合、シーンイベントを見逃す可能性があります。最初の収集シーンの前に初期化してください。

自動 Action または Error が有効にならない¶

Action：

autoTrack.actions: true を確認してください。
操作が最終的にグローバルな TOUCH_END をトリガーすることを確認してください。
カスタム入力システムやグローバルイベントを消費するコンポーネントでは、Action API を手動で呼び出す必要があります。

Error：

autoTrack.errors: true を確認してください。
現在のランタイムでグローバルな addEventListener が提供されている必要があります。
ビジネスコードの try/catch で捕捉された例外は、addError() を手動で呼び出す必要があります。

Log にデータがない、または RUM に関連付けられていない¶

logger を初期化し、enableCustomLog: true を設定してください。
sampleRate と logLevelFilters を確認してください。
Console 収集にはさらに autoTrack.console: true が必要です。
RUM との関連付けには、enableLinkRumData: true、有効な RUM Session、現在の View が必要です。
最初の View より前に生成されたログには View が関連付けられていない可能性があります。

Trace Header が空¶

trace が初期化されていることを確認してください。
URL は空にできず、Native SDK が処理できる有効な URL である必要があります。
Trace のサンプリングレートを確認してください。
サポートされていないプラットフォームでは空のオブジェクトが返されます。
自動インジェクションは、ランタイムが提供する fetch と XMLHttpRequest のみを対象とします。

ネットワークデータの重複¶

次の設定が同時に有効になっていないか確認してください。

autoTrack.network と enableNativeUserResource
autoTrack.network と enableNativeAutoTrace
自動ネットワーク収集と、ビジネスコードによる手動の Resource/Trace

同じリクエストスタックに対しては収集経路を 1 つに絞り、RUM の Resource 数とリクエストヘッダーを比較してください。

Android では JS のネットワーク収集を残し、ネイティブの setEnableHttpURLConnectionResource(false) を維持することを推奨します。enableNativeUserResource は全体のスイッチであり、HttpURLConnection 収集を単独で有効にすることはありません。Android ネットワーク収集の推奨設定を参照してください。

iOS では、Creator 2 の NSURLConnection と Creator 3.8.8 の NSURLSession を区別する必要があります。前者は iOS SDK 1.6.8-alpha.5 以降、独立したスイッチで有効になり、後者は従来のスイッチで制御されます。いずれかの経路と JS の自動または手動 Resource を同時に収集すると、重複する可能性があります。iOS ネットワーク収集の推奨設定を参照してください。

Replay パッケージまたはネイティブ統合の欠落¶

0.1.0-alpha.6 以降、Replay には独立した npm パッケージ、コードの組み合わせ、ネイティブ統合の 3 つのステップが必要です。

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

その後、ネイティブプロジェクトを再生成してビルドしてください。CocoaPods を使用する場合は pod install を実行します。コードでは withSessionReplay(baseSdk) が返すインスタンスを使用します。パッケージ分割の移行を参照してください。

メッセージまたは現象	対処方法
`Cannot find module '@cloudcare/cocos-session-replay/...'` / `Session Replay is not installed`	現在の Cocos プロジェクトに、基本パッケージと完全に同じバージョンの Replay パッケージをインストールする
`Session Replay requires @cloudcare/cocos-session-replay`	基本インスタンスの初期化前に `withSessionReplay()` を呼び出し、`replay` 設定を組み合わせた後のインスタンスに渡す
`SDK extension version or Creator engine does not match the base SDK`	2 つのパッケージのバージョンが完全に同一であり、インポートのエントリーポイントがどちらも `/creator2` または `/creator3` であることを確認する
`Install SDK extensions before start() or attach()`	組み合わせの呼び出しを SDK の起動または Hybrid バインドより前に行う
`Session Replay native integration is unavailable`	インストーラーで `--replay` を実行して再ビルドする。Hybrid プロジェクトでは、ネイティブホストが互換バージョンの SDK を初期化していることも確認する
基本パッケージが `setReplayCamera` をエクスポートしなくなった	組み合わせた後のインスタンスの `guanceSdk.setReplayCamera(camera)` を使用する

インストーラーは、ローカルで変更された SDK ファイルを検出すると停止し、具体的なパスを表示します。これらのカスタム変更をバックアップして確認してから再インストールしてください。シーンが参照する ReplayPrivacy.ts や .meta を直接削除しないでください。

Session Replay に画面が表示されない¶

RUM が初期化され、現在有効な View が存在することを確認してください。
シーンに Camera が存在するか、guanceSdk.setReplayCamera() を呼び出していることを確認してください。
Replay と RUM のサンプリングレートが 0 でないことを確認してください。
静止画は重複フレームと判定され、スキップされます。
コンソールにキャプチャ停止エラーが表示されていないか確認してください。
SDK のバージョンと依存関係の要件に従って Session Replay のネイティブ依存関係を確認し、ネイティブプロジェクトを再生成してビルドしてください。

Creator 3 の Replay 画面またはタッチ操作の異常¶

0.1.0-alpha.7 では、表示 Camera がフレームキャプチャの影響を受ける問題、UI コントロールが消費するタッチが Replay で欠落する問題、および Replay 収集が通常の入力配信に影響を与える問題を修正しました。アップグレード手順に従って 2 つの npm パッケージを更新し、再ビルドしてください。

組み合わせた後の guanceSdk.setReplayCamera(camera) を使用して必要な Camera を指定してください。SDK は 1 つの Camera のみを収集し、複数の Camera の画像を合成しません。
Replay にタッチ位置が表示されない場合は、touchPrivacy が明示的に show に設定されているか確認してください。デフォルトの hide では位置は記録されません。autoTrack.actions と Replay のタッチ収集は独立しています。
ボタン、ジョイスティック、空白領域のそれぞれで、ビジネスロジックの応答と Replay の記録を検証してください。旧バージョンのタッチ欠落を補うために、ビジネスの入力ロジックを重複して呼び出さないでください。
画像を縮小した後、タッチとマスクが表示座標と一致していることを確認してください。エンコードされた画像のサイズをゲームの表示サイズと直接みなさないでください。

初期化パラメータが例外をスローする¶

エラー	原因
`Configure datakitUrl or datawayUrl with clientToken`	有効な送信先アドレスが設定されていない
`... must be between 0 and 1`	RUM、Log、Trace、Replay のサンプリングレートが範囲外
`captureFps must be an integer between 1 and 5`	Replay FPS が `1–5` の整数でない
`maxImageDimension must be between 1 and 2048`	Replay の最長辺が範囲外
`... must not be empty`	View、Action、Resource Key、Trace URL などの必須文字列が空

パフォーマンスの問題¶

Session Replay は captureFps: 1、maxImageDimension: 720 から始めてください。
不要な場合は Console の自動収集をオフにしてください。
ログやイベント属性に大きなオブジェクトを渡さないでください。
必要な Native モニタリング指標のみを有効にしてください。
ネットワーク収集が重複していないか確認してください。

SDK をシャットダウンすると収集が停止する¶

guanceSdk.shutdown() は自動リスナーを削除し、Session Replay を停止して Native SDK をシャットダウンします。シャットダウン後は収集メソッドを呼び出し続けないでください。再度有効にする必要がある場合は、アプリケーションを再起動して一度初期化することを推奨します。