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

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

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

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 設定が反映されない、またはビルドに失敗する¶

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

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

エラー	原因
`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 のシャットダウンが行われます。シャットダウン後は、収集メソッドを呼び出し続けないでください。再び有効にする必要がある場合は、アプリを再起動して初期化を 1 回実行することをお勧めします。