[Android] 구글·네이버·카카오 지도 길찾기 연동 및 Android 11 패키지 가시성(Queries) 대응

관광 앱이나 위치 기반 서비스를 만지다 보면 장소 상세 화면에서 외부 지도 앱(구글지도, 네이버지도, 카카오맵)으로 길찾기를 연결해야 하는 경우가 필수적으로 생깁니다.

처음에는 단순하게 URI 스킴 하나 호출하면 끝날 줄 알았는데, 막상 여러 기기에서 테스트하고 운영하다 보면 예외 상황이 계속 터지더군요. 특정 지도 앱이 안 깔려 있어서 앱이 뻗거나, 서버에서 넘어온 좌표 데이터가 일시적으로 누락되어 엉뚱한 곳을 가리키는 등의 문제가 발생합니다.

매번 화면마다 코드를 복사해서 붙여넣기에는 관리도 안 되고 조만간 지도 앱 정책이 바뀌면 골치가 아파집니다. 그래서 아예 외부 앱 실행 기능을 공통 모듈로 분리해서 안전하게 처리하는 방식으로 구현했습니다. 나중에도 꺼내 쓰려고 블로그에 기록해 둡니다.

1. 내가 겪은 문제와 설계 기준

이래저래 앱을 배포하고 운영하면서 자주 놓치기 쉬운 예외 상황들은 대략 이렇습니다.

  • 사용자 기기에 특정 지도 앱이 무조건 설치되어 있다고 가정하고 호출함 (미설치 시 크래시 위험)

  • 좌표 정보(위경도)가 비어 있거나 잘못되었는데도 그대로 Intent를 던짐

  • 앱이 없을 때 마켓(Play 스토어)으로 보내거나 웹 지도(브라우저)로 띄워주는 안전장치(Fallback)가 없음

  • Android 11(API 30) 이상에서 도입된 패키지 가시성(Package Visibility) 정책을 고려하지 않아 앱 감지가 안 됨

  • 테스트 코드나 공개 저장소에 실제 운영 서버 URL이나 특정 관광지 좌표를 그대로 하드코딩함

결국 핵심은 단순히 "지도 앱을 여는 것"이 아니라, [좌표 검증 → 앱 설치 여부 확인 → 안전한 Intent 생성 → 실패 시 웹/마켓 Fallback 처리 → 사용자 안내]까지의 흐름을 하나의 파이프라인으로 묶어주는 것입니다.

지도 앱 연동 흐름도

단계설명실패 시 처리
좌표 검증위도와 경도 값이 정상 범위에 있는지 확인사용자에게 "위치 정보가 없다"고 안내 후 중단
지도 앱 선택사용자가 원하는 지도 브라우저/앱 선택다이얼로그 또는 기본 설정값 활용
Intent 생성앱별 고유 URI 스킴으로 Intent 빌드잘못된 포맷이면 실행 취소
설치 여부 확인해당 패키지를 처리할 수 있는 앱이 기기에 있는지 조회앱이 없으면 웹 지도 URL이나 마켓으로 전환
최종 실행외부 지도 앱 구동예외 발생 시 안전하게 Toast 안내

2. 해결 코드: MapRouteLauncher 공통 모듈

화면단(Activity나 Fragment)에 스킴 코드를 파편화하지 않고, 하나의 헬퍼 클래스로 묶어서 처리한 구조입니다. 아래 예제 코드는 실제 프로젝트에 적용했던 구조에서 중요 정보와 좌표를 더미 값으로 걷어낸 형태입니다. 바로 복사해서 프로젝트 환경에 맞게 변형해 쓰시면 됩니다.

Kotlin
data class PlaceLocation(
    val name: String,
    val latitude: Double,
    val longitude: Double,
)

enum class MapApp {
    GOOGLE,
    NAVER,
    KAKAO,
    WEB,
}

class MapRouteLauncher(
    private val context: Context,
) {
    fun openRoute(mapApp: MapApp, location: PlaceLocation) {
        // 1. 좌표 및 데이터 검증
        if (!isValidLocation(location)) {
            showMessage("위치 정보가 올바르지 않습니다.")
            return
        }

        // 2. 선택한 앱에 따른 Intent 생성
        val intent = when (mapApp) {
            MapApp.GOOGLE -> googleMapIntent(location)
            MapApp.NAVER -> naverMapIntent(location)
            MapApp.KAKAO -> kakaoMapIntent(location)
            MapApp.WEB -> webMapIntent(location)
        }

        // 3. 앱 실행 가능 여부 확인 후 분기
        if (canOpen(intent)) {
            context.startActivity(intent)
            return
        }

        // 4. 네이티브 앱 실행 실패 시 브라우저(Web)를 최종 안전장치로 활용
        val fallback = webMapIntent(location)
        if (canOpen(fallback)) {
            context.startActivity(fallback)
        } else {
            showMessage("길찾기를 실행할 수 있는 앱이나 브라우저가 없습니다.")
        }
    }

    private fun googleMapIntent(location: PlaceLocation): Intent {
        val uri = Uri.parse("google.navigation:q=${location.latitude},${location.longitude}")
        return Intent(Intent.ACTION_VIEW, uri).apply {
            setPackage("com.google.android.apps.maps")
        }
    }

    private fun naverMapIntent(location: PlaceLocation): Intent {
        // 장소명은 반드시 URI 인코딩 처리를 해줘야 깨지지 않습니다.
        val encodedName = Uri.encode(location.name)
        val uri = Uri.parse("nmap://route/public?dlat=${location.latitude}&dlng=${location.longitude}&dname=$encodedName")
        return Intent(Intent.ACTION_VIEW, uri).apply {
            setPackage("com.nhn.android.nmap")
        }
    }

    private fun kakaoMapIntent(location: PlaceLocation): Intent {
        val uri = Uri.parse("kakaomap://look?p=${location.latitude},${location.longitude}")
        return Intent(Intent.ACTION_VIEW, uri).apply {
            setPackage("net.daum.android.map")
        }
    }

    private fun webMapIntent(location: PlaceLocation): Intent {
        // 실제 운영 시에는 자체 안내 페이지나 각 지도사 fallback 웹 링크를 사용합니다.
        val uri = Uri.parse("https://www.example.com/maps?lat=${location.latitude}&lng=${location.longitude}")
        return Intent(Intent.ACTION_VIEW, uri)
    }

    private fun canOpen(intent: Intent): Boolean {
        return intent.resolveActivity(context.packageManager) != null
    }

    private fun isValidLocation(location: PlaceLocation): Boolean {
        return location.latitude in -90.0..90.0 &&
               location.longitude in -180.0..180.0 &&
               location.name.isNotBlank()
    }

    private fun showMessage(message: String) {
        Toast.makeText(context, message, Toast.LENGTH_SHORT).show()
    }
}

3. 제일 중요: Android 11 이상 AndroidManifest.xml 설정

코드를 아무리 잘 짜도 이 설정을 빼먹으면 Android 11(Target SDK 30) 이상 기기에서는 무조건 웹 지도로만 튕겨 나갑니다. OS 단에서 다른 앱의 패키지 정보를 함부로 조회하지 못하게 막아두었기 때문입니다.

AndroidManifest.xml 파일의 <manifest> 태그 바로 아래에 우리가 연동할 지도 앱들의 패키지명을 명시해 주어야 resolveActivity가 정상적으로 인텐트를 찾아냅니다.

XML
<queries>
    <package android:name="com.google.android.apps.maps" />
    <package android:name="com.nhn.android.nmap" />
    <package android:name="net.daum.android.map" />
</queries>

주의하세요

간혹 귀찮다고 <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" /> 권한을 주는 경우가 있는데, 이렇게 하면 구글 플레이 스토어 심사 거절 사유가 됩니다. 딱 필요한 지도 앱 패키지만 <queries>에 선언하는 것이 가장 깔끔하고 안전합니다.

4. 실무 운영 시 참고할 UX 가이드

각 지도 앱별로 장단점이 뚜렷하기 때문에, 유저 인터페이스를 설계할 때 아래 기준을 참고하시면 좋습니다.

  • 지도 앱 선택 다이얼로그 방식 (추천): 길찾기 버튼을 눌렀을 때 유저가 평소에 자주 쓰는 앱을 고를 수 있게 바텀 시트나 다이얼로그를 띄워주는 게 관광 앱 특성상 반응이 제일 좋습니다. (이후 '기본값으로 기억하기' 옵션을 주면 클릭 동선을 줄일 수 있습니다.)

  • 설치된 앱만 노출하기: 기기를 조회해서 인텐트 실행이 가능한 앱만 다이얼로그 선택지에 노출하면 유저가 미설치 앱을 눌러서 발생하는 피로감을 줄일 수 있습니다.

  • 장소명 인코딩: 카카오나 네이버의 경우 앱 호출 시 뒤에 목적지 텍스트(dname)를 붙일 수 있는데, 띄어쓰기나 특수문자가 포함되면 인텐트가 깨질 수 있으니 꼭 Uri.encode() 처리를 거치셔야 합니다.

5. 최종 배포 전 체크리스트

  • [ ] 지도사별 최신 개발자 문서에서 URI 스킴 형식이 바뀌지 않았는지 확인했는가?

  • [ ] 공통 런처 모듈을 구현하여 장소/축제/숙소 상세 화면에서 동일하게 호출하고 있는가?

  • [ ] 위도·경도 데이터가 null이거나 0.0으로 들어올 때의 예외 처리가 작동하는가?

  • [ ] 외부 앱 호출 실패 시 크래시가 나지 않고 웹 브라우저나 마켓으로 정상 유도되는가?

  • [ ] 코드 내부에 불필요한 운영 서버 하드코딩 주소나 API 키가 남아있지 않은가?

막상 붙여보면 별거 아닌 기능 같아도, 디테일한 예외 처리를 안 해두면 CS가 종종 들어오는 영역입니다. 관광 앱처럼 이동이 잦은 서비스를 빌드할 때는 이런 외부 앱 연동 인터페이스를 초기에 탄탄하게 잡아두는 편이 정신 건강에 이롭습니다. 자꾸 잊어버리시는 분들은 위 코드를 템플릿 삼아 공통 헬퍼로 묶어서 활용해 보시기 바랍니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

안드로이드 화면 꺼짐 방지 FLAG_KEEP_SCREEN_ON 및 WakeLock 적용 방법

이래저래 시험 타이머나 운동 기록, 지도 내비게이션 같은 앱을 개발하다 보면 사용자가 화면을 가만히 쳐다보고 있어야 하는 상황이 자주 생깁니다. 이때 대충 구현하면 스마트폰 설정에라 맞춰진 화면 자동 꺼짐 시간 때문에 화면이 픽 꺼져버려서 사용자가 불편을 겪게 됩니다. 처음에는 그냥 "화면 안 꺼지게 백그라운드에서 계속 돌리면 되겠지" 하고 접근하기 쉬운데, 운영하다 보면 배터리가 광탈하거나 앱을 껐는데도 화면이 계속 켜져 있는 등 온갖 버그성 문제가 터지곤 합니다. 저의 경우도 타이머 앱을 만들 때 화면 유지와 백그라운드 상태 관리를 제대로 분리하지 못해 고생했던 기억이 있습니다. 자꾸 까먹기도 하고 나중에 프로젝트할 때 바로 복사해서 쓰려고 실무 기준으로 핵심만 정리해 둡니다. 헷갈리기 쉬운 핵심 개념: 화면 유지 vs CPU 작업 유지 가장 먼저 확인해야 할 점은 화면만 계속 켜둘 것인가 , 아니면 화면이 꺼져도 내부 CPU 연산(작업)을 계속 돌릴 것인가 를 명확히 구분하는 것입니다. 이걸 혼동하면 안 써도 되는 무거운 권한을 쓰거나 배터리 이슈가 발생합니다. 저의 경우 아래 표를 기준으로 상황에 맞게 기술을 선택해 적용하고 있습니다. 구분 목적 대표 방식 적합한 상황 주의할 점 화면 유지 현재 화면을 계속 보이게 함 FLAG_KEEP_SCREEN_ON 타이머, 영상, 지도 화면 화면을 벗어나면 해제 필수 CPU 작업 유지 화면이 꺼져도 작업 계속 실행 WakeLock , Foreground Service 녹음, 위치 추적, 긴 다운로드 배터리 소모 및 구글 정책 검토 예약/재시도 작업 조건 충족 시 백그라운드 실행 WorkManager 서버 데이터 동기화, 업로드 즉시 실행 보장 안 됨 상태 복구 앱 재진입 시 시간 재계산 저장 시각 + 현재 시각 비교 시험 타이머, 카운트다운 화면 유지와 별개로 설계 필요 단순히 타이머 숫자를 화면에 계속 보여줘야 하는 수준이라면 복잡하게 생각할 것 없이 FLAG_KEEP_SCREEN_ON 하나면...
자세한 내용 보기

안드로이드 백그라운드 타이머 구현 및 Foreground Service 알림 설계 정리

타이머 앱을 만들고 운영하다 보면 백그라운드 처리 때문에 골치 아픈 일이 많습니다. 화면이 켜져 있을 때는 잘 돌다가도, 사용자가 홈 버튼을 누르고 다른 앱을 보거나 화면을 꺼버리면 타이머가 멈추거나 종료 알림이 안 오는 현상이 발생하곤 합니다. 처음에는 무조건 Foreground Service로 다 돌리면 해결될 줄 알았는데, 실제 서비스를 운영해 보니 배터리 소모나 구글 플레이 정책 측면에서 고려할 게 한두 가지가 아니었습니다. 자꾸 까먹어서 나중에도 바로 보고 적용할 수 있도록 실무 기준으로 정리해 둡니다. 백그라운드 타이머 운영 시 자주 겪는 문제 보통 처음 구현할 때 아래와 같은 지점에서 막히거나 실수를 많이 합니다. 화면이 꺼지면 타이머가 같이 멈춰버리는 현상 앱을 백그라운드로 보낸 뒤 타이머 종료 알림이 먹통이 되는 상황 모든 카운트다운을 무조건 Foreground Service로 처리해서 배터리를 낭비하는 구조 상단 알림창에 일시정지, 재개, 종료 같은 제어 버튼이 없는 불편함 알림 채널 중요도를 너무 높여서 사용자에게 과도한 피로감을 주는 경우 PendingIntent 나 로그에 사용자 ID나 민감한 데이터를 그대로 남기는 보안 실수 백그라운드 타이머를 작업할 때는 "코드를 백그라운드에서 계속 실행한다"가 아니라, "사용자가 인지할 수 있는 지속된 작업과 종료 알림을 조합한다"로 접근하는 것이 운영상 훨씬 안전합니다. 핵심 개념: 계산은 상태로, 표시는 알림으로 분리 타이머의 남은 시간은 매초 줄어드는 루프 코드가 아니라, 시작 기준 시각과 현재 시각의 차이 로 계산하는 것이 정석입니다. Foreground Service는 시간을 계산하는 주체가 아니라, 백그라운드에서도 사용자에게 "타이머가 돌고 있다"는 것을 보여주고 제어할 수 있게 돕는 창구일 뿐입니다. 저의 경우 아래와 같이 역할을 나누어 구조를 잡았습니다. 구성 요소 역할 주의할 점 TimerSession 시작 시각, 전체 시간, 일...
자세한 내용 보기

관광 앱 다국어 데이터 모델 및 검색 색인 설계 (자꾸 까먹어서 정리)

관광 앱을 개발하거나 서비스를 운영하다 보면 외국인 여행자를 위해 다국어를 지원해야 하는 일이 꼭 생깁니다. 처음에는 단순히 앱 내 UI 문자열( strings.xml )만 번역하면 끝날 줄 알았는데, 실제 서비스를 돌려보니 장소명이나 지역명 같은 콘텐츠 데이터 처리 가 진짜 번역의 핵심이더군요. 특히 공공데이터를 가져와서 쓰다 보면 한국어만 달랑 있거나, 영문 표기 방식이 데이터 소스마다 제각각이라 데이터가 다 깨집니다. 저의 경우도 "제주시", "Jeju-si", "Jeju City"가 마구 뒤섞여서 검색도 안 되고 화면도 깨지는 삽질을 좀 했습니다. 나중에 또 같은 문제로 고생하지 않으려고 표시 이름, 내부 지역 코드 표준화, Fallback 처리, 그리고 검색 색인 구조까지 실무에서 바로 쓸 수 있게 정리해 둡니다. 1. 기본 개념: 표시 이름과 원본 이름 분리하기 공공데이터에서 가져온 원본 이름을 그대로 덮어써 버리면, 나중에 번역 데이터가 바뀌거나 원본 데이터가 업데이트될 때 매칭할 기준이 사라집니다. 원본 이름은 그대로 보존하고, UI 표시용과 로마자 표기를 별도로 분리해서 관리 해야 유지보수가 쉬워집니다. 항목 예시 용도 원본 이름 성산일출봉 공공데이터 원본 데이터 보존 (비교용) 한국어 표시명 성산일출봉 한국어 UI 표시 영어 표시명 Seongsan Ilchulbong 영어 UI 표시 로마자 표기 Seongsan Ilchulbong 외국어 검색 보조용 검색 키워드 sunrise peak, seongsan 검색 색인 확장용 출처명 공공데이터 제공 기관명 저작권 및 출처 표시 요구사항 대응 2. 데이터 모델 설계 예시 (Kotlin) 저의 경우, 이 문제를 해결하기 위해 아래처럼 장소 기본 정보와 번역 맵( Map<AppLanguage, String> )을 분리한 데이터 모델을 사용합니다. 외부 노출을 막기 위해 실제 API URL이나 내부 코드는 더미 값으로 대체한 구조입니다. Ko...
자세한 내용 보기