SDK 테스트 가이드

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

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

note

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

info

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

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

SDK 의존성 추가

저장소 등록

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

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

Groovy (build.gradle)
Kotlin DSL (build.gradle.kts)
Groovy (settings.gradle)
Kotlin DSL (settings.gradle.kts)

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

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

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

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

SDK 추가

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

Groovy (build.gradle)
Kotlin DSL (build.gradle.kts)

implementation 'com.loplat:placeengine:2.1.3.1'

implementation("com.loplat:placeengine:2.1.3.1")

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(이상)로 선언이 필요합니다.

적용 방법은 네이버 지도 적용 가이드 (https://navermaps.github.io/android-map-sdk/guide-ko/) 참고하시면 됩니다.

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

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

compileSdkVersion 34
minSdkVersion 21

로그 뷰 진입

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

Java
Kotlin

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

// 테스트 빌드인 경우 호출
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 호출 버튼을 제공하는 것을 권장합니다.

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

호출 예시

Java
Kotlin

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

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

테스트하기

WiFi 기반의 기본동작 테스트

tip

테스트 어시스턴트 모드를 활용하면 매장 이동 시 로플랫 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 장소 인식

장소 인식 결과

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

매장(장소) 인식 결과
- 매장 인식이 된 경우
  - [ENTER/NEARBY] : 장소 인식 결과 상태 값
  - ENTER: 매장(장소) 내 인식 성공
  - NEARBY: 해당 장소 주변으로 위치 인식
- 매장 인식이 안 된 경우 (실패)
  - Event는 전달되었으나 (인식 로그 1번이 없는 경우, 이미지 참고) 상권, 복합몰, Geofence 등이 인식된 경우
  - 위치 인식 실패 -> 위치 요청한 장소가 매장, 상권, 복합몰, Geofence 중 하나도 인식되지 않은 경우
  - response fail: Location acquisition fail 로그로 확인할 수 있습니다.
상권 인식 결과
- 위치 인식 요청한 장소가 상권에 포함되면 아래와 같이 event로 전달됩니다.
  - [상권 ID] 상권 명, 도시명(위치 요청 당시 기기 위 경도값)
    [7]강남대로, 서울(37.490719941, 127.030670166)
복합몰 인식 결과
- 위치 인식 요청한 장소가 복합몰 내이면 아래와 같이 event로 전달됩니다.
  - [복합몰 ID] 복합몰 명, 지점 명, 카테고리
    [1295]로플랫복합몰,,Theme Park
Geofence 인식 결과
- 위치 인식 요청한 장소가 설정하신 Geofence에 해당하면 (이미지 참고)로그 4와 같이 event로 전달됩니다.
  - (location: 요청한 기기 위·경도 값), [[gfid, fence name, client_code], ....]
위치 요청한 기기의 위·경도 정보
- 위치 인식 요청한 기기의 위·경도 정보가 (이미지 참고)로그 5와 같이 event로 전달됩니다.
  - 위·경도, 층, 정확도, provider

SDK 의존성 추가​

저장소 등록​

SDK 추가​

SDK 버전 설정​

권한 설정​

테스트 도구​

테스트 로그 뷰​

추가 SDK 연동​

로그 뷰 진입​

SDK 로그 목록 화면​

장소 인식 결과 화면​

테스트 어시스턴트 모드​

사용법​

플로팅 버튼 설정​

호출 예시​

테스트하기​

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

장소 인식 시나리오​

장소 인식 결과​