トラブルシューティング: コンテンツが表示/有効化されない
画像クラウド認識を使用する際、仮想コンテンツが表示または有効化されない問題が発生することがあります。本記事では体系的なトラブルシューティング方法を提供します。ほとんどの場合、画像クラウド認識失敗の原因はローカル認識失敗の原因と完全に同じです。平面画像トラッキングの トラブルシューティング セクションを参照できます。ここではクラウド認識特有の問題と解決策のみを補足します。
よくある原因とトラブルシューティング方法
ネットワーク接続の問題
現象: 認識リクエスト送信後に応答がない、またはエラーコードが返される。
トラブルシューティング方法:
- デバイスがネットワーク（Wi-Fi/4G/5G）に接続されているか確認し、Web ページを開いて検証します。
- アプリでネットワーク権限が有効になっているか確認します。
- コード内でネットワークエラーログを取得します。
- ブラウザで CRS API の接続性をテストします（参照: Health check | GET /ping）。
改善提案:
- アプリ内にネットワーク状態検出を追加し、弱いネットワークではプロンプトを表示します。
- リクエスト timeout を設定し、その後 retry するか local tracking にダウングレードします。
サービス設定エラー
現象: 認識リクエストが拒否され、Unauthorized または Invalid Key が返される。
トラブルシューティング方法:
- コードに入力した CRS API Key と Secret が正しいか確認します。
- コードに入力した Client-end URL が間違っていないか確認します（例: 誤って Server-end URL を入力していないか）。
- License Key が有効化され、期限切れでないことを確認します（EasyAR 公式サイトのアカウントセンターで確認）。
改善提案:
- CRS image library の Copy ボタンを使用して関連サービス設定をコピーし、正しく入力されていることを確認します。
Target library/アプリ設定エラー
現象: 以前は問題なく認識できていた target image の認識リクエストが、現在は失敗する。
トラブルシューティング方法:
- CRS API を通じて target 状態を取得し、target image が "activated" 状態（
"active":"1"）であることを確認します。 - target ID がコード内のものと完全に一致しているか確認します（大文字小文字を区別）。
改善提案:
- クラウド image library が更新/変更された場合、アプリの特定 target が常に有効化されていることを確認します。
- コードを慎重に確認します。
Hybrid mode でのローカル読み込み失敗
現象: クラウド認識は成功するが、local tracking が開始されず、コンテンツが表示されない。
トラブルシューティング方法:
- ローカル
ImageTargetの読み込み時に例外が発生していないことを確認します（ログを確認）。 ImageTrackerが有効になっているか検証します。
改善提案:
- ローカル読み込みロジックを
try-catchで囲み、例外を取得して retry します。 - 仮想コンテンツが
ImageTargetの child object であり、無効化されていないことを確認します。
まとめとベストプラクティス
クラウド認識コンテンツが表示されない問題は、主に ネットワーク、サービス設定、target 状態 の 3 つに集中しています。Hybrid mode ではローカル読み込みにも注意が必要です。次の順序で優先的に確認することを推奨します:
- ネットワーク接続を確認し、CRS サービスの接続性を確認する;
- License、API Key/Secret、Client-end URL などのサービス設定を確認する。
- CRS image library の target image 状態を確認し、image library とアプリ内の target ID が一致していることを確認する;
問題が複雑な場合は、EasyAR debug logs を有効にするか、技術サポートに連絡してください。