문제 해결: 콘텐츠 표시/활성화 안됨
이미지 클라우드 인식 사용 중 가상 콘텐츠가 표시되지 않거나 활성화되지 않는 문제가 발생할 수 있습니다. 본 문서는 체계적인 문제 해결 방법을 제공합니다. 대부분의 경우 이미지 클라우드 인식 실패 원인은 로컬 인식 실패와 완전히 동일하므로, 평면 이미지 트래킹의 문제 해결 챕터를 참조할 수 있습니다. 여기서는 클라우드 인식에 특화된 문제 및 해결 방안만 보완합니다.
일반적인 원인과 해결 방법
네트워크 연결 문제
증상: 인식 요청 전송 후 응답 없음, 또는 오류 코드 반환.
해결 방법:
- 기기가 인터넷에 연결되어 있는지 확인(Wi-Fi/4G/5G), 웹페이지 열기 시도.
- 애플리케이션이 네트워크 접근 권한을 갖고 있는지 확인.
- 코드에서 네트워크 오류 로그를 캡처.
- 브라우저에서 CRS API 연결성 테스트 (참조: 헬스 체크 | GET /ping).
개선 권장사항:
- 앱 내 네트워크 상태 감지 기능 추가, 약한 네트워크 시 알림.
- 요청 타임아웃 후 재시도 또는 로컬 트래킹으로 다운그레이드 설정.
서비스 구성 오류
증상: 인식 요청 거부, Unauthorized 또는 Invalid Key 반환.
해결 방법:
- 코드에 입력된 CRS API Key 및 Secret이 정확한지 확인.
- 코드에 입력된 Client-end URL이 잘못 입력되지 않았는지 확인(예: 실수로 Server-end URL 입력).
- 라이선스 Key가 활성화되었고 만료되지 않았는지 확인(EasyAR 공식 웹사이트 계정 센터에서 확인).
개선 권장사항:
- CRS 이미지 라이브러리의 복사 버튼을 사용하여 관련 서비스 설정을 복사, 정확한 입력 보장.
타겟 라이브러리/애플리케이션 구성 오류
증상: 특정 타겟 이미지가 과거에는 인식되었으나 현재 인식 요청 실패.
해결 방법:
- CRS API를 통해 타겟 상태 획득, 타겟 이미지가 "활성화" 상태인지 확인(
"active":"1"). - 타겟 ID가 코드와 완전히 일치하는지 확인(대소문자 구분).
개선 권장사항:
- 클라우드 이미지 라이브러리 업데이트/변경 시, 애플리케이션의 특정 타겟이 항상 활성화되도록 보장.
- 신중한 코드 검토.
하이브리드 모드에서 로컬 로딩 실패
증상: 클라우드 인식 성공했으나 로컬 트래킹이 시작되지 않아 콘텐츠 표시 안됨.
해결 방법:
- 로컬
ImageTarget로딩 시 예외가 발생하지 않았는지 확인(로그 확인). ImageTracker가 활성화되었는지 검증.
개선 권장사항:
- 로컬 로딩 로직을
try-catch로 감싸 예외를 포착하고 재시도. - 가상 콘텐츠가
ImageTarget의 자식 오브젝트이며 비활성화되지 않았는지 확인.
요약과 모범 사례
클라우드 인식 콘텐츠 미표시 문제는 주로 네트워크, 서비스 구성, 타겟 상태 세 가지 측면에 집중되며, 하이브리드 모드에서는 로컬 로딩 단계도 확인해야 합니다. 다음 순서로 우선적으로 문제 해결을 권장합니다:
- 네트워크 연결 확인, CRS 서비스 연결성 확인;
- 라이선스, API Key/Secret, Client-end URL 등 서비스 설정 확인.
- CRS 이미지 라이브러리에서 타겟 이미지 상태 확인, 라이브러리와 애플리케이션의 타겟 ID 일치 보장;
문제가 복잡한 경우 EasyAR 디버그 로그를 활성화하거나 기술 지원에 문의하십시오.