문제 해결: 콘텐츠가 표시/활성화되지 않음
이미지 클라우드 인식을 사용할 때 가상 콘텐츠가 표시되거나 활성화되지 않는 문제가 발생할 수 있습니다. 이 문서는 체계적인 문제 해결 방법을 제공합니다. 대부분의 경우 이미지 클라우드 인식 실패 원인은 로컬 인식 실패 원인과 완전히 동일하다는 점에 유의하십시오. 평면 이미지 tracking의 문제 해결 섹션을 참조할 수 있습니다. 여기서는 클라우드 인식 고유의 문제와 해결 방법만 보충합니다.
일반적인 원인과 문제 해결 방법
네트워크 연결 문제
현상: 인식 요청을 보낸 후 응답이 없거나 오류 코드가 반환됩니다.
문제 해결 방법:
- 기기가 네트워크(Wi-Fi/4G/5G)에 연결되어 있는지 확인하고, 웹 페이지를 열어 검증합니다.
- 앱에 네트워크 권한이 활성화되어 있는지 확인합니다.
- 코드에서 네트워크 오류 로그를 캡처합니다.
- 브라우저에서 CRS API 연결성을 테스트합니다(참고: Health check | GET /ping).
개선 제안:
- 앱 내에 네트워크 상태 감지를 추가하고, 약한 네트워크에서는 안내를 표시합니다.
- 요청 timeout을 설정한 뒤 retry하거나 local tracking으로 downgrade합니다.
서비스 구성 오류
현상: 인식 요청이 거부되고 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 상태 세 가지 측면에 집중됩니다. Hybrid mode에서는 로컬 로딩 단계도 주의해야 합니다. 다음 순서로 우선 점검하는 것이 좋습니다:
- 네트워크 연결을 확인하고 CRS 서비스 연결성을 확인합니다;
- License, API Key/Secret, Client-end URL 등의 서비스 설정을 확인합니다.
- CRS image library에서 target image 상태를 확인하고, image library와 앱의 target ID가 일치하는지 확인합니다;
문제가 복잡한 경우 EasyAR debug logs를 활성화하거나 기술 지원에 문의하십시오.