빠른 시작: Azure Maps를 사용하여 Android 앱 만들기

아티클
03/18/2024

이 문서에서는 Android 앱에 Azure Maps를 추가하는 방법을 보여줍니다. 여기서는 다음 기본 단계를 단계별로 안내합니다.

개발 환경 설정
사용자 고유의 Azure Maps 계정을 만듭니다.
앱에서 사용할 기본 Azure Maps 키를 가져옵니다.
프로젝트에서 Azure Maps 라이브러리를 참조합니다.
앱에 Azure Maps 컨트롤을 추가합니다.

참고 항목

Azure Maps Android SDK 사용 중지

이제 Android용 Azure Maps 네이티브 SDK는 더 이상 사용되지 않으며 2025년 3월 31일에 사용 중지됩니다. 서비스 중단을 방지하려면 2025년 3월 31일까지 Azure Maps 웹 SDK로 마이그레이션합니다. 자세한 내용은 Azure Maps Android SDK 마이그레이션 가이드를 참조하세요.

필수 조건

Microsoft Azure 구독. Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.
Android Studio. Android Studio가 없는 경우 Google에서 무료로 다운로드할 수 있습니다.

참고 항목

이 빠른 시작의 많은 지침은 Android Studio Arctic Fox(2020.3.1)를 사용하여 만들어졌습니다. 다른 버전의 Android Studio를 사용하는 경우 Android Studio와 관련된 단계는 다를 수 있습니다.

Azure Maps 계정 만들기

다음 단계에 따라 새 Azure Maps 계정을 만듭니다.

Azure Portal의 왼쪽 위 모서리에서 리소스 만들기를 선택합니다.
Marketplace 검색 상자에 Azure Maps를 입력한 다음 검색 결과에서 Azure Maps를 선택합니다.
생성 단추를 선택합니다.
Maps 계정 만들기 페이지에서 다음 값을 입력합니다.
- 이 계정에 사용하려는 구독.
- 이 계정에 대한 리소스 그룹 이름. 새로 만들기 또는 기존 리소스 그룹 사용을 선택할 수도 있습니다.
- 새 계정의 이름.
- 이 계정에 대한 가격 책정 계층입니다. Gen2를 선택합니다.
- 사용 약관을 읽고 확인란을 선택하여 라이선스 및 개인정보처리방침을 읽고 동의했음을 확인합니다.
- 검토 + 만들기 단추를 선택합니다.
- 검토 + 만들기 페이지에서 모든 것이 올바른지 확인했으면 만들기 단추를 선택합니다.

계정에 대한 구독 키 가져오기

Azure Maps 계정이 성공적으로 만들어지면 Maps API를 쿼리할 수 있는 구독 키를 검색합니다.

포털에서 Azure Maps 계정을 엽니다.
왼쪽 창에서 인증을 선택합니다.
기본 키를 복사하고 로컬로 저장하여 이 자습서의 뒷부분에서 사용합니다.

참고 항목

보안을 위해 기본 키와 보조 키 사이를 회전하는 것이 좋습니다. 키를 회전하려면 보조 키를 사용하도록 앱을 업데이트하고 배포한 다음, 기본 키 옆에 있는 주기/새로 고침 단추를 눌러 새 기본 키를 생성합니다. 이전 기본 키는 사용할 수 없습니다. 키 회전에 대한 자세한 내용은 키 회전 및 감사를 사용하여 Azure Key Vault 설정을 참조하세요.

Android Studio에서 프로젝트 만들기

다음 단계를 완료하여 Android Studio에서 빈 작업을 사용하여 새 프로젝트를 만듭니다.

Android Studio를 시작하고 파일 메뉴에서 새로 만들기를 선택한 다음 새 프로젝트 만들기를 선택합니다.
새 프로젝트 화면에서 왼쪽의 템플릿 목록에서 전화 및 태블릿을 선택합니다.
템플릿 목록에서 빈 작업을 선택한 다음, 다음을 선택합니다.
빈 작업 화면에서 다음 필드에 대한 값을 입력합니다.
- Name(이름): AzureMapsApp을 입력합니다.
- 패키지 이름. 기본값 com.example.azuremapsapp을 사용합니다.
- 저장 위치. 기본값을 사용하거나 새 위치를 선택하여 프로젝트 파일을 저장합니다. NDK 도구의 잠재적인 문제로 인해 경로 또는 파일 이름에 공백을 사용하지 마세요.
- 언어. Kotlin 또는 Java를 선택합니다.
- 최소 SDK. API 21: Android 5.0.0 (Lollipop)을(를) 최소 SDK로 선택합니다. Azure Maps Android SDK에서 지원하는 가장 빠른 버전입니다.
마침을 선택하여 프로젝트를 만듭니다.

Android Studio를 설치하고 새 프로젝트를 만드는 방법에 대한 자세한 도움말은 Android Studio 문서를 참조하세요.

가상 디바이스 설정

Android Studio를 사용하면 컴퓨터에 가상 Android 디바이스를 설정할 수 있습니다. 이렇게 하면 개발 중에 애플리케이션을 테스트하는 데 도움이 됩니다.

AVD(Android 가상 디바이스)를 설정하려면 다음을 실행합니다.

도구 메뉴에서 AVD 관리자를 선택합니다.
Android 가상 디바이스 관리자가 표시됩니다. 가상 디바이스 만들기를 선택합니다.
휴대폰 범주에서 Nexus 5X를 선택한 후 다음을 선택합니다.

AVD 설정에 대한 자세한 내용은 Android Studio 설명서에서 가상 디바이스 만들기 및 관리를 참조하세요.

새 가상 디바이스를 만들 때 Android 가상 디바이스 관리자의 하드웨어 선택 화면을 보여 주는 스크린샷

Azure Maps Android SDK 설치

애플리케이션을 빌드하는 다음 단계에서 Azure Maps Android SDK를 설치합니다. SDK를 설치하려면 다음 단계를 완료합니다.

프로젝트 설정 파일 settings.gradle을 열고 리포지토리 섹션에 다음 코드를 추가합니다.
```
maven {url "https://atlas.microsoft.com/sdk/android"}
```
동일한 프로젝트 설정 파일 settings.gradle에서 repositoriesMode를 PREFER_SETTINGS(으)로 변경합니다.
```
repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
```
이제 프로젝트 설정 파일이 다음과 같이 표시됩니다.
프로젝트의 gradle.properties 파일을 열고 android.useAndroidX 및 android.enableJetifier가 모두 true로 설정되어 있는지 확인합니다.

gradle.properties 파일에 android.useAndroidX 및 android.enableJetifier가 포함되어 있지 않으면 다음 두 줄을 파일 끝에 추가합니다.
```
android.useAndroidX=true
android.enableJetifier=true
```
애플리케이션 build.gradle 파일을 열고 다음을 수행합니다.
1. 프로젝트의 minSdk가 21 이상인지 확인합니다.
2. Android 섹션의 compileOptions이(가) 다음과 같은지 확인합니다.
```
compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}
```
3. 다음과 같이 종속성 블록을 업데이트하고 최신 Azure Maps Android SDK에 대한 새 구현 종속성을 추가합니다.
```
implementation 'com.azure.android:azure-maps-control:1.+'
```
4. 파일 메뉴에서 Gradle 파일로 Project 동기화를 선택합니다.
다음과 같이 기본 작업에 맵 조각을 추가합니다.
```
<com.azure.android.maps.control.MapControl
    android:id="@+id/mapcontrol"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />
```
주 작업을 업데이트하려면 프로젝트 탐색기에서 앱 > res > 레이아웃 >activity_main.xml을 선택합니다.

MainActivity.java 파일에서:

Azure Maps SDK에 대한 가져오기를 추가합니다.
Azure Maps 인증 정보를 설정합니다.
onCreate 메서드에서 지도 컨트롤 인스턴스 가져옵니다.

팁

setSubscriptionKey 또는 setAadProperties 메서드를 사용하여 AzureMaps 클래스에서 인증 정보를 전역적으로 설정하면 모든 보기에서 인증 정보를 추가할 필요가 없습니다.

지도 컨트롤에는 Android의 OpenGL 수명 주기를 관리하는 자체 수명 주기 메서드가 포함되어 있습니다. 이러한 수명 주기 메서드는 포함된 작업에서 직접 호출해야 합니다. 지도 컨트롤의 수명 주기 메서드를 올바르게 호출하려면 지도 컨트롤을 포함하는 작업에서 다음 수명 주기 메서드를 재정의한 다음, 각 지도 컨트롤 메서드를 호출합니다.

onCreate(Bundle)
onDestroy()
onLowMemory()
onPause()
onResume()
onSaveInstanceState(Bundle)
onStart()
onStop()

MainActivity.java 파일을 다음과 같이 편집합니다.

package com.example.azuremapsapp;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import com.azure.android.maps.control.AzureMaps;
import com.azure.android.maps.control.MapControl;
import com.azure.android.maps.control.layer.SymbolLayer;
import com.azure.android.maps.control.options.MapStyle;
import com.azure.android.maps.control.source.DataSource;

public class MainActivity extends AppCompatActivity {

static {
    AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>");

    //Alternatively use Azure Active Directory authenticate.
    //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>");
}

MapControl mapControl;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mapControl = findViewById(R.id.mapcontrol);

    mapControl.onCreate(savedInstanceState);

    //Wait until the map resources are ready.
    mapControl.onReady(map -> {

        //Add your post map load code here.

    });
}

@Override
public void onResume() {
    super.onResume();
    mapControl.onResume();
}

@Override
protected void onStart(){
    super.onStart();
    mapControl.onStart();
}

@Override
public void onPause() {
    super.onPause();
    mapControl.onPause();
}

@Override
public void onStop() {
    super.onStop();
    mapControl.onStop();
}

@Override
public void onLowMemory() {
    super.onLowMemory();
    mapControl.onLowMemory();
}

@Override
protected void onDestroy() {
    super.onDestroy();
    mapControl.onDestroy();
}

@Override
protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);
    mapControl.onSaveInstanceState(outState);
}}

MainActivity.kt 파일에서:

Azure Maps SDK에 대한 가져오기 추가
Azure Maps 인증 정보 설정
onCreate 메서드에서 지도 컨트롤 인스턴스 가져오기

팁

지도 컨트롤에는 Android의 OpenGL 수명 주기를 관리하는 자체 수명 주기 메서드가 포함되어 있습니다. 이러한 수명 주기 메서드는 포함된 작업에서 직접 호출해야 합니다. 지도 컨트롤의 수명 주기 메서드를 올바르게 호출하려면 지도 컨트롤이 포함된 작업에서 다음 수명 주기 메서드를 재정의합니다. 그리고 각 지도 컨트롤 메서드를 호출해야 합니다.

onCreate(Bundle)
onDestroy()
onLowMemory()
onPause()
onResume()
onSaveInstanceState(Bundle)
onStart()
onStop()

MainActivity.kt 파일을 다음과 같이 편집합니다.

package com.example.azuremapsapp;

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import com.azure.android.maps.control.AzureMap
import com.azure.android.maps.control.AzureMaps
import com.azure.android.maps.control.MapControl
import com.azure.android.maps.control.events.OnReady

class MainActivity : AppCompatActivity() {

    companion object {
        init {
            AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>");

            //Alternatively use Azure Active Directory authenticate.
            //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>");
        }
    }

    var mapControl: MapControl? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        mapControl = findViewById(R.id.mapcontrol)

        mapControl?.onCreate(savedInstanceState)

        //Wait until the map resources are ready.
        mapControl?.onReady(OnReady { map: AzureMap -> })
    }

    public override fun onStart() {
        super.onStart()
        mapControl?.onStart()
    }

    public override fun onResume() {
        super.onResume()
        mapControl?.onResume()
    }

    public override fun onPause() {
        mapControl?.onPause()
        super.onPause()
    }

    public override fun onStop() {
        mapControl?.onStop()
        super.onStop()
    }

    override fun onLowMemory() {
        mapControl?.onLowMemory()
        super.onLowMemory()
    }

    override fun onDestroy() {
        mapControl?.onDestroy()
        super.onDestroy()
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        mapControl?.onSaveInstanceState(outState)
    }
}

다음 이미지에 표시된 대로 도구 모음에서 실행 단추를 선택하여(또는 Mac에서는 Control + R을 누름) 애플리케이션을 빌드합니다.

Android Studio에서 애플리케이션을 빌드하는 데 몇 초 정도 걸립니다. 빌드가 완료되면 에뮬레이트된 Android 디바이스에서 애플리케이션을 테스트할 수 있습니다. 다음과 같은 맵이 표시됩니다.

Android 애플리케이션의 Azure Maps를 보여 주는 스크린샷

팁

기본적으로 Android는 방향이 변경되거나 키보드가 숨겨지면 작업을 다시 로드합니다. 이로 인해 맵 상태가 초기화됩니다(보기를 초기화하고 데이터를 초기 상태로 다시 로드하는 맵 다시 로드). 이를 방지하려면 매니페스트에 다음을 추가합니다. android:configChanges="orientation|keyboardHidden". 이렇게 하면 작업이 다시 로드되지 않고 방향이 변경되었거나 키보드가 숨겨져 있을 때 대신 onConfigurationChanged()를 호출합니다.

리소스 정리

Warning

다음 단계 섹션에 나열된 이 자습서에서는 계정에서 Azure Maps를 사용하고 구성하는 방법에 대해 자세히 설명되어 있습니다. 자습서를 계속 진행하려면 이 빠른 시작에서 만든 리소스를 정리하지 마세요.

자습서를 계속 진행하지 않으려면 다음 단계에 따라 리소스를 정리합니다.

Android Studio를 닫고 사용자가 만든 애플리케이션을 삭제합니다.
외부 디바이스에서 애플리케이션을 테스트한 경우 해당 디바이스에서 애플리케이션을 제거합니다.

Azure Maps Android SDK를 사용하여 계속 개발할 계획이 없는 경우:

Azure Portal 페이지로 이동합니다. 기본 포털 페이지에서 모든 리소스를 선택합니다.
Azure Maps 계정을 선택합니다. 페이지 위쪽에서 삭제를 선택합니다.
경우에 따라 Android 앱을 계속 개발할 계획이 없는 경우 Android Studio를 제거합니다.

추가 코드 예제는 다음 가이드를 참조하세요.

다음 단계

이 빠른 시작에서는 Azure Maps 계정을 만들고 데모 애플리케이션을 만들었습니다. Azure Maps에 대해 자세히 알아보려면 다음 자습서를 살펴보세요.

자습서: GeoJSON 데이터를 Azure Maps Android SDK로 로드

빠른 시작: Azure Maps를 사용하여 Android 앱 만들기

필수 조건

Azure Maps 계정 만들기

계정에 대한 구독 키 가져오기

Android Studio에서 프로젝트 만들기

가상 디바이스 설정

Azure Maps Android SDK 설치

리소스 정리

다음 단계

추가 리소스