Skip to content

안드로이드 SDK 가이드

해당 문서는 최신버전 의 SDK를 기준으로 작성되었습니다.

SDK 정보

SDK 지원 버전

  • minSdkVersion 14
  • targetSdkVersion 26

SDK 적용

로플랫 SDK를 사용하기 위해서는 API 키가 필요합니다.

loplat SDK를 사용하기 위해서는 로플랫에서 제공하는 ID와 Secret 키를 발급받아야 합니다.
발급을 원하시는 기업, 개발자는 아래의 내용을 기입하여 business@loplat.com 으로 보내주시기 바랍니다.

  • 이름
  • 회사
  • 사용 목적

권한

  • SDK를 적용하면 하기 권한이 자동으로 추가됩니다.

    • ACCESS_FINE_LOCATION : GPS를 이용하여 현재 위치의 위도와 경도 값을 획득할 수 있는 권한
    • ACCESS_COARSE_LOCATION : WiFi 혹은 Network를 이용하여 현재 위치의 위도와 경도 값을 획득할 수 있는 권한
    • ACCESS_NETWORK_STATE : 네트워크 상태를 확인할 수 있는 권한
    • ACCESS_WIFI_STATE / CHANGE_WIFI_STATE : 주변 WiFi AP들을 스캔하기 위한 권한
    • INTERNET : 인터넷을 사용할 수 있는 권한
    • RECEIVE_BOOT_COMPLETED : 핸드폰 부팅되는 과정을 브로드캐스팅하기 위한 권한
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
    

안드로이드 6.0부터 위치 권한 허용 & GPS가 켜저있는 상태에서만 와이파이 스캔 결과값 획득이 가능합니다.

아래의 권한이 있어야만, 와이파이 스캔을 할 수 있습니다.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  • 권한 설정과 관련하여 좀 더 자세한 사항은 Android Developers 를 참고 바랍니다.

프로젝트에 로플랫 SDK 추가

loplat SDK 종속성 추가 하기

  • 프로젝트 내, 최상위 build.gradle 에 아래의 코드를 추가하세요.

    allprojects {
        repositories {
            jcenter()
            mavenCentral()
            maven { url "https://maven.loplat.com/artifactory/plengi"}
            google()
        }
    }
    
  • 이후 앱의 build.gradle 에 아래의 코드를 추가하세요.

    implementation 'com.loplat:placeengine:[최신버전]'
    

Android 8.0 이상 버전을 위한 Gradle 설정

compileSdkVersion 를 아래와 같이 설정합니다.

android {
	compileSdkVersion 26
	/* 이하 생략 */
}

Android Support 라이브러리 적용

아래의 예시 처럼 appcompat-v7 라이브러리를 26버전 이상으로 적용해주세요.

implementation 'com.android.support:appcompat-v7:26.1.0'

appcompat-v7 라이브러리는 26 버전 이상을 사용해야만 합니다.

appcompat v7의 version이 26이상이 아닌 경우에는 SDK 동작 중 오류가 발생하여 앱 동작이 중지 될 수 있으니 , 기존의 적용된 라이브러리 버전을 확인 후 업그레이드 하시길 바랍니다.

Google Play Services 라이브러리 적용하기

Google Play Services 라이브러리는 11.8.0 버전 이상을 사용해야만 합니다.

SDK 내부에서 현재 위치를 가져오기 위해 Google Play Services API FusedLocationProviderClient 를 사용합니다. 11.8.0 이전 버전을 사용할 경우 해당 API에 대한 버그, 안정성 이슈로 인해 앱 동작이 중지될 수 있습니다.
자세한 사항은 Google Developers - FusedLocationProviderClient 를 참조해주세요.

통합 GOOGLE PLAY SERVICES 라이브러리를 사용하는 경우

아래와 같이 통합 Google Play Services 라이브러리만 사용하면 됩니다.

compile 'com.google.android.gms:play-services:11.8.0'
통합 GOOGLE PLAY SERVICES 라이브러리를 사용하지 않는 경우
  • (필수)효율적인 위치 정보 획득을 위해서 build.gradle 의 dependency에 아래와 같이 라이브러리 적용이 필요합니다.

    compile 'com.google.android.gms:play-services-location:11.8.0'
    
  • loplat X를 사용하기 위해서 build.gradle 의 dependency에 아래와 같이 Google Play Services 라이브러리 적용이 필요합니다.

    compile 'com.google.android.gms:play-services-ads:11.8.0'
    

    loplat X란 무엇인가요?

    loplat X는 오프라인 행동 분석 및 마케팅 솔루션입니다.
    loplat X 사용을 위한 추가 작업은 loplat X 연동하기 를 참고 바랍니다.

Retrofit 및 GSON 라이브러리 적용하기
  • loplat SDK 1.7.10 이상 버전부터 위치 확인 요청시 서버와의 통신을 위해 Retrofit 및 GSON 라이브러리를 사용합니다. Retrofit 및 GSON 라이브러리 적용을 위해서 프로젝트의 build.gradle 에 아래와 같이 추가합니다.

    compile 'com.squareup.retrofit2:retrofit:2.4.0'
    compile 'com.squareup.retrofit2:converter-gson:2.4.0'
    compile 'com.squareup.okhttp3:okhttp:3.11.0'
    
  • Proguard를 사용한다면, 아래와 같이 proguard 설정을 추가해야 합니다.

    -dontwarn okio.**
    -dontwarn javax.annotation.**
    -keepclasseswithmembers class * {
    		@retrofit2.http.* <methods>;
    }
    

SDK 초기화

1. PlengiListener 생성

PlengiListener 인터페이스를 구현합니다.

  • loplat 서버로 부터 받은 모든 결과는 해당 리스너를 통해 전달됩니다.
  • 아래와 같은 인식 이벤트에 따른 결과를 작성합니다.

    • PLACE_EVENT (Enter/Leave/Nearby, Recognizer mode)
    • PLACE_TRACKING (Enter/Leave/Nearby, Tracker mode)
public class LoplatPlengiListener implements PlengiListener {
	@Override
	public void listen(PlengiResponse response) {
		String echoCode = response.echoCode; // init시 전달된 echo code
		if(response.result == PlengiResponse.Result.SUCCESS) {
			if(response.type == PlengiResponse.ResponseType.PLACE_EVENT
				|| response.type == PlengiResponse.ResponseType.PLACE_TRACKING) { //BACKGROUND
				if (response.place != null) {
					// response.place 값이 null이 아닌 경우만 response.placeEvent(ENTER/LEAVE/NEARBY) 값을 사용
					int event = response.placeEvent;
					if (event == PlengiResponse.PlaceEvent.ENTER) {
						// 사용자가 장소에 들어 왔을 때
					} else if (event == PlengiResponse.PlaceEvent.LEAVE) {
						// 사용자가 가장 최근에 머문 장소를 떠났을 때
					} else if (event == PlengiResponse.PlaceEvent.NEARBY) {
						// 사용자가 장소 주변(Nearby)을 방문 했을 때
					}
				}
				if (reponse.area != null) {
					// 상권이 인식 되었을 때
				}
				if (response.complex != null) {
					// 복합몰이 인식 되었을 때
				}
				if (response.advertisement != null) {
					// loplat X 광고 정보가 있을 때
					// loplat SDK 통한 광고 알림을 사용하지 않고
					// Custom Notification 혹은 직접 이벤트 처리 할 경우 해당 객체를 사용
				}
				if (response.geofence != null) {
					// GeoFence 정보
				}
				if (response.location != null) {
					// Device 위경도
        			}
				if (response.district != null) {
					// 행정구역
        			}
			}
		} else {
			// 위치 획득 실패 및 에러
			// response.errorReason 위치 획득 실패 혹은 에러 이유가 포함 되어 있음
			// errorReason -> Location Acquisition Fail(위치 획득 실패), Network Fail(네트워크 연결 실패)
			// Not Allowed Client(잘못된 client id, passwrod 입력), invalid scan results
			if (response.result == PlengiResponse.Result.FAIL) {
				// response.errorReason 확인
			} else if (response.result == PlengiResponse.Result.ERROR_CLOUD_ACCESS) {
				// response.errorReason 확인
			}
		}
	}
}
2. Plengi 인스턴스 생성 및 EventListener 등록

Application 클래스에서 상속 받은 클래스에서 작업해주세요.

Plengi 인스턴스를 생성한 후, 1번에서 생성한 Listener 를 등록해주신 후, 생성한 Application 클래스를 AndroidManifest.xml 에 등록해주세요.

3. Plengi init

Plengi 인스턴스와 이벤트 등록은 무조건 Application 클래스의 onCreate() 에서 해야합니다.

Application 클래스의 onCreate()init(SDK 초기화)과 setListener(리스너 등록)을 선언하지 않으면 SDK가 동작하지 않습니다.

  • 사용자의 매장/장소 방문을 모니터링하기 위해 Plengi Engine을 초기화합니다.
  • 생성한 Application 클래스(2번 항목 참조)에서 Plengi init을 다음과 같이 선언을 합니다.

    Plengi.getInstance(this).init(clientId, clientSecret, echoCode);
    
  • init을 위해 clientId, clientSecret, echoCode 인자값으로 전달해주셔야합니다.

    • clientId / clientSecret : loplat server로 접근하기 위한 ID와 PW입니다.

    • echoCode: 앱에서 사용자 식별(관리용) 및 추적하기 위한 ID입니다 (ex, 광고id,id,....,etc.). echoCode 관리를 원하지 않는 경우 null 값을 입력하면 됩니다.

      echoCode 에는 개인정보가 포함되면 안됩니다.

      이메일, 전화번호와 같은 개인정보는 전달하지 마세요.

  • 예시코드

생성한 Application 클래스는 무조건 AndroidManifest.xml에 등록해야합니다.

생성한 Application 클래스를 AndroidManifest.xml 에 등록해주세요. 등록하지 않은 경우, SDK가 동작하지 않습니다.

public class LoplatSampleApplication extends Application {
	@Override
	public void onCreate() {
		super.onCreate();
		Plengi.getInstance(this).setListener(new LoplatPlengiListener());
		Plengi.getInstance(this).init("[CLIENT_ID]", "[CLIENT_SECRET]", "[ECHO_CODE]");
	}
}
<application
	android:name=".LoplatSampleApplication"
	android:icon="@mipmap/ic_launcher"
	android:label="@string/app_name"
	android:theme="@style/AppTheme" >
	<!-- 이하 생략... -->
>

SDK 구동하기

Start/Stop

  • 사용자 장소/매장 방문 모니터링을 시작하거나 정지 할 수 있습니다.

    SDK에는 Start / Stop 이 중복으로 호출될 수 없도록 처리되어 있습니다.

    start/stop을 중복 호출 하더라도 SDK 내에서 1회만 호출되도록 구현되어 있습니다.

    예외적인 케이스에 대해서는 Stop을 호출하면 안됩니다.

    예외적인 케이스에 대해서 stop을 호출하지 마세요. stop은 사용자의 위치약관동의에 대한 거부시에만 호출해주세요.

  • 설정된 주기마다 WiFi 신호를 스캔하여 사용자의 위치를 확인합니다.

  • 사용자의 위치 정보는 PlengiEventListener로 전달됩니다.
  • 모니터링 시작과 정지는 다음과 같이 선언합니다.

    Plengi.getInstance(this).start(); //Monitoring Start
    Plengi.getInstance(this).stop(); //Monitoring Stop
    

장소인식결과

  • 장소 결과 값은 PlengiResponse 객체로 전달 됩니다.

    장소 인식 결과에 따라 PlengiResponse 객체에서 사용할 수 있는 정보가 달라집니다.

    장소 인식시 인식된 장소 결과에 따라 area (상권정보), complex (복합몰) 정보가 추가로 전달됩니다. 상권만 인식된 경우에는 place 정보가 nil 로 넘어가니 코드 작성시 주의 부탁드립니다.

  • echoCode ( 사용자 식별 code 값 )

    public String echo_code;	// 사용자 식별 echo code
    
    • init시 전달한 echo_code 값이 전달됩니다. (PlengiListener 예시를 참고 바랍니다)
  • result (위치 인식 성공/실패)

    public int result;	// 위치 인식 성공/실패 결과
    // PlengiResponse.Result.SUCCESS -> 성공, PlengiResponse.Result.FAIL -> 실패
    
  • 위치 인식 실패 한 경우

    • errorReason : 위치 인식 실패한 사유

      public String errorReason;	// 실패 사유
      
      • 현재 위치 획득 실패: Location Acquisition Fail
      • 클라이언트 인증 실패: Not Allowed Client
  • 위치 인식 성공 한 경우

    • type : 위치 요청 타입

      public int type; 	// 위치 요청 타입
      // ResponseType.PLACE  		테스트 용 TEST_refreshPlace_foreground() 요청시
      // ResponseType.PLACE_EVENT 	설정된 주기에 따라 요청시
      
    • placeEvent : 인식된 place event 타입 (ENETER, NEARBY, LEAVE)

      public int placeEvent;		// 인식된 event 타입
      // PlaceEvent.ENTER 		Place에 들어감
      // PlaceEvent.LEAVE 		Place에서 떠남
      // PlaceEvent.NEARBY 	Place근처에 있음
      
    • place : 위치 정보 (PlengiResponse.Place 클래스, response.place로 획득 가능)

      class Place {
      	public long loplatid;        // 장소 id
      	public String name;          // 장소 이름
      	public String tags;          // 장소와 관련된 tag
      	public int floor;            // 층 정보
      	public String category;      // 장소 유형
      	public String category_code; // 장소 유형 코드
      	public double lat;           // 인식된 장소의 위도
      	public double lng;	         // 인식된 장소의 경도
      	public float accuracy;       // 정확도
      	public float threshold;      // 한계치
      	public String client_code;   // 클라이언트 코드
      	public String address;       // 장소 (구)주소
      	public String address_road;  // 장소 신 주소
      	public String post;          // 우편번호
      }
      
      • accuracy > threshold: 현재 위치 내에 있는 경우
      • 그 외에 경우: 현재 위치 근처에 있는 경우
    • Area : 상권 정보 (PlengiResponse.Area 클래스, response.area로 획득 가능)

      • 장소 위치 요청한 장소가 상권 안일 경우 상권 정보가 인식 결과에 함께 같이 전달됩니다.
      • 위도 및 경도는 아래의 조건으로 결과가 전달됩니다.

        • 장소 인식 결과값이 있다면 -> 인식된 장소 위도/경도
        • 장소 인식 결과값이 없으면 -> device의 위도/경도
      class Area {
      	public int id;         // Area ID
      	public String name;    // 상권 이름
      	public String tag;     // 상권 위치 [도, 시 단위 ex) 서울, 경기도, 인천]
      	public double lat;     // 위도
      	public double lng;     // 경도
      }
      
    • Complex : Complex(복합몰) 정보 (PlengiResponse.Complex 클래스, response.complex로 획득 가능)

      • 인식된 장소가 복합몰 내인 경우 복합몰 정보도 함께 인식 결과에 포함되어 전달됩니다.
      class Complex {
      	public int id;         // Complex ID
      	public String name;    // 복합몰 이름
      	public String branch_name;     // 복합몰 지점명
      	public String category;     // 카테고리
      	public String category_code;     // 카테고리 코드
      }
      
    • Advertisement : 광고 (PlengiResponse.Advertisement 클래스, response.advertisement 결과 전달)

      class Advertisement {
      	private int campaign_id;	// loplat X 캠페인 ID
      	private int msg_id;			// loplat X 광고 ID
      	private String title;       // 광고 제목
      	private String body;    	// 광고 내용
      	private String intent;     	// 광고 이벤트 타입 (In-App, url link)
      	private String target_pkg;	// 광고 대상 앱 패키지 명
      	private long delay;			// 광고 알림 delay time
      	private String delay_type;	// 광고 알림 delay type (enter, leave)
      	private String img; 		// 광고 이미지 URL
      	private String client_code;	// 광고에 대한 client code
      }
      
    • GeoFence : Geofence & Fence (PlengiResponse.Geofence 클래스, response.geofence 결과 전달), fence 정보는 geofence에 포함되어 전달

      class Geofence {
      	private double lat;  				// GeoFence (중심)위도
      	private double lng;  				// GeoFence (중심)경도
      	private ArrayList<Fence> fences;	// GeoFence 리스트
      }
      
      class Fence {
      	private long gfid; 			// 지오펜스 관리 ID
      	private float dist;	// 거리; 중심 좌표와 사용자 위치 간 거리 (optional - 중심 좌표가 있는 경우만 속성값 존재)
      	private String name; 		// 이름
      	private String clientCode; //고객사 측 관리 ID
      }
      
    • District : 행정구역 (PlengiResponse.District 클래스, response.district 결과 전달)

      class District {
      	private String lv0_code; // 국가 코드, code만 지원
      	private String lv1_code; // 시, 도
      	private String lv1_name;
      	private String lv2_code; // 구, 군
      	private String lv2_name;
      	private String lv3_code; // 동, 면
      	private String lv3_name;
      }
      

loplat X 연동하기

loplat X를 사용하기 위해서는 등록이 필요합니다.

미등록 시 서비스 이용에 제한이 발생할 수 있습니다. 자세한 사항은 로플랫 비즈니스팀에 문의 바랍니다.

  • loplat X 를 통해 푸시 메시지 (광고 및 알림 메시지)를 받기 위해서는 광고 알림 허용을 한 시점에 아래와 같이 코드 작성이 필요 합니다.
  • 직접 구현한 Notification을 사용을 원하는 경우 (예시 코드 참조), 광고 정보 값은 장소 인식 결과 내의 Advertisement(response.advertisement)를 확인하면 됩니다.

    // 직접 푸시 메시지를 사용하는 경우
    Plengi.getInstance(this).enableAdNetwork(true, false);
    // SDK 내 푸시 메시지를 사용하는 경우
    Plengi.getInstance(this).enableAdNetwork(true);
    // 푸시 메세지 설정이 on된 경우 해당, 직접 Notification을 사용하는 경우 구현할 필요 없음
    Plengi.getInstance(this).setAdNotiSmallIcon([small icon id]);  // 푸시 메세지 small icon (예시 : R.drawable.notification_icon)
    Plengi.getInstance(this).setAdNotiLargeIcon([large icon id]);  // 푸시 메세지 large icon (예시 : R.drawable.notification_icon)
    

샘플앱