이전 Google Maps Mobile SDK for Work Android

이전 Google Maps APIs for Work 또는 Google Maps API for Business 라이선스를 보유한 고객은 Google Maps Mobile SDK for Work의 일부분으로 Google Maps Android API를 구매합니다. 이 문서 섹션에서는 해당 SDK의 설정에 대해 설명합니다.

이 페이지는 이전 Maps APIs for Work 또는 Maps API for Business 라이선스가 있는 고객만을 위한 것입니다. 이 페이지는 2016년 1월에 출시된 새 Google Maps API 프리미엄 플랜가 있는 고객에게는 적용되지 않습니다.

개요

이 페이지의 지시에 따라 SDK를 다운로드하고, 프로젝트를 설정하고, 지도를 추가합니다. 다음은 필요한 단계를 요약한 내용입니다.

  1. SDK를 다운로드합니다.
  2. SDK를 기존 Android 프로젝트나 새 프로젝트에 추가합니다.
  3. API 키를 앱 매니페스트에 추가합니다.
  4. 필요한 Android 권한과 OpenGL ES 버전 2를 지정합니다.
  5. 지도를 추가합니다.

SDK 다운로드

SDK를 정적 라이브러리로서 다운로드하거나 Android SDK Manager를 사용할 수 있습니다.

옵션 1: SDK를 정적 라이브러리로 다운로드

최신 릴리스를 정적 라이브러리로 다운로드합니다.

옵션 2: Android SDK Manager를 사용하여 SDK 다운로드

Android Studio에서:

  1. Tools > Android > SDK Manager를 선택합니다.
  2. Appearance & Behavior > System Settings > Android SDK를 선택합니다.
  3. SDK Update Sites 탭을 클릭합니다.
  4. plus (+) 아이콘을 클릭하여 새 사이트를 추가합니다.
  5. 이름(예: 'Google Maps APIs')과 URL(예: https://dl.google.com/geosdk/android-m4b-addon.xml을 입력합니다.
  6. OK를 클릭합니다.
  7. SDK Tools 탭을 클릭합니다.
  8. Google Maps Mobile SDK for Work를 선택하고 OK를 클릭하여 다운로드를 완료합니다.

Android Studio가 <android-sdk-folder>/extras/google/maps_for_business_sdk/에 라이브러리를 설치합니다.

Android SDK Manager를 독립 실행형 도구로 사용하는 방법에 대한 설명은 Android SDK Manager 가이드를 참조하세요.

프로젝트에 SDK 추가

다음은 Android Studio 관련 설명입니다. 다른 도구를 사용 중인 경우에는 Android 문서에서 명령줄 사용에 대한 설명을 참조하세요.

Google Maps Mobile SDK for Work의 Google Maps Android API는 두 가지 형식으로 제공합니다. aar 번들(google-maps-sdk-m4b.aar) 및 라이브러리 모듈 (google-maps-sdk-m4b_lib). 가장 적합한 형식을 선택할 수 있습니다.

옵션 1: aar 번들에서 SDK 가져오기

다음 단계에 따라 aar 번들(google-maps-sdk-m4b.aar)을 Android Studio 프로젝트에 포함시킵니다.

  1. 다음 위치의 Google Maps Mobile SDK for Work로 이동합니다:

    <android-sdk>/extras/google/maps_for_business_sdk

  2. Copy the google-maps-sdk-m4b.aar file into the libs directory in your project. (Create the directory if it doesn't exist.)

  3. Add the following code in your build.gradle file:

    dependencies {
        compile(name:'google-maps-sdk-m4b', ext:'aar')
    
    }
    
    repositories {
        flatDir{
            dirs 'libs'
        }
    }
    
  4. Complete the configuration steps as described below.

Option 2: Import the SDK as a library module

Instead of using the aar file, you can follow these steps to add the SDK library module (google-maps-sdk-m4b_lib) to an existing project in Android Studio:

  1. In Android Studio, choose the option to import a new module (File -> New -> Import Module).
  2. 다음 위치의 SDK로 이동합니다:

    <android-sdk>/extras/google/maps_for_business_sdk

  3. google-maps-sdk-m4b_lib 디렉토리를 선택하고 Choose를 클릭합니다.

  4. 가져오기 마법사에서 기본값을 수락합니다.
  5. Finish를 클릭합니다. 가져오기 절차의 결과를 요약한 텍스트 파일이 나타납니다.
  6. 라이브러리가 settings.gradle 파일에 포함되었는지 확인합니다.

    include ':googlemapssdkm4b_lib'

  7. 앱의 build.gradle 파일에 모듈 종속성을 추가합니다.

    compile project(':googlemapssdkm4b_lib')

Google Play 서비스를 사용하는 기존 구성을 전환

  1. Google Play 서비스를 사용하는 기존 앱이 있는 경우, com.google.android.gms.maps 패키지에 대한 모든 참조를 com.google.android.m4b.maps로 대체합니다.
  2. XML 레이아웃 특성에 대한 모든 참조에 m4b_ 접두사를 붙입니다. 예: m4b_mapTypem4b_cameraZoom.

API 키 가져와서 앱에 추가

아래 설명과 같이 프로젝트에 대해 API 키를 생성하고 이 키를 AndroidManifest.xml에 추가합니다. Android 제한 API 키를 설정해야 합니다.

API 키는Google Maps Mobile SDK for Work 고객을 식별하고 애플리케이션에 대한 지원 및 구입한 할당량을 활성화합니다. 애플리케이션 패키지 이름과 디지털 인증서를 조합하여 Google Maps Mobile SDK 서비스를 활성화한 계정에서 API 키를 생성할 수 있습니다.

API 키는 짧은 형식의 앱 디지털 인증서를 기반으로 합니다. 모든 Android 앱은 비공개 키를 보유한 디지털 인증서로 서명됩니다. (디지털 인증서에 대한 자세한 내용은 Android 가이드의 애플리케이션 서명을 참조하세요.)

앱의 인증서 정보 표시

Android API 키 제한은 SHA-1 지문으로 알려진 짧은 형식의 앱 디지털 인증서를 기반으로 합니다.

Android Studio에서 인증 정보 가져오기

Google Maps Android API 시작 가이드를 따를 경우, Android Studio는 여러분의 앱 자격 증명으로 간단한 google_maps_api.xml 파일을 생성합니다.

다음 중 하나를 선택하여 Android Studio에서 API 키를 가져옵니다.

  • 빠르고 쉬운 방법: Android Studio가 생성한 google_maps_api.xml 파일에 있는 링크를 사용합니다.
    1. google_maps_api.xml 파일에 있는 링크를 복사하여 브라우저에 붙여넣습니다. 링크를 누르면 Google API Console로 이동하고, URL 매개변수를 통해 필수 정보를 Google API Console에 제공하므로, 개발자가 수동으로 입력해야 하는 항목이 줄어듭니다.
    2. 지침에 따라 Google API Console에서 새 프로젝트를 생성하거나 기존 프로젝트를 선택합니다.
    3. 프로젝트의 Android 제한 API 키를 생성합니다.
    4. 생성된 API 키를 복사하고 Android Studio로 돌아간 다음, google_maps_api.xml 파일의 <string> 요소에 API 키를 붙여넣습니다.
  • 약간 덜 빠른 방법: Android Studio가 생성한 google_maps_api.xml 파일에 있는 자격 증명을 사용합니다.
    1. google_maps_api.xml 파일에서 제공하는 자격 증명을 복사합니다.
    2. 브라우저에서 Google API Console로 이동합니다.
    3. 복사한 자격 증명을 사용하여 기존 API 키에 앱을 추가하거나 새 API 키를 생성합니다.

직접 인증서 정보 가져오기

앱을 생성할 때 시작 가이드를 따르지 않았다면, 직접 인증서의 SHA-1 지문을 가져와야 합니다. 먼저 유효한 인증서를 사용 중인지 확인합니다. 2개의 인증서를 가질 수 있습니다.

  • 디버그 인증서: Android SDK 도구는 디버그 빌드 수행 시 이 인증서를 자동으로 생성합니다. 이 인증서는 테스트 중인 앱에서만 사용합니다. 디버그 인증서로 서명된 앱은 게시하지 마십시오. 디버그 인증서는 Android 개발자 문서의 디버그 모드에서 서명에 더 자세히 설명되어 있습니다.
  • 릴리스 인증서: Android SDK 도구는 릴리스 빌드 수행 시 이 인증서를 자동으로 생성합니다. keytool 프로그램을 사용하여 이 인증서를 생성할 수도 있습니다. 전세계에 앱 출시를 준비할 때 이 인증서를 사용합니다.

아래 단계에 따라 keytool 프로그램을 -v 매개변수와 함께 사용하여 인증서의 SHA-1 지문을 표시합니다. Keytool에 대한 자세한 내용은 Oracle 문서를 참조하세요.

디버그 인증서

디버그 인증서 지문 표시

  1. 디버그 키스토어 파일을 찾습니다. 파일 이름은 debug.keystore이고 처음 프로젝트를 빌드할 때 생성됩니다. 기본적으로 Android Virtual Device (AVD) 파일과 동일한 디렉토리에 저장됩니다.

    • macOS 및 Linux: ~/.android/
    • Windows Vista 및 Windows 7: C:\Users\your_user_name\.android\
  2. SHA-1 지문 표시:

    • Linux 또는 macOS의 경우, 터미널 창을 열고 다음을 입력합니다.

      keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    • Windows Vista 및 Windows 7의 경우 다음을 실행합니다.

      keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

다음과 유사하게 출력되어야 합니다.

Alias name: androiddebugkey
Creation date: Jan 01, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4aa9b300
Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033
Certificate fingerprints:
     MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9
     SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75
     Signature algorithm name: SHA1withRSA
     Version: 3
릴리스 인증서

릴리스 인증서 지문 표시

  1. 릴리스 인증서 키스토어 파일을 찾습니다. 릴리스 키스토어의 기본 위치 또는 이름이 없습니다. 릴리스용 앱을 빌드할 때 이를 지정하지 않으면, 빌드에서 .apk를 서명되지 않은 상태로 두며, 여기에 먼저 서명해야만 게시할 수 있습니다. 릴리스 인증서의 경우, 인증서의 별칭과 키스토어 및 인증서의 암호도 필요합니다. 다음을 입력하여 모든 키에 대해 별칭을 표시할 수 있습니다.

    keytool -list -keystore your_keystore_name

    your_keystore_name.keystore 확장명을 포함한 키스토어의 전체 경로 및 이름으로 대체합니다. 키스토어의 암호를 입력하라는 메시지가 나타납니다. 이어서 keytool이 키스토어의 모든 별칭을 표시합니다.

  2. 터미널이나 명령 프롬프트에서 다음을 입력합니다.

    keytool -list -v -keystore your_keystore_name -alias your_alias_name

    your_keystore_name.keystore 확장명을 포함한 키스토어의 전체 경로 및 이름으로 대체합니다. your_alias_name을 인증서를 생성할 때 할당한 별칭으로 대체합니다.

다음과 유사하게 출력되어야 합니다.

Alias name: <alias_name>
Creation date: Feb 02, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4cc9b300
Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033
Certificate fingerprints:
    MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9
    SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75
    Signature algorithm name: SHA1withRSA
    Version: 3

SHA1로 시작하는 줄은 인증서의 SHA-1 지문을 포함합니다. 지문은 콜론으로 구분된 20개의 두 자리 16진수 시퀀스입니다.

디지털 인증서에 대한 자세한 내용은 Android 가이드의 애플리케이션 서명을 참조하세요.

계정에서

Google Maps Mobile SDK 서비스가 활성화되었는지 확인

Google Maps Mobile SDK for Work에 가입하면 Google Cloud Support 팀이 Google Maps Mobile SDK서비스를 활성화합니다. 서비스는 새 프로젝트에 대해 활성화됩니다. Google API Console에서 API 키를 획득할 수 있습니다.

참고: 프로젝트의 최초 소유자에게만 Google Maps Mobile SDK 서비스가 표시됩니다. 추가 프로젝트 소유자에 대해 승인을 요청하려면 Google Cloud Support Portal에 기술 외 케이스를 제출하세요.

다음과 같이 계정이 활성화되었는지 확인합니다.

  1. Google API Console을 방문하여 Google 계정으로 로그인합니다.
  2. Google Maps Mobile SDK for Work를 주문했을 때 생성된 Google Maps Mobile SDK for Work 프로젝트를 선택합니다 . 프로젝트 이름은 Google Maps APIs for Business 또는 Google Maps for Work 또는 Google Maps로 시작합니다. SDK 액세스 권한을 아직 구매하지 않은 경우 [판매부]에 문의하세요.
  3. DashboardAPIs 목록에서 Google Maps Mobile SDK이 활성화되었는지 확인합니다.

Google API Console에서 API 키 가져오기

프로젝트에서 Google Maps Mobile SDK for Work 서비스를 활성화한 후 새 키를 생성해야 합니다.

  1. Google API Console 자격 증명 페이지를 방문하여 Google 계정으로 로그인합니다.

  2. Google Maps Mobile SDK for Work를 주문했을 때 생성된 Google Maps Mobile SDK for Work 프로젝트를 선택합니다 . 프로젝트 이름은 Google Maps APIs for Business 또는 Google Maps for Work 또는 Google Maps로 시작합니다. SDK 액세스 권한을 아직 구매하지 않은 경우 [판매부]에 문의하세요.
  3. API keys 목록에서 Android 제한이 포함된 키를 찾습니다.
  4. 프로젝트에 Android 제한 API 키가 없다면 Create credentials > API key를 선택하여 지금 API 키를 생성합니다.
  5. 결과 대화상자에서 Restrict key를 선택합니다.
  6. Restrictions 섹션에서 Android apps를 선택한 다음, 앱의 SHA-1 지문과 패키지 이름을 입력합니다. 예:

    BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
    com.example.android.mapexample
    
  7. Save를 클릭합니다.

    프로젝트의 API 키 목록에 새 Android 제한 API 키가 나타납니다. API 키는 다음과 같은 문자열입니다.

    AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
    

애플리케이션에 API 키 추가

아래 절차에 따라 AndroidManifest.xml 파일에 들어 있는 애플리케이션의 매니페스트에 API 키를 포함합니다.

  1. AndroidManifest.xml에서 </application> 태그를 닫기 직전에 다음 요소를 삽입하여 <application> 요소의 하위 요소로 추가합니다.
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="YOUR_API_KEY"/>
        

    value 특성에서 API 키를 YOUR_API_KEY로 교체합니다. 이 요소는 com.google.android.geo.API_KEY 키를 API 키 값으로 설정합니다.

  2. AndroidManifest.xml을 저장하고 애플리케이션을 다시 빌드합니다.

참고: 위에서 본 바와 같이 com.google.android.geo.API_KEY는 API 키의 권장 메타데이터 이름입니다. 이 이름을 가진 키는 Android 플랫폼에서 Google Maps Android API를 비롯한 여러 가지 Google Maps 기반 API를 인증하는 데 사용할 수 있습니다. 이전 버전과의 호환성을 위해 이 API는 com.google.android.maps.v2.API_KEY 이름도 지원합니다. 이 레거시 이름은 Android Maps API v2만 인증할 수 있습니다. 애플리케이션은 API 키 메타데이터 이름 중에 하나만 지정할 수 있습니다. 두 개 모두 지정되면 API가 예외를 발생시킵니다.

앱 권한 지정

AndroidManifest.xml에서 <uses-permission> 요소를 <manifest>의 하위 요소로 추가하여 애플리케이션에 필요한 권한을 지정합니다.

위치 권한

애플리케이션이 My Location 계층을 활성화하여 사용자의 현재 위치에 액세스하면 위치 데이터 가이드에 설명된 위치 권한을 요청해야 합니다.

외부 저장소 권한:

Google Play 서비스 SDK 버전 8.3 이상이 대상이라면, 이제 Google Maps Android API를 사용하기 위해 WRITE_EXTERNAL_STORAGE 권한이 필요 없습니다.

Google Play 서비스 SDK의 이전 버전이 대상이라면, android.permission.WRITE_EXTERNAL_STORAGE 권한을 요청해야 합니다.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

참고: 앱이 API 레벨 23(Android 6.0)을 대상으로 하면 런타임 권한을 사용하므로, Google Play 서비스 SDK 버전 8.3 이상을 대상으로 해야 합니다.

권한은 매니페스트에 자동으로 병합됩니다.

다음 권한은 Google Play 서비스에 정의되어 있고 빌드 시 앱 매니페스트에 자동으로 병합됩니다. 매니페스트에 이 권한을 명시적으로 추가할 필요가 없습니다.

OpenGL ES 버전 2 지정

Google Maps Android API는 OpenGL ES 버전 2를 사용하여 지도를 렌더링합니다. 다음 설정은 Google Play 서비스에 정의되어 있고 빌드 시 앱 매니페스트에 자동으로 병합됩니다. 매니페스트에 이 설정을 명시적으로 추가할 필요가 없습니다.

<uses-feature
        android:glEsVersion="0x00020000"
        android:required="true"/>

이는 외부 서비스에게 요구사항을 알려줍니다. 특히, Google Play 스토어가 OpenGL ES 버전 2를 지원하지 않는 기기에 앱을 표시하지 못하게 합니다.

지도 추가

앱이 올바로 구성되었는지 테스트하는 가장 쉬운 방법은 간단한 지도를 추가하는 것입니다.

참고: 이 코드는 프로덕션 앱에는 사용하면 안됩니다.

  1. activity_main.xml에서 다음 프래그먼트를 추가합니다.

    <?xml version="1.0" encoding="utf-8"?>
    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
              android:id="@+id/map"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              android:name="com.google.android.m4b.maps.MapFragment"/>
    
  2. MainActivity.java에서 다음 코드를 추가합니다.

    package com.example.mapdemo;
    
    import android.app.Activity;
    import android.os.Bundle;
    
    public class MainActivity extends Activity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
        }
    }
    

앱 빌드 및 실행

앱을 빌드하고 실행합니다. 지도가 나타납니다.

문제 해결:

  • 지도가 나타나지 않으면, 이 문서 앞부분에 있는 모든 단계를 완료했는지 확인하세요. 특히, API 키가 올바른지 확인하고 Google Maps Mobile SDK for Work 서비스를 위해 계정이 활성화되었는지 확인하세요.

  • 프로젝트에서 메서드 수가 한도를 넘으면, 다음 오류가 발생할 수도 있습니다.

    Unable to execute dex: method ID not in [0, 0xffff]: 65536

    원인 및 해결책에 대한 자세한 내용은 65K 이상의 메서드를 사용하여 앱 빌드 Android 개발자 가이드를 참조하세요.

  • 프로젝트가 이미 Guava에 종속된 경우에는 다음과 같은 클래스 충돌 오류가 발생할 수도 있습니다.

    com.android.dex.DexException: Multiple dex files define Lcom/google/common/annotations/Beta

    이 문제를 해결하려면, google-maps-sdk-m4b_lib/libs 디렉토리에서 Guava 복사본을 삭제하면 됩니다.

추가 정보

기존 앱의 마이그레이션 방법

Google Maps Mobile SDK for Work에서 사용 가능한 Android API는 표준 Google Maps Android API와 매우 유사하게 디자인되었습니다. 따라서 마이그레이션 절차도 아주 간단합니다.

  1. Google Maps Mobile SDK for Work용 Google Maps Android API를 다운로드하고 SDK를 프로젝트에 추가합니다(위 설명 참조).
  2. com.google.android.gms.maps 패키지에 대한 모든 참조를 com.google.android.m4b.maps로 대체합니다.
  3. XML 레이아웃 특성에 대한 모든 참조에 m4b_ 접두사를 붙입니다. 예: m4b_mapTypem4b_cameraZoom.
  4. 프로젝트에 대해 새 API 키를 생성하고 이 키를 AndroidManifest.xml에 추가합니다(인증 가이드의 설명 참조).
  5. 앱을 빌드합니다.

버전 비교

다음 표에서는 표준 Google Maps Android API 사용 시와 Google Maps Mobile SDK for Work를 포함한 API 사용 시의 주요 차이점에 대해 설명합니다.

  표준 Google Maps Android API Google Maps Mobile SDK for Work
패키지 이름 com.google.android.gms.maps com.google.android.m4b.maps
레이아웃 파일의 XML 특성 접두사가 없는 특성 이름을 사용합니다. 예: mapType. 모든 특성 이름에 m4b_ 접두사를 붙입니다. 예: m4b_mapType. 자세한 내용은 XML 특성에 관한 문서를 참조하세요.
다운로드 위치 Google Play 서비스에 포함됩니다. 정적 라이브러리로 사용 가능.
지원 채널 커뮤니티 기반 지원 프리미엄 지원에 액세스
약관 Google Maps APIs 서비스 약관을 따릅니다. Google Maps Mobile SDK for Work 약관이 적용됩니다.

Google Play 서비스

표준 Google Maps Android API는 Google Play 서비스 APK 및 Google Play 서비스 클라이언트 라이브러리가 모두 필요합니다. 그러나 Google Maps Mobile SDK for Work와 사용할 경우 SDK는 Google Play 서비스 APK만 대상 기기에 설치하도록 요구하며, 클라이언트 라이브러리는 설치할 필요가 없습니다.

애플리케이션을 Google Maps Mobile SDK for Work로 마이그레이션할 때, Google Play 서비스 SDK를 프로젝트에서 제거할 필요가 없습니다. 그러나 com.google.android.gms.maps 패키지에 대한 모든 참조는 제거해야 합니다. Google Play 서비스에는 Google Maps Android APIAPI 버전 뿐만 아니라 기타 Google 서비스도 포함되어 있습니다. 여러분의 앱 내에서 다른 Google API를 사용하기 위해 Google Play 서비스를 사용하는 경우, SDK Google Maps Mobile SDK for Work SDK( com.google.android.m4b.maps 패키지)만 사용하여 지도에 액세스하세요.

Google Play 서비스 클라이언트 라이브러리는 필수는 아니지만, 이 라이브러리를 포함시키면 Google+ 또는 Location API와 같은 다른 Google API를 활용할 수 있으므로 유용한 라이브러리입니다.

샘플 코드

Github의 Google Maps 리포지토리에는 Android 앱에서 Google Maps Android API를 사용하는 방법을 보여주는 여러 가지 샘플이 포함되어 있습니다. 참고로, 이 샘플 앱에서는 com.google.android.gms.maps 패키지를 사용합니다(Google Maps Mobile SDK for Work에서 사용되는 com.google.android.m4b.maps 대신). 데모의 일부분에 Location API가 사용되기 때문에, 이 샘플 앱에는 또한 Google Play 서비스 SDK가 필요합니다.

또한, 개발자 가이드의 각 페이지에서 코드 스니펫을 찾을 수 있습니다.

문서

Google Maps Mobile SDK for Work에 대한 자세한 내용은 이 사이트에서 제공하는 개발자 및 참조 문서를 참조하세요.