Skip to content

안드로이드 SDK 가이드

해당 문서는 SDK 버전 v 2.0.4.8 을 기준으로 작성되었습니다.

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:2.0.4.8'
    

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.3.0'
    compile 'com.squareup.retrofit2:converter-gson:2.3.0'
    compile 'com.squareup.okhttp3:okhttp:3.8.1'
    
  • Proguard를 사용한다면, 아래와 같이 proguard 설정을 추가해야 합니다.

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

SDK 초기화

1. PlengiListener 생성

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

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

    • PLACE (Recognize a place)
    • 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_ADV_TRACKING
                || 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 정보
                }
            }
        } 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
      }
      

loplat X 연동하기

loplat X를 사용하기 위해서는 아래의 필수 권한이 필요합니다.

loplat X는 위치 권한이 허용되어있어야 하고, GPS가 켜져있는 상태에서 동작하오니 코드 작성시 유의하시기 바랍니다.

  • 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)
    

샘플앱