테스트 어시스턴트 모드 사용자 가이드

1. 테스트 어시스턴트 모드란?

테스트 어시스턴트 모드는 loplat SDK가 고객사 앱 안에서 정상 동작하는지 테스트 단말에서 확인하는 기능입니다.

테스트 어시스턴트 모드는 테스트 전용 SDK 빌드에서만 사용합니다. 일반 사용자에게 배포되는 운영 앱에서는 사용하지 않습니다.

이 모드로 다음 내용을 확인할 수 있습니다.

• SDK가 초기화되었는지
• SDK가 동작 중인지
• 위치 권한과 알림 권한 및 기타 권장 권한이 허용되었는지
• 단말 위치 서비스가 켜져 있는지 (android)
• 장소 인식 결과가 들어오는지

또한 테스트 후 점검 결과와 로그를 loplat 담당자에게 전달할 수 있습니다.

2. 점검 전 준비

테스트를 시작하기 전에 테스트 전용 빌드 SDK가 탑재된 테스트 어시스턴트용 앱 설치해 주세요.

필수

Android는 플로팅 버튼을 사용합니다. 아래 시트가 뜨면 “다른 앱 위에 표시”권한을 허용해 주세요.

플로팅 버튼이 뜬 상태 “다른 앱 위에 표시” 권한 요청

테스트 어시스턴트 화면에서 확인

고객사 테스트 권장 사항에 맞게 준비가 되었는지 테스트 어시스턴트 화면에서 확인할 수 있습니다.

• 테스트 앱 위치 서비스 이용약관 동의
• 단말 위치 서비스 ON
• 앱 위치 권한 허용 (* 항상 허용 권장)
• Android 13 이상 단말에서는 알림 권한 허용

테스트에 필요한 권한이 누락되면 테스트 어시스턴트 화면에서 상태를 확인하고 설정 화면으로 이동할 수 있습니다.

단말 위치 서비스 ON	위치 권한 허용	다른 앱 위에 표시 권한 허용

3. 테스트 어시스턴트 화면 열기

앱을 실행하면 화면 오른쪽에 테스트 어시스턴트 플로팅 버튼이 표시될 수 있습니다.

테스트 어시스턴트 화면을 여는 방법은 다음과 같습니다.

1. 앱을 실행합니다.
2. “다른 앱 위에 표시 권한”을 획득합니다.
3. 화면 오른쪽의 테스트 어시스턴트 플로팅 버튼을 탭합니다.
4. 테스트 어시스턴트 화면에서 SDK 상태와 권한 상태를 확인합니다.

장소 인식 결과 알림을 탭해도 테스트 어시스턴트 화면으로 이동할 수 있습니다.

플로팅 버튼이 보이지 않으면 다음을 확인해 주세요.

• 다른 앱 위에 표시 권한을 허용했는지 확인합니다.
• 앱을 완전히 종료한 뒤 다시 실행합니다.
• 테스트 어시스턴트 화면에서 플로팅 버튼을 숨김 처리하지 않았는지 확인합니다.
  • 이 경우 플로팅 버튼 가시화 버튼으로 SDK에 요청하지 않으면 보이지 않습니다.
  • 앱에 저장된 설정 값을 지우면 플로팅 버튼이 나타나지만 로그인 정보를 포함한 모든 앱 내 정보가 삭제될 수 있습니다.
  • 설정 값 초기화하는 방법은 애플리케이션 설정 > 저장 공간 > 데이터 삭제 후 다시 열어주세요.
• 앱이 테스트 어시스턴트용 SDK를 사용 중인지 확인합니다.

앱을 완전히 종료한 후에 다시 실행하는 방법

• 최근 앱 버튼(≡)을 누른 후 상단에 “실행 중인 앱”버튼을 누르면 백그라운드에서 동작 중인 앱을 확인할 수 있습니다. 테스트 앱이 있다면 중지 후 다시 앱을 열어주세요.
• 앱을 꾹 눌러서 애플리케이션 설정 화면을 열면 앱을 강제 중지 시킬 수 있습니다. 중지 후 다시 앱을 열어주세요.

4. 권한 상태 확인

테스트 어시스턴트 화면 상단에는 주요 권한 상태가 표시됩니다.

확인해야 할 권한은 다음과 같습니다.

• 위치 권한: 위치 인식을 위해 필요합니다.
• 알림 권한: Android 13 이상에서 결과 알림을 받기 위해 필요합니다.
• 신체 활동 권한: SDK 설정에 따라 위치 스캔 최적화에 사용될 수 있습니다.

권한 상태가 허용이 아니면 현장 테스트 기준에 따라 해당 버튼을 눌러 설정 또는 권한 요청 화면으로 이동합니다.

Android 버전에 따라 위치 권한은 "앱 사용 중 허용"과 "항상 허용"으로 나뉠 수 있습니다. 현장 테스트 기준은 고객사 개발팀 또는 loplat 담당자가 안내한 권한 수준을 따라 주세요.

5. 점검 화면에서 볼 항목

테스트 어시스턴트 화면에서는 다음 정보를 확인합니다.

• SDK 설정
  • SDK 버전: 테스트 대상 SDK 버전이 맞는지 확인합니다.
  • 클라이언트 ID: 고객사 앱에 설정된 loplat client id입니다.
  • 앱 ID: 현재 앱 패키지명입니다.
  • 엔진 상태: "시작됨"이면 SDK가 동작 중입니다.
  • 광고/알림 설정: 고객사 앱의 마케팅 및 알림 설정 상태입니다.
• 사용자 식별값
  • Echo code: 고객사의 사용자 구분을 위해 설정된 값입니다.
  • 광고 식별자: 광고 식별자 설정 여부입니다.
  • FCM token id: 일반 캠페인 테스트를 위해 사용되는 식별자입니다.
• 추가 정보
  • 최신 장소: 마지막으로 인식된 장소 정보입니다.
  • 단말 위치 서비스: 단말 위치 서비스가 켜져 있는지 확인합니다.
  • 포그라운드 서비스 상태: SDK 백그라운드 동작에 필요한 서비스 상태입니다.

값이 비어 있거나 예상과 다르면 화면을 캡처하거나 리포트 메일을 보내 loplat 담당자, 고객사 담당자에게 전달해 주세요.

6. 장소 인식 결과 알림 확인

테스트 어시스턴트 모드에서는 장소 인식 성공 응답이 들어오면 알림으로 요약 결과를 보여줍니다.

알림에는 보통 다음 정보가 표시됩니다.

• 응답 시간
• 복합몰, 지점, 매장명 등 장소 정보
• IN 또는 NEAR 상태
• 캠페인 ID 또는 동일 장소 여부
• 행정구역 정보

알림이 오지 않으면 다음을 확인합니다.

• 알림 권한이 허용되어 있는지
• 테스트 어시스턴트 설정에서 "알림"이 켜져 있는지
• 앱 위치 권한과 단말 위치 서비스가 켜져 있는지

7. 테스트 어시스턴트 설정

테스트 어시스턴트 화면의 설정 메뉴에서 다음 항목을 변경할 수 있습니다.

• 알림: 장소 인식 결과 알림 표시 여부
• 진동: 결과 알림 시 진동 여부
• 파일 로그: 점검 로그 저장 여부
• 플로팅 버튼 표시: 테스트 어시스턴트 플로팅 버튼 표시 여부

테스트 어시스턴트 설정 메뉴	파일 로그 종료 시 안내 팝업

파일 로그를 끌 때는 기존 로그를 메일로 보낼지, 삭제할지 선택하는 안내가 표시될 수 있습니다.

점검 중 문제가 있었다면 로그를 삭제하기 전에 리포트 메일을 먼저 보내 주세요.

플로팅 버튼 표시를 끄면 이후 앱을 다시 실행해도 버튼이 자동으로 보이지 않을 수 있습니다. 다시 표시해야 할 경우 고객사 개발팀 또는 loplat 담당자에게 문의해 주세요.

8. 리포트 메일 보내기

문제가 있거나 점검 결과를 공유해야 할 때는 테스트 어시스턴트 화면의 리포트 버튼을 사용합니다.

전송 절차는 다음과 같습니다.

1. 테스트 어시스턴트 화면을 엽니다.
2. 리포트 버튼을 누릅니다.
3. 메일 앱이 열리면 수신자를 확인합니다.
4. 필요하면 테스트 상황을 본문에 추가로 적습니다.
5. 메일을 전송합니다.

메일에는 기기 정보, OS 버전, SDK 상태, Client ID, Echo code, ADID, FCM token id, 테스트 어시스턴트 설정, 테스트 로그 파일이 포함될 수 있습니다.

전송 전 주의사항

• 로플랫 SDK에는 개인정보가 포함된 식별자를 사용하지 않도록 가이드하고 있습니다.
• 운영 고객의 식별자 항목에 개인정보가 포함된 경우에는 고객사 내부 기준을 확인해 주세요.
• 메일은 고객사와 loplat이 사전에 합의한 담당자에게만 보내 주세요.
• 비밀번호, API Key, Token, client_secret 등 인증정보는 본문이나 첨부 설명에 적지 마세요.
• 캡처 이미지나 추가 설명을 넣을 때 전화번호, 이름, 계정, 주소 등 개인정보가 노출되지 않도록 주의해 주세요.

9. 현장 점검 순서 예시

현장에서는 다음 순서로 점검하는 것을 권장합니다.

1. 테스트 앱 설치 후 실행
2. 단말 위치 서비스가 ON인지 확인
3. 위치서비스 이용약관 동의
4. 위치 권한, 알림 권한, 다른 앱 위에 표시 권한 허용
5. 테스트 어시스턴트 플로팅 버튼 탭
6. 엔진 상태가 "시작됨"인지 확인
7. 테스트 장소로 이동하거나 테스트 조건을 충족
8. 장소 인식 결과 알림이 오는지 확인
9. (필요 시) 테스트 어시스턴트 화면의 최신 장소 값이 갱신되는지 확인
10. (필요 시) 리포트 메일 전송

10. 문제 상황별 조치

엔진 상태가 "미초기화"인 경우:

• 앱을 완전히 종료한 뒤 다시 실행합니다.
• 네트워크 연결 상태를 확인합니다.
• 계속 동일하면 리포트 메일을 보내고 고객사 개발팀에 전달합니다.

엔진 상태가 "중지됨"인 경우:

• 위치서비스 이용약관 동의 상태를 확인합니다.
• 앱에서 SDK 시작 조건이 충족되었는지 고객사 개발팀에 확인합니다.

위치 서비스가 OFF인 경우:

• 단말 설정에서 위치 서비스를 켭니다.
• 배터리 절약 모드나 회사 보안 앱이 위치 사용을 제한하는지 확인합니다.

최신 장소가 갱신되지 않는 경우:

• 현재 위치가 테스트 대상 장소인지 확인합니다.
• Wi-Fi, 위치, 네트워크 상태를 확인합니다.
• 몇 분간 대기한 뒤 다시 확인합니다.
• 리포트 메일을 보내 loplat 담당자에게 분석을 요청합니다.

리포트 메일이 열리지 않는 경우:

• 단말에 메일 앱이 설정되어 있는지 확인합니다.
• 회사 보안 정책이 첨부파일 전송을 차단하는지 확인합니다.
• 화면 캡처와 테스트 시간, 단말 모델, 앱 버전을 별도로 전달합니다.

11. 담당자에게 전달하면 좋은 정보

문제 분석을 요청할 때 다음 정보를 함께 전달하면 원인 파악이 빠릅니다.

• 테스트 일시
• 테스트 장소
• 단말 모델과 Android 버전
• 앱 버전
• SDK 버전
• 테스트 어시스턴트 화면 캡처
• 결과 알림 수신 여부
• 리포트 메일과 로그 첨부
• 기대한 동작과 실제 동작

개인정보가 포함될 수 있는 화면 캡처나 로그는 사전에 합의된 채널로만 전달해 주세요.