개발 주의사항

API 개발 시 주의사항에 대해 확인합니다.

1. 지도 API 의 라이프사이클

지도 API 의 라이프사이클은 start, resume, pause, finish 단계가 있고 MapView 의 함수로 되어 있습니다. 지도를 시작하는 시점에 start() 를 호출하면 인증과정을 거친 뒤 지도가 실행됩니다.
MapView 가 실행되는 Activity 나 Fragment 의 onResume/onPause 시점에 맞춰 resume(), pause() 를 꼭 호출해줘야 합니다. 그렇지 않으면 지도의 라이프사이클에 문제가 생겨 알 수 없는 크래쉬가 발생 할 수 있습니다.
기본적으로 종료는, MapView 가 포함 된 Activity 가 종료될 때 finish 가 동작합니다. 그 외 지도 종료가 필요할 때는, 사용자가 필요한 특정 시점에는 명시적으로 finish 를 꼭 호출해줘야 합니다.
Activity 가 종료되면서 지도가 finish 되는 것을 막을 때는, setFinishManually() 를 true 로 설정하고 사용자가 원하는 시점에 finish() 를 호출합니다.

2. API 의 비동기 처리

UI 흐름에 방해되지 않고 지도를 빠르게 보여주기 위해, 지도에 변경을 주는 API 호출은 메인(UI) 쓰레드가 아닌 다른 쓰레드에서 수행됩니다. 지도의 수행은 매우 빠르게 처리되서 대부분 별 이슈가 없습니다. 그러나, 이런 내부적인 동작으로 인해 지도에 변경을 주는 set 관련 함수 호출 직후, get 호출로 가져온 변경 된 값을 완벽하게 보장하지 않습니다.

예를 들어, 아래와 같이 지도의 카메라 변경 호출 직후, 바로 카메라 값을 가져오는 코드를 실행 했을 때 변경 된 값이 나오는 것을 보장하지 않습니다.

kakaoMap.moveCamera(CameraUpdateFactory.newCenterPosition(LatLng.from(37.402005, 127.108621)));
CameraPosition position = kakaoMap.getCameraPosition(); // 보장되지 않음

때문에, 카메라 변경 직후 변경 된 값을 가져올 때는 아래와 같이 리스너(또는 콜백)을 이용해야 정확합니다.

kakaoMap.moveCamera(CameraUpdateFactory.newCenterPosition(LatLng.from(37.402005, 127.108621)));
kakaoMap.setOnCameraMoveEndListener(new KakaoMap.OnCameraMoveEndListener() {
    @Override
    public void onCameraMoveEnd(KakaoMap kakaoMap, CameraPosition cameraPosition, GestureType gestureType) {
      // 변경 된 값 보장 됨
    }
});

3. 픽셀 밀도 지원 (MapDpScale)

Android 기기의 다양한 화면 크기 및 해상도에 상관없이 지도의 UI가 일정한 크기로 보여질 수 있도록, 지도 렌더링 시 내부적으로 dp 값을 계산해서 처리하고 있습니다. API 에서 입력받는 모든 pixel 값과 이미지의 크기는 dp 값에 영향을 받습니다.

지도에 적용 된 dp 값은 아래와 같이 가져와서 확인 할 수 있습니다.

(float) kakaoMap.getMapDpScale();

4. 이미지는 drawable-nodpi/ 권장

다양한 화면 크기 및 해상도에 따라 일정하게 지도 UI 가 보여지도록 내부적으로 계산되기 때문에, 지도에 넣는 이미지를 해상도 별 drawable 폴더에 넣지 않아도 됩니다. 이미지가 해상도 별 drawable 폴더마다 있더라도 지도에서 사용하는데 문제는 없지만, 항상 이미지 원본만 가져와서 사용됩니다. 때문에, 지도에서 사용하는 이미지는 drawable-nodpi/ 에 넣는 것을 권장합니다.

5. 로고 표시 정책

카카오지도 API 사용 시 기본적으로 지도의 우하단에 로고가 표시 됩니다. 이에 대한 변경이나 가려짐은 허용되지 않습니다. 앱의 UI 구성상 로고가 지속적으로 가려지는 경우, 아래와 같이 로고의 위치를 옮길 수 있습니다.

kakaoMap.getLogo().setPosition(MapGravity, xPx, yPx);

다만, 일시적으로 잠깐 가려지는 경우는 허용됩니다. 이 외의 경우에도 지도에서 로고가 쉽게 인지 할 수 있도록 노출되어 있어야 합니다.