Table of Contents

トラブルシューティング：コンテンツが表示されない/アクティブにならない

Image Cloud Recognitionの使用時に、仮想コンテンツが表示されない、またはアクティブにならない問題が発生する可能性があります。本記事では体系的なトラブルシューティング手法を提供します。留意点として、ほとんどのケースにおいてImage Cloud Recognitionの失敗原因はローカル認識失敗と同一であり、平面画像トラッキングのトラブルシューティング章を参照できます。ここではクラウド認識特有の問題と解決策を補足します。

一般的な原因と調査方法

Network connection problem

現象: 認識リクエスト送信後応答がない、またはエラーコードが返される。
調査方法:

  • デバイスがネットワーク接続（Wi-Fi/4G/5G）されているか確認（ウェブページの開封でテスト）。
  • アプリにネットワークアクセス権限があるか確認。
  • コード内でネットワークエラーログをキャプチャ。
  • ブラウザでCRS APIの接続性をテスト（参照：Health check | GET /ping）。

改善提案:

  • アプリ内にネットワーク状態検知機能を追加、通信環境が弱い場合に通知。
  • リクエストタイムアウト後の再試行またはローカルトラッキングへのフォールバックを設定。

サービス設定エラー

現象: 認識リクエストが拒否され、UnauthorizedまたはInvalid Keyが返される。
調査方法:

  • コードに入力したCRS API KeyとSecretが正しいか確認。
  • コードに入力したClient-end URLが誤っていないか確認（例: Server-end URLを誤入力）。
  • License Keyが有効化済みかつ期限切れでないことを確認（EasyAR公式サイトアカウントセンターで確認）。

改善提案:

  • CRSイメージライブラリのコピーボタンを使用して関連サービス設定を複製し、正確に入力することを保証。

ターゲットライブラリ/アプリ設定エラー

現象: 特定のターゲットイメージが過去には認識されたが、現在リクエストが失敗する。
調査方法:

  • CRS API経由でターゲットステータスを取得し、ターゲットイメージが「アクティブ」状態（"active":"1"）であることを確認。
  • ターゲットIDがコード内と完全一致するか確認（大文字小文字を区別）。

改善提案:

  • クラウドイメージライブラリが更新/変更された場合、アプリの特定ターゲットが常にアクティブ状態であることを保証。
  • コードの入念なチェックを実施。

ハイブリッドモードでのローカルロード失敗

現象: クラウド認識は成功したが、ローカルトラッキングが起動せずコンテンツが表示されない。
調査方法:

  • ローカルのImageTargetロード時に例外がスローされていないことを確認（ログを確認）。
  • ImageTrackerが有効化されているか検証。

改善提案:

  • ローカルロード処理をtry-catchでラップし、例外をキャプチャして再試行。
  • 仮想コンテンツがImageTargetの子オブジェクトであり、無効化されていないことを保証。

まとめとベストプラクティス

クラウド認識のコンテンツ非表示問題は主にネットワーク、サービス設定、ターゲット状態の3点に集中し、ハイブリッドモードではローカルロードも要確認。以下の順序で優先調査することを推奨：

  1. ネットワーク接続を確認し、CRSサービスの接続性を検証
  2. License、API Key/Secret、Client-end URLなどのサービス設定を確認
  3. CRSイメージライブラリ内のターゲットイメージ状態を確認、ライブラリとアプリ間のターゲットID一致を保証

問題が複雑な場合は、EasyARデバッグログを有効化するかテクニカルサポートに連絡。