본문으로 건너뛰기

SDK 테스트 가이드

해당 가이드는 로플랫에서 제공하는 테스트용 loplat SDK를 앱에 탑재하는 과정을 안내합니다.

탑재를 시작하기에 앞서 아래의 정보를 확인해주세요.

노트

이 문서는 2.1.3.1-staging-docs 버전을 기준으로 작성되었습니다.

정보

테스트용 SDK 탑재는 종속성을 제외하면 릴리즈용 SDK와 동일한 과정으로 탑재 가능합니다.

따라서 가이드에서는 종속성 및 테스트용 도구를 활성화하는 방법을 안내해 드립니다.

SDK 의존성 추가​

저장소 등록​

프로젝트 루트의 Gradle 설정에 저장소를 추가합니다.

템플릿에 따라 build.gradle / settings.gradle 구조가 다를 수 있습니다. 사용 중인 템플릿에 맞게 추가해 주세요.

allprojects {
    repositories {
        mavenCentral()
        maven { url "https://maven.loplat.com/artifactory/plengi-debug" }
        google()
    }
}

SDK 추가​

앱 모듈 build.gradle / build.gradle.kts 에 아래를 추가합니다.

implementation 'com.loplat:placeengine:2.1.3.1-staging-docs'

SDK 버전 설정​

테스트 모드를 사용하려면 minSdkVersion 21(이상) 선언이 필요합니다.

compileSdkVersion, minSdkVersion 을 아래와 같이 선언을 합니다.

compileSdkVersion 34
minSdkVersion 21

권한 설정​

"권한 선언"

SDK 내 AndroidManifest.xml 가 선언되어 있으므로 별도의 선언은 따로 하지 않아도 됩니다.

앱을 모바일 디바이스에서 원활하게 테스트하기 위하여 아래 권한 및 설정을 꼭 체크해 주세요

테스트 모드 동작을 위해 아래의 권한들이 허용되어야 합니다.

  • 단말 위치 서비스: 단말의 위치 정보를 받기 위함

  • 알림 권한 (Android 13 이상 환경): 결과 알림을 받기 위해 필요합니다.

  • 위치 권한: Wi-Fi scanning 결과, GPS (위·경도) 값을 반환받기 위함

  • 외부 저장소 쓰기 권한: SDK 동작 로그를 파일에 쓰기 위함

  • 계정 정보 읽기: 파일 로그를 메일로 전송할 때 사용

  • 다른 앱 위에 표시 권한: Floating view를 화면에 띄우기 위함 (아래 사진 참고)

    • 다른 앱 위에 표시되는 앱 권한 허용


테스트 도구​

테스트 로그 뷰​

테스트 로그 뷰는 loplat SDK가 고객사 앱 안에서 정상 동작하는지 확인할 수 있도록 장소 인식 결과 목록을 별도 화면으로 제공합니다.

장소 인식 결과 목록 조회뿐만 아니라 지도 위 pin을 통해 장소를 쉽고 빠르게 확인할 수 있습니다.

"테스트 로그 뷰는 테스트 전용 SDK에서만 사용할 수 있습니다"

일반 사용자에게 배포되는 운영 앱에서는 활성화되지 않습니다.

추가 SDK 연동​

네이버 지도를 활용하기 때문에 해당 SDK의 제약에 맞추어 compileSdkVersion 34(이상)로 선언이 필요합니다.

"네이버 지도 SDK V3 요구 설정값"

네이버 지도 V3에서 요구하는 SDK version 설정값은 아래와 같습니다.

compileSdkVersion 34
minSdkVersion 21

로그 뷰 진입​

테스트 빌드 여부를 확인한 뒤 showPlaceHistoryActivity를 호출해 주세요.

// 테스트 빌드인 경우 호출
if (BuildConfig.DEBUG_MODE) {
  PlaceHistoryHelper.getInstance().showPlaceHistoryActivity(context);
}

SDK 로그 목록 화면​

SDK 로그 목록 화면은 5가지 기능 버튼과 리스트 화면으로 구성되어 있습니다.

상단 기능 버튼

  • 1번 : 현재 위치 확인하기

    • 현재 위치에서 Wi-Fi scanning 결과를 통해 위치 확인

  • 2번 : 로그 파일 메일로 보내기

    • SDK 동작 로그를 원하는 메일 주소로 전송 가능

  • 3번 : 로그 파일 삭제 하기

  • 4번 : TAG, 검색어로 로그 필터링

  • 5번 : 로그 검색

로그 목록

  • 로그 목록 화면은 SDK 동작 로그와 장소 인식 결과 위치를 확인할 수 있는 지도 버튼으로 구성되어 있습니다.

  • 로그 값 예시 로플랫 사무실을 예시로 로그를 해석하면 아래와 같습니다.

    [ENTER] 로플랫,여원빌딩(12345), 9F, 0.889/0.629
    [260]강남대로,서울(37.499182,127.028928)
    Location) 37.4990905, 127.0291293, 1, 15.612, loplat
    서울 강남구 역삼1동
    • [BG]/[FG] : foreground, background wifi scanning 당시의 앱 상태 값

    [ENTER] 로플랫,여원빌딩(12345), 9F, 0.889/0.629

    • [ENTER] : 인식 장소 결과 상태 값, [ENTER] / [NEARBY]
    • 로플랫 : 장소명
    • 여원빌딩(12345) : 지점 명/태그(장소ID) - 9F : 층(floor) 정보
    • 0.889 / 0.629 : 인식 정확도

    [260]강남대로,서울(37.499182,127.028928)

    • [260] : Area ID
    • 강남대로,서울(37.499182,127.028928) : 상권(지역)명(위도,경도)

    Location) 37.4990905, 127.0291293, 1, 15.612, loplat

    • 37.4990905 : 위도
    • 127.0291293 : 경도
    • 1 : 층(floor)
    • 15.612 : 정확도
    • loplat : provider

  • 6번 : 장소 인식 결과 확인

    • 장소 인식 결과 화면으로 이동

장소 인식 결과 화면​

SDK를 통해 인식된 장소의 위치를 지도 위에서 바로 확인할 수 있습니다.


테스트 어시스턴트 모드​

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

"테스트 어시스턴트는 테스트 전용 SDK에서만 사용할 수 있습니다"

일반 사용자에게 배포되는 운영 앱에서는 활성화되지 않습니다.

테스트 어시스턴트 모드 사용 시, 다음 내용을 확인할 수 있습니다.

  • SDK가 정상적으로 초기화되었는지

  • SDK가 동작 중인지

  • 플랫폼별 필요 권한(위치 권한, 알림 권한 등)이 허용되었는지

  • 위치 요청 결과가 들어오는지

또한 테스트 후 고객사 앱의 SDK 관련 상태 값과 SDK 동작 로그를 loplat 담당자에게 전달할 수 있습니다.

사용법​

앱을 실행하면, 오른쪽 아래의 플로팅 버튼을 이용해 테스트 어시스턴트 화면 진입할 수 있습니다.

상세한 사용 가이드는 SDK 테스트 사용자 가이드를 확인해주세요

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

플로팅 버튼 설정​

테스트 모드 사용 중 설정 화면에서 플로팅 버튼 표시 옵션을 끄면, 다시 표시하기 위해 앱 재설치 또는 앱 데이터 초기화가 필요할 수 있습니다.

플로팅 버튼을 다시 표시할 수 있도록 개발/테스트용 화면에 setStatusCheckOverlayButtonVisible 호출 버튼을 제공하는 것을 권장합니다.

이를 통해 테스트 중 플로팅 버튼 가시성을 손쉽게 전환할 수 있습니다.

호출 예시​

// 버튼 띄우기
Plengi.getInstance(context).setStatusCheckOverlayButtonVisible(true);
// 버튼 숨기기
Plengi.getInstance(context).setStatusCheckOverlayButtonVisible(false);

테스트하기​

WiFi 기반의 기본동작 테스트​

팁

테스트 어시스턴트 모드를 활용하면 매장 이동 시 로플랫 SDK 위치 확인 결과를 알림으로 확인하실 수 있습니다.

장소 인식 시나리오​

Case 1. 매장(장소) 방문 인식 (IN)

A 매장에서 약 4분 정도 머무름 -> A 장소 인식 & 장소 인식 Event 발생

Case 2. 매장 주변 인식 (NEARBY)

A 매장(장소) (밖) 20m 이내 주변 약 4분 정도 머무름 -> A 장소 Nearby Event 발생

Case 3. 다른 매장 이동

A 장소에서 약 4분 정도 머무름 -> A 장소 In (ENTER) 인식 -> B 장소로 이동 -> B 장소에서 약 4분 정도 머무름 -> B 장소 인식

장소 인식 결과​

테스트하기 전에 아래 내용을 숙지해 주세요.

  1. 매장(장소) 인식 결과

    • 매장 인식이 된 경우

      • [ENTER/NEARBY] : 장소 인식 결과 상태 값
      • ENTER: 매장(장소) 내 인식 성공
      • NEARBY: 해당 장소 주변으로 위치 인식

    • 매장 인식이 안 된 경우 (실패)

      • Event는 전달되었으나 (인식 로그 1번이 없는 경우, 이미지 참고) 상권, 복합몰, Geofence 등이 인식된 경우
      • 위치 인식 실패 -> 위치 요청한 장소가 매장, 상권, 복합몰, Geofence 중 하나도 인식되지 않은 경우
      • response fail: Location acquisition fail 로그로 확인할 수 있습니다.

  2. 상권 인식 결과

    • 위치 인식 요청한 장소가 상권에 포함되면 아래와 같이 event로 전달됩니다.

      • [상권 ID] 상권 명, 도시명(위치 요청 당시 기기 위 경도값)

        [7]강남대로, 서울(37.490719941, 127.030670166)

  3. 복합몰 인식 결과

    • 위치 인식 요청한 장소가 복합몰 내이면 아래와 같이 event로 전달됩니다.

      • [복합몰 ID] 복합몰 명, 지점 명, 카테고리

        [1295]로플랫복합몰,,Theme Park

  4. Geofence 인식 결과

    • 위치 인식 요청한 장소가 설정하신 Geofence에 해당하면 (이미지 참고)로그 4와 같이 event로 전달됩니다.
      • (location: 요청한 기기 위·경도 값), [[gfid, fence name, client_code], ....]

  5. 위치 요청한 기기의 위·경도 정보

    • 위치 인식 요청한 기기의 위·경도 정보가 (이미지 참고)로그 5와 같이 event로 전달됩니다.
      • 위·경도, 층, 정확도, provider