기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Amazon Location Service를 위한 SDK 및 프레임워크
<a name="dev-sdks"></a>

AWS 는 여러 프로그래밍 언어를 위한 소프트웨어 개발 키트(SDKs)를 제공하므로 Amazon Location Service를 애플리케이션에 쉽게 통합할 수 있습니다. 이 페이지에서는 기본 개발 환경에서 Amazon Location Service를 시작하는 데 도움이 되는 사용 가능한 SDK, 해당 설치 절차 및 코드 예제를 간략하게 설명합니다.

Amazon Location Service를 사용하는 데 도움이 되는 몇 가지 도구가 있습니다.
+ **AWS SDKs**- AWS 소프트웨어 개발 키트(SDKs)는 널리 사용되는 여러 프로그래밍 언어로 제공되며 선호하는 언어로 애플리케이션을 더 쉽게 빌드할 수 있는 API, 코드 예제 및 설명서를 제공합니다. AWS SDKs에는 맵, 장소, 라우팅, 지오펜싱 및 트래커에 대한 액세스를 포함한 핵심 Amazon Location APIs 및 기능이 포함되어 있습니다. 다양한 애플리케이션 및 언어에 대해 Amazon Location Service와 함께 사용할 수 있는 SDK에 대해 자세히 알아보려면 [언어별 SDK](dev-by-language.md)을 참조하세요.
+ **MapLibre** – Amazon Location Service는 [MapLibre](https://github.com/maplibre/maplibre-gl-js) 렌더링 엔진을 사용하여 지도를 렌더링할 것을 권장합니다. MapLibre는 웹 또는 모바일 애플리케이션에서 지도를 표시하기 위한 엔진입니다. 또한 MapLibre에는 플러그인 모델이 있으며 일부 언어 및 플랫폼에서 검색 및 경로를 위한 사용자 인터페이스를 지원합니다. MapLibre 사용 및 MapLibre에서 제공하는 기능에 대한 자세한 내용은 [Amazon Location에서 MapLibre 도구 및 관련 라이브러리 사용](dev-maplibre.md)을 참조하세요.
+ **Amazon Location SDK** – Amazon Location SDK는 Amazon Location Service를 사용하여 애플리케이션을 더 쉽게 개발할 수 있게 해주는 오픈 소스 라이브러리 세트입니다. 라이브러리는 모바일 및 웹 애플리케이션에 대한 인증, 모바일 애플리케이션에 대한 위치 추적, Amazon Location 데이터 유형과 [GeoJSON](https://geojson.org/) 간의 변환, AWS SDK v3용 Amazon Location 클라이언트의 호스팅 패키지를 지원하는 기능을 제공합니다. Amazon Location SDK에 대한 자세한 내용은 [언어별 SDK](dev-by-language.md)을 참조하세요.
+ **Amazon Location Migration SDK** - Amazon Location Migration SDK는 기존 애플리케이션을 Google Maps에서 Amazon Location으로 마이그레이션할 수 있는 브리지를 제공합니다. Migration SDK는 Amazon Location이 사용되는 기능을 지원하는 경우 애플리케이션 또는 비즈니스 로직을 다시 작성할 필요 없이 Google Maps SDK for JavaScript를 사용하여 구축된 애플리케이션이 Amazon Location Service를 사용할 수 있는 옵션을 제공합니다. Migration SDK는 Google Map 대신 모든 API 직접 호출을 Amazon Location으로 리디렉션합니다. 시작하려면 GitHub의 [Amazon Location Migration SDK](https://github.com/aws-geospatial/amazon-location-migration)를 참조하세요.

# 개발자 자습서
<a name="sdk-how-to"></a>

이 섹션에서는 Amazon Location Service SDK의 다양한 측면을 사용하는 방법을 알아봅니다.

**Topics**
+ [인증 도우미 사용 방법](how-to-auth-helper.md)
+ [Amazon Location MapLibre 지오코더 GL 플러그인 사용](dev-maplibre-geocoder.md)
+ [추적 SDK 사용 방법](dev-tracking-sdk.md)
+ [Amazon Location에서 MapLibre 도구 및 관련 라이브러리 사용](dev-maplibre.md)

# 인증 도우미 사용 방법
<a name="how-to-auth-helper"></a>

이 섹션에서는 인증 도우미에 대한 추가 정보를 제공합니다.

## 웹
<a name="loc-sdk-auth-web"></a>

Amazon Location JavaScript 인증 유틸리티는 JavaScript 애플리케이션에서 Amazon Location Service API를 호출할 때 인증을 지원합니다. 이러한 유틸리티는 특히 API 키 또는 Amazon Cognito를 사용한 인증을 지원합니다.

**설치**
+ NPM을 사용하여 이 라이브러리를 설치합니다.

  ```
  npm install @aws/amazon-location-utilities-auth-helper
  ```
+ 브라우저에서 직접 사용하려면 HTML 파일에 다음을 포함합니다.

  ```
  <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-auth-helper@1"></script>
  ```

### 사용법
<a name="loc-sdk-auth-usage"></a>

인증 도우미를 사용하려면 라이브러리를 가져온 후 필요한 유틸리티 함수를 호출합니다. 이 라이브러리는 [Maps](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-maps/), [Places](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-places/) 및 [Routes](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/geo-routes/) 독립형 SDK를 포함한 Amazon Location Service SDK의 요청 인증과 [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js)를 사용한 맵 렌더링을 지원합니다.

**모듈 사용**

이 예제에서는 독립형 Places SDK를 사용하여 API 키로 요청을 인증하는 방법을 보여줍니다.

```
npm install @aws-sdk/client-geo-places

import { GeoPlacesClient, GeocodeCommand } from "@aws-sdk/client-geo-places";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new GeoPlacesClient(authHelper.getClientConfig());

const input = { ... };
const command = new GeocodeCommand(input);
const response = await client.send(command);
```

이 예제에서는 독립형 Routes SDK를 사용하여 API 키로 요청을 인증하는 방법을 보여줍니다.

```
npm install @aws-sdk/geo-routes-client

import { GeoRoutesClient, CalculateRoutesCommand } from "@aws-sdk/geo-routes-client";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new GeoRoutesClient(authHelper.getClientConfig());

const input = { ... };
const command = new CalculateRoutesCommand(input);
const response = await client.send(command);
```

이 예제에서는 Location SDK를 API 키 인증과 함께 사용합니다.

```
npm install @aws-sdk/client-location

import { LocationClient, ListGeofencesCommand } from "@aws-sdk/client-location";
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";

const authHelper = withAPIKey("<API Key>", "<Region>");
const client = new LocationClient(authHelper.getClientConfig());

const input = { ... };
const command = new ListGeofencesCommand(input);
const response = await client.send(command);
```

**브라우저에서 사용**

유틸리티 함수는 브라우저 환경에서 직접 사용할 때 amazonLocationAuthHelper 글로벌 객체에서 액세스할 수 있습니다.

이 예제에서는 API 키를 사용하여 인증된 Amazon Location Client에 대한 요청을 보여줍니다.

```
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>

const authHelper = amazonLocationClient.withAPIKey("<API Key>", "<Region>");
const client = new amazonLocationClient.GeoRoutesClient(authHelper.getClientConfig());
const input = { ... };
const command = new amazonLocationClient.routes.CalculateRoutesCommand(input);
const response = await client.send(command);
```

이 예제에서는 API 키를 사용하여 인증된 MapLibre GL JS로 맵을 렌더링하는 방법을 보여줍니다.

```
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.x"></script>

const apiKey = "<API Key>";
const region = "<Region>";
const styleName = "Standard";

const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor?key=${apiKey}`,
});
```

이 예제에서는 Amazon Cognito를 사용하여 MapLibre GL JS로 맵을 렌더링하는 방법을 보여줍니다.

```
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.x"></script>
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-auth-helper@1"></script>

const identityPoolId = "<Identity Pool ID>";
const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(identityPoolId);

const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${styleName}/descriptor`,
  ...authHelper.getMapAuthenticationOptions(),
});
```

**인증된 자격 증명을 사용한 대체 사용**

인증된 자격 증명에 대한 사용자 지정 파라미터를 포함하도록 withIdentityPoolId 함수를 수정할 수 있습니다.

```
const userPoolId = "<User Pool ID>";

const authHelper = await amazonLocationAuthHelper.withIdentityPoolId(identityPoolId, {
  logins: {
    [`cognito-idp.${region}.amazonaws.com/${userPoolId}`]: "cognito-id-token"
  }
});
```

## iOS
<a name="loc-sdk-auth-ios"></a>

iOS용 Amazon Location Service 모바일 인증 SDK는 iOS 애플리케이션에서 Amazon Location Service API에 대한 요청을 인증하는 데 도움이 됩니다. 특히 API 키 또는 Amazon Cognito를 통한 인증을 지원합니다.

**설치**
+ Xcode를 열고 **파일 > 패키지 종속성 추가**로 이동합니다.
+ 패키지 URL([https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios/](https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios/))를 검색 창에 입력하고 Enter를 누릅니다.
+ "amazon-location-mobile-auth-sdk-ios" 패키지를 선택하고 **패키지 추가**를 클릭합니다.
+ "AmazonLocationiOSAuthSDK" 패키지 제품을 선택하고 **패키지 추가**를 클릭합니다.

### 사용법
<a name="loc-sdk-auth-usage"></a>

라이브러리를 설치한 후 `AuthHelper` 클래스를 사용하여 API 키 또는 Amazon Cognito에 대한 클라이언트 설정을 구성합니다.

**API 키**

다음은 API 키 인증과 함께 독립형 Places SDK를 사용하는 예제입니다.

```
import AmazonLocationiOSAuthSDK
import AWSGeoPlaces

func geoPlacesExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: GeoPlacesClient = GeoPlacesClient(config: authHelper.getGeoPlacesClientConfig())

    let input = AWSGeoPlaces.SearchTextInput(
        biasPosition: [-97.7457518, 30.268193],
        queryText: "tacos"
    )

    let output = try await client.searchText(input: input)
}
```

다음은 API 키 인증과 함께 독립형 Routes SDK를 사용하는 예제입니다.

```
import AmazonLocationiOSAuthSDK
import AWSGeoRoutes

func geoRoutesExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: GeoRoutesClient = GeoRoutesClient(config: authHelper.getGeoRoutesClientConfig())

    let input = AWSGeoRoutes.CalculateRoutesInput(
        destination: [-123.1651031, 49.2577281],
        origin: [-97.7457518, 30.268193]
    )

    let output = try await client.calculateRoutes(input: input)
}
```

다음은 API 키 인증과 함께 Location SDK를 사용하는 예제입니다.

```
import AmazonLocationiOSAuthSDK
import AWSLocation

func locationExample() {
    let apiKey = "<API key>"
    let region = "<Region>"

    let authHelper = try await AuthHelper.withApiKey(apiKey: apiKey, region: region)
    let client: LocationClient = LocationClient(config: authHelper.getLocationClientConfig())

    let input = AWSLocation.ListGeofencesInput(
        collectionName: "<Collection name>"
    )

    let output = try await client.listGeofences(input: input)
}
```

다음은 Amazon Cognito와 함께 독립형 Places SDK를 사용하는 예제입니다.

```
import AmazonLocationiOSAuthSDK
import AWSGeoPlaces

func geoPlacesExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: GeoPlacesClient = GeoPlacesClient(config: authHelper.getGeoPlacesClientConfig())

    let input = AWSGeoPlaces.SearchTextInput(
        biasPosition: [-97.7457518, 30.268193],
        queryText: "tacos"
    )

    let output = try await client.searchText(input: input)
}
```

다음은 Amazon Cognito와 함께 독립형 Routes SDK를 사용하는 예제입니다.

```
import AmazonLocationiOSAuthSDK
import AWSGeoRoutes

func geoRoutesExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: GeoRoutesClient = GeoRoutesClient(config: authHelper.getGeoRoutesClientConfig())

    let input = AWSGeoRoutes.CalculateRoutesInput(
        destination: [-123.1651031, 49.2577281],
        origin: [-97.7457518, 30.268193]
    )

    let output = try await client.calculateRoutes(input: input)
}
```

다음은 Amazon Cognito와 함께 Location SDK를 사용하는 예제입니다.

```
import AmazonLocationiOSAuthSDK
import AWSLocation

func locationExample() {
    let identityPoolId = "<Identity Pool ID>"

    let authHelper = try await AuthHelper.withIdentityPoolId(identityPoolId: identityPoolId)
    let client: LocationClient = LocationClient(config: authHelper.getLocationClientConfig())

    let input = AWSLocation.ListGeofencesInput(
        collectionName: "<Collection name>"
    )

    let output = try await client.listGeofences(input: input)
}
```

## Android
<a name="loc-sdk-auth-android"></a>

Android용 Amazon Location Service 모바일 인증 SDK는 Android 애플리케이션에서 Amazon Location Service API에 대한 요청을 인증하는 데 도움이 되며, 특히 Amazon Cognito를 사용한 인증을 지원합니다.

**설치**
+ 이 인증 SDK는 전체 AWS Kotlin SDK에서 작동합니다. 두 SDK는 Maven Central에 게시됩니다. Maven Central에서 [인증 SDK](https://mvnrepository.com/artifact/software.amazon.location/auth)의 최신 버전을 확인합니다.
+ Android Studio에서 `build.gradle` 파일의 종속성 섹션에 다음 줄을 추가합니다.

  ```
  implementation("software.amazon.location:auth:1.1.0")
  implementation("org.maplibre.gl:android-sdk:11.5.2")
  implementation("com.squareup.okhttp3:okhttp:4.12.0")
  ```
+ 독립형 Maps, Places 및 Routes SDK의 경우 다음 줄을 추가합니다.

  ```
  implementation("aws.sdk.kotlin:geomaps:1.3.65")
  implementation("aws.sdk.kotlin:geoplaces:1.3.65")
  implementation("aws.sdk.kotlin:georoutes:1.3.65")
  ```
+ 지오펜싱 및 추적이 포함된 통합 Location SDK의 경우 다음 줄을 추가합니다.

  ```
  implementation("aws.sdk.kotlin:location:1.3.65")
  ```

### 사용법
<a name="loc-sdk-auth-usage"></a>

코드에서 다음 클래스를 가져옵니다.

```
// For the standalone Maps, Places, and Routes SDKs
import aws.sdk.kotlin.services.geomaps.GeoMapsClient
import aws.sdk.kotlin.services.geoplaces.GeoPlacesClient
import aws.sdk.kotlin.services.georoutes.GeoRoutesClient

// For the consolidated Location SDK
import aws.sdk.kotlin.services.location.LocationClient

import software.amazon.location.auth.AuthHelper
import software.amazon.location.auth.LocationCredentialsProvider
import software.amazon.location.auth.AwsSignerInterceptor
import org.maplibre.android.module.http.HttpRequestUtil
import okhttp3.OkHttpClient
```

를 생성하고 AWS Kotlin SDK와 함께 `AuthHelper` 사용할 수 있습니다.

**예: 자격 증명 풀 ID가 있는 자격 증명 공급자**

```
private suspend fun exampleCognitoLogin() {
    val authHelper = AuthHelper.withCognitoIdentityPool("MY-COGNITO-IDENTITY-POOL-ID", applicationContext)
    
    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

**예: 사용자 지정 자격 증명 공급자가 있는 자격 증명 공급자**

```
private suspend fun exampleCustomCredentialLogin() {
    var authHelper = AuthHelper.withCredentialsProvider(MY-CUSTOM-CREDENTIAL-PROVIDER, "MY-AWS-REGION", applicationContext)

    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

**예: API 키가 있는 자격 증명 공급자**

```
private suspend fun exampleApiKeyLogin() {
    var authHelper = AuthHelper.withApiKey("MY-API-KEY", "MY-AWS-REGION", applicationContext)

    var geoMapsClient = GeoMapsClient(authHelper?.getGeoMapsClientConfig())
    var geoPlacesClient = GeoPlacesClient(authHelper?.getGeoPlacesClientConfig())
    var geoRoutesClient = GeoRoutesClient(authHelper?.getGeoRoutesClientConfig())
    
    var locationClient = LocationClient(authHelper?.getLocationClientConfig())
}
```

`LocationCredentialsProvider`를 사용하여 MapLibre 맵을 로드할 수 있습니다. 다음 예를 참고하세요

```
HttpRequestUtil.setOkHttpClient(
    OkHttpClient.Builder()
        .addInterceptor(
            AwsSignerInterceptor(
                "geo",
                "MY-AWS-REGION",
                locationCredentialsProvider,
                applicationContext
            )
        )
        .build()
)
```

생성된 클라이언트를 사용하여 Amazon Location Service를 호출합니다. 다음은 지정된 위도 및 경도에 가까운 장소를 검색하는 예제입니다.

```
val suggestRequest = SuggestRequest {
       biasPosition = listOf(-97.718833, 30.405423)
       maxResults = MAX_RESULT
       language = "PREFERRED-LANGUAGE"
   }
val nearbyPlaces = geoPlacesClient.suggest(suggestRequest)
```

# Amazon Location MapLibre 지오코더 GL 플러그인 사용
<a name="dev-maplibre-geocoder"></a>

Amazon Location MapLibre 지오코더 플러그인은 [maplibre-gl-geocoder](https://github.com/maplibre/maplibre-gl-geocoder) 라이브러리를 사용하여 맵 렌더링 및 지오코딩 작업을 수행할 때 Amazon Location 기능을 JavaScript 애플리케이션에 더 쉽게 통합할 수 있도록 설계되었습니다.

## 설치
<a name="geocoder-installation"></a>

모듈에서 사용할 수 있도록 NPM에서 Amazon Location MapLibre 지오코더 플러그인을 설치합니다. 다음 명령을 입력합니다.

```
npm install @aws/amazon-location-for-maplibre-gl-geocoder
```

스크립트를 사용하여 브라우저에서 직접 사용할 HTML 및 CSS 파일을 가져올 수 있습니다.

```
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-for-maplibre-gl-geocoder@2"></script>
<link
  href="https://cdn.jsdelivr.net/npm/@aws/amazon-location-for-maplibre-gl-geocoder@2/dist/amazon-location-for-mlg-styles.css"
  rel="stylesheet"
/>
```

## 모듈에서 사용 - 독립형 GeoPlaces SDK
<a name="geocoder-module"></a>

이 예제에서는 [AWS SDK for JavaScript V3](https://github.com/aws/aws-sdk-js-v3)를 사용하여 라이브러리에 제공할 GeoPlacesClient와 GeoPlacesClient를 인증하기 위한 [AuthHelper](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js)를 가져옵니다. 지오코더에 대한 모든 API를 활성화합니다.

```
// Import MapLibre GL JS
import maplibregl from "maplibre-gl";
// Import from the AWS JavaScript SDK V3
import { GeoPlacesClient } from "@aws-sdk/client-geo-places";
// Import the utility functions
import { withAPIKey } from "@aws/amazon-location-utilities-auth-helper";
// Import the AmazonLocationMaplibreGeocoder
import {
  buildAmazonLocationMaplibreGeocoder,
  AmazonLocationMaplibreGeocoder,
} from "@aws/amazon-location-for-maplibre-gl-geocoder";

const apiKey = "<API Key>";
const mapName = "Standard";
const region = "<Region>"; // region containing Amazon Location API Key

// Create an authentication helper instance using an API key and region
const authHelper = await withAPIKey(apiKey, region);

const client = new GeoPlacesClient(authHelper.getClientConfig());

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${mapStyle}/descriptor?key=${apiKey}`,
});

// Gets an instance of the AmazonLocationMaplibreGeocoder Object.
const amazonLocationMaplibreGeocoder = buildAmazonLocationMaplibreGeocoder(client, { enableAll: true });

// Now we can add the Geocoder to the map.
map.addControl(amazonLocationMaplibreGeocoder.getPlacesGeocoder());
```

## 브라우저에서 사용 - 독립형 GeoPlaces SDK
<a name="geocoder-browser"></a>

이 예제에서는 Amazon Location 클라이언트를 사용하여 API 키를 통해 인증되는 요청을 작성합니다.

**참고**  
이러한 예제 중 일부는 Amazon Location GeoPlacesClient를 사용합니다. 이 클라이언트는 [AWS SDK for JavaScript V3](https://github.com/aws/aws-sdk-js-v3)를 기반으로 하며 HTML 파일에 참조된 스크립트를 통해 Amazon Location에 직접적으로 호출할 수 있습니다.

HTML 파일에 다음을 포함합니다.

```
<!-- Import the Amazon Location For Maplibre Geocoder -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-for-maplibre-gl-geocoder@2"></script>
<link
  href="https://cdn.jsdelivr.net/npm/@aws/amazon-location-for-maplibre-gl-geocoder@2/dist/amazon-location-for-mlg-styles.css"
  rel="stylesheet"
/>
<!-- Import the Amazon GeoPlacesClient -->
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
```

JavaScript 파일에 다음을 포함합니다.

```
const apiKey = "<API Key>";
const mapStyle = "Standard";
const region = "<Region>"; // region containing Amazon Location API key

// Create an authentication helper instance using an API key and region
const authHelper = await amazonLocationClient.withAPIKey(apiKey, region);

const client = new amazonLocationClient.GeoPlacesClient(authHelper.getClientConfig());

// Render the map
const map = new maplibregl.Map({
  container: "map",
  center: [-123.115898, 49.295868],
  zoom: 10,
  style: `https://maps.geo.${region}.amazonaws.com/v2/styles/${mapStyle}/descriptor?key=${apiKey}`,
});

// Initialize the AmazonLocationMaplibreGeocoder object
const amazonLocationMaplibreGeocoderObject = amazonLocationMaplibreGeocoder.buildAmazonLocationMaplibreGeocoder(
  client,
  { enableAll: true },
);

// Use the AmazonLocationWithMaplibreGeocoder object to add a geocoder to the map.
map.addControl(amazonLocationMaplibreGeocoderObject.getPlacesGeocoder());
```

## 함수
<a name="geocoder-functions"></a>

다음은 Amazon Location MapLibre 지오코더 플러그인에 사용되는 함수입니다.
+ `buildAmazonLocationMaplibreGeocoder`

  이 클래스는 다른 모든 직접 호출의 진입점인 `AmazonLocationMaplibreGeocder`의 인스턴스를 생성합니다.

  독립형 `GeoPlacesClient` API 호출 사용(클라이언트는 `GeoPlacesClient`의 인스턴스임):

  ```
  const amazonLocationMaplibreGeocoder = buildAmazonLocationMaplibreGeocoder(client, { enableAll: true });
  ```

  통합 `LocationClient` API 호출 사용(클라이언트는 `LocationClient`의 인스턴스임):

  ```
  const amazonLocationMaplibreGeocoder = buildAmazonLocationMaplibreGeocoder(client, {
    enableAll: true,
    placesIndex: placeIndex,
  });
  ```
+ `getPlacesGeocoder`

  맵에 직접 추가할 수 있는 즉시 사용 가능한 IControl 객체를 반환합니다.

  ```
  const geocoder = getPlacesGeocoder();
  
  // Initialize map see: <insert link to initializing a map instance here>
  let map = await initializeMap();
  
  // Add the geocoder to the map.
  map.addControl(geocoder);
  ```

# 추적 SDK 사용 방법
<a name="dev-tracking-sdk"></a>

이 주제에서는 추적 SDK 사용 방법에 대한 정보를 제공합니다.

# iOS
<a name="loc-mobile-tracking-ios"></a>

Amazon Location 모바일 추적 SDK는 쉽게 인증하고 디바이스 위치를 캡처하고 Amazon Location Tracker에 위치 업데이트를 전송하는 데 도움이 되는 유틸리티를 제공합니다. SDK는 구성 가능한 업데이트 간격을 사용하여 위치 업데이트의 로컬 필터링을 지원합니다. 이렇게 하면 데이터 비용이 절감되고 iOS 애플리케이션의 간헐적인 연결이 최적화됩니다.

iOS 추적 SDK는 GitHub: [iOS용 Amazon Location 모바일 추적 SDK](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios)에서 사용할 수 있습니다.

이 섹션에서는 Amazon Location 모바일 추적 iOS SDK에 대한 다음 주제를 다룹니다.

**Topics**
+ [설치](#loc-mobile-tracking-install-ios)
+ [사용법](#loc-mobile-tracking-usage-ios)
+ [필터](#loc-mobile-tracking-ios-filters)
+ [iOS 모바일 SDK 추적 함수](#loc-mobile-tracking-functions)
+ [예제](#loc-mobile-tracking-example-ios)

## 설치
<a name="loc-mobile-tracking-install-ios"></a>

다음 절차에 따라 iOS용 모바일 추적 SDK를 설치합니다.

1. Xcode 프로젝트에서 **파일**로 이동하여 **패키지 종속성 추가**를 선택합니다.

1. 검색 창에 [https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/) URL을 입력하고 Enter 키를 누릅니다.

1. `amazon-location-mobile-tracking-sdk-ios` 패키지를 선택하고 **패키지 추가**를 클릭합니다.

1. `AmazonLocationiOSTrackingSDK` 패키지 제품을 선택하고 **패키지 추가**를 클릭합니다.

## 사용법
<a name="loc-mobile-tracking-usage-ios"></a>

다음 절차에서는 Amazon Cognito의 자격 증명을 사용하여 인증 도우미를 생성하는 방법을 보여줍니다.

1. 라이브러리를 설치한 후 `info.plist` 파일에 다음 설명 중 하나 또는 둘 모두 추가해야 합니다.

   ```
   Privacy - Location When In Use Usage Description
   Privacy - Location Always and When In Use Usage Description
   ```

1. 다음으로 클래스에서 AuthHelper를 가져옵니다.

   ```
   import AmazonLocationiOSAuthSDKimport AmazonLocationiOSTrackingSDK
   ```

1. 그런 다음 Amazon Cognito의 자격 증명을 사용하여 인증 도우미를 생성하여 `AuthHelper` 객체를 생성하고 AWS SDK와 함께 사용합니다.

   ```
   let authHelper = AuthHelper()
   let locationCredentialsProvider = authHelper.authenticateWithCognitoUserPool(identityPoolId: "My-Cognito-Identity-Pool-Id", region: "My-region") //example: us-east-1
   let locationTracker = LocationTracker(provider: locationCredentialsProvider, trackerName: "My-tracker-name")
   
   // Optionally you can set ClientConfig with your own values in either initialize or in a separate function
   // let trackerConfig = LocationTrackerConfig(locationFilters: [TimeLocationFilter(), DistanceLocationFilter()],
   
        trackingDistanceInterval: 30,
        trackingTimeInterval: 30,
        logLevel: .debug)
   
   // locationTracker = LocationTracker(provider: credentialsProvider, trackerName: "My-tracker-name",config: trackerConfig)
   // locationTracker.setConfig(config: trackerConfig)
   ```

## 필터
<a name="loc-mobile-tracking-ios-filters"></a>

Amazon Location 모바일 추적 iOS SDK에는 3개의 내장 위치 필터가 있습니다.
+ `TimeLocationFilter`: 정의된 시간 간격을 기준으로 업로드할 현재 위치를 필터링합니다.
+ `DistanceLocationFilter`: 지정된 거리 임계값을 기준으로 위치 업데이트를 필터링합니다.
+ `AccuracyLocationFilter`: 마지막 업데이트 이후 이동한 거리를 현재 위치의 정확도와 비교하여 위치 업데이트를 필터링합니다.

이 예제에서는 생성 시 `LocationTracker`에 필터를 추가합니다.

```
val config = LocationTrackerConfig(
    trackerName = "MY-TRACKER-NAME",
    logLevel = TrackingSdkLogLevel.DEBUG,
    accuracy = Priority.PRIORITY_HIGH_ACCURACY,
    latency = 1000,
    frequency = 5000,
    waitForAccurateLocation = false,
    minUpdateIntervalMillis = 5000,
    locationFilters = mutableListOf(TimeLocationFilter(), DistanceLocationFilter(), AccuracyLocationFilter())
)

locationTracker = LocationTracker(
    applicationContext,
    locationCredentialsProvider,
    config,
)
```

이 예제에서는 `LocationTracker`를 사용하여 런타임 시 필터를 활성화 및 비활성화합니다.

```
// To enable the filter
locationTracker?.enableFilter(TimeLocationFilter())

// To disable the filter
locationTracker?.disableFilter(TimeLocationFilter())
```

## iOS 모바일 SDK 추적 함수
<a name="loc-mobile-tracking-functions"></a>

iOS용 Amazon Location 모바일 추적 SDK에는 다음 함수가 포함됩니다.
+ **클래스**: `LocationTracker`

  `init(provider: LocationCredentialsProvider, trackerName: String, config: LocationTrackerConfig? = nil)`

  이는 `LocationTracker` 객체를 생성하는 초기화 기능입니다. `LocationCredentialsProvider` , `trackerName`의 인스턴스와 선택적으로 `LocationTrackingConfig`의 인스턴스가 필요합니다. 구성이 제공되지 않으면 기본값으로 초기화됩니다.
+ **클래스**: `LocationTracker`

  `setTrackerConfig(config: LocationTrackerConfig)`

  이렇게 하면 위치 추적기를 초기화한 후 언제든지 추적기의 구성이 적용되도록 설정합니다.
+ **클래스**: `LocationTracker`

  `getTrackerConfig()`

  이렇게 하면 앱에서 사용하거나 수정할 위치 추적 구성을 가져옵니다.

  반환 값: `LocationTrackerConfig`
+ **클래스**: `LocationTracker`

  `getDeviceId()`

  위치 추적기의 생성된 디바이스 ID를 가져옵니다.

  반환 값: `String?`
+ **클래스**: `LocationTracker`

  `startTracking()`

  사용자의 위치에 액세스하여 AWS 트래커로 전송하는 프로세스를 시작합니다.
+ **클래스**: `LocationTracker`

  `resumeTracking()`

  사용자의 위치에 액세스하여 AWS 트래커로 전송하는 프로세스를 재개합니다.
+ **클래스**: `LocationTracker`

  `stopTracking()`

  사용자의 위치를 추적하는 프로세스를 중지합니다.
+ **클래스**: `LocationTracker`

  `startBackgroundTracking(mode: BackgroundTrackingMode)`

  애플리케이션이 백그라운드에 있는 동안 사용자의 위치에 액세스하여 AWS 트래커로 전송하는 프로세스를 시작합니다. `BackgroundTrackingMode`에는 다음 옵션이 있습니다.
  + `Active:` 이 옵션은 위치 업데이트를 자동으로 일시 중지하지 않습니다.
  + `BatterySaving:` 이 옵션은 위치 업데이트를 자동으로 일시 중지합니다.
  + `None:` 이 옵션은 전체적으로 백그라운드 위치 업데이트를 비활성화합니다.
+ **클래스**: `LocationTracker`

  `resumeBackgroundTracking(mode: BackgroundTrackingMode)`

  애플리케이션이 백그라운드에 있는 동안 사용자의 위치에 액세스하여 AWS 트래커로 전송하는 프로세스를 재개합니다.
+ **클래스**: `LocationTracker`

  `stopBackgroundTracking()`

  애플리케이션이 백그라운드에 있는 동안 사용자의 위치에 액세스하여 AWS 트래커로 전송하는 프로세스를 중지합니다.
+ **클래스**: `LocationTracker`

  `getTrackerDeviceLocation(nextToken: String?, startTime: Date? = nil, endTime: Date? = nil, completion: @escaping (Result<GetLocationResponse, Error>)`

  시작 날짜 및 시간과 종료 날짜 및 시간 사이에 사용자 디바이스에 대해 업로드된 추적 위치를 검색합니다.

  반환 값: `Void`
+ **클래스**: `LocationTrackerConfig`

  `init()`

  이렇게 하면 기본값으로 LocationTrackerConfig가 초기화됩니다.
+ **클래스**: `LocationTrackerConfig`

  `init(locationFilters: [LocationFilter]? = nil, trackingDistanceInterval: Double? = nil, trackingTimeInterval: Double? = nil, trackingAccuracyLevel: Double? = nil, uploadFrequency: Double? = nil, desiredAccuracy: CLLocationAccuracy? = nil, activityType: CLActivityType? = nil, logLevel: LogLevel? = nil)`

  이렇게 하면 사용자 정의 파라미터 값으로 `LocationTrackerConfig`가 초기화됩니다. 파라미터 값이 제공되지 않으면 기본값으로 설정됩니다.
+ **클래스**: `LocationFilter`

  `shouldUpload(currentLocation: LocationEntity, previousLocation: LocationEntity?, trackerConfig: LocationTrackerConfig)`

  `LocationFilter`는 사용자가 사용자 지정 필터 구현을 위해 사용자가 구현할 수 있는 프로토콜입니다. 사용자는 이전 위치와 현재 위치를 비교하고 현재 위치를 업로드해야 하는 경우 반환하는 `shouldUpload` 함수를 구현해야 합니다.

## 예제
<a name="loc-mobile-tracking-example-ios"></a>

이 섹션에서는 iOS용 Amazon Location 모바일 추적 SDK 사용의 예를 자세히 설명합니다.

**참고**  
`info.plist` 파일에 필요한 권한이 설정되어 있는지 확인합니다. 이는 [사용법](#loc-mobile-tracking-usage-ios) 섹션에 나열된 것과 동일한 권한입니다.

다음 예제에서는 디바이스 위치를 추적하고 추적된 위치를 검색하는 기능을 보여줍니다.

```
Privacy - Location When In Use Usage Description
Privacy - Location Always and When In Use Usage Description
```

위치 추적 시작:

```
do {
    try locationTracker.startTracking()
    } 
catch TrackingLocationError.permissionDenied {
        // Handle permissionDenied by showing the alert message or opening the app settings
        }
```

위치 추적 재개:

```
do { 
    try locationTracker.resumeTracking()
    } 
catch TrackingLocationError.permissionDenied {
    // Handle permissionDenied by showing the alert message or opening the app settings
    }
```

위치 추적 중지:

```
locationTracker.stopTracking()
```

백그라운드 추적 시작:

```
do {
    locationTracker.startBackgroundTracking(mode: .Active) // .Active, .BatterySaving, .None
    } 
catch TrackingLocationError.permissionDenied {
   // Handle permissionDenied by showing the alert message or opening the app settings
   }
```

백그라운드 추적 재개:

```
do {
    locationTracker.resumeBackgroundTracking(mode: .Active)
    } 
catch TrackingLocationError.permissionDenied {
    // Handle permissionDenied by showing the alert message or opening the app settings
    }
```

백그라운드 추적을 중지하려면:

```
locationTracker.stopBackgroundTracking()
```

트래커에서 디바이스의 추적된 위치를 검색합니다.

```
func getTrackingPoints(nextToken: String? = nil) {
let startTime: Date = Date().addingTimeInterval(-86400) // Yesterday's day date and time
let endTime: Date = Date() 
locationTracker.getTrackerDeviceLocation(nextToken: nextToken, startTime: startTime, endTime: endTime, completion: { [weak self] result in
    switch result {
    case .success(let response):
        
        let positions = response.devicePositions
        // You can draw positions on map or use it further as per your requirement

        // If nextToken is available, recursively call to get more data
        if let nextToken = response.nextToken {
            self?.getTrackingPoints(nextToken: nextToken)
        }
    case .failure(let error):
        print(error)
    }
})
}
```

# Android 모바일 추적 SDK
<a name="loc-mobile-tracking-android"></a>

Amazon Location 모바일 추적 SDK는 쉽게 인증하고 디바이스 위치를 캡처하고 Amazon Location Tracker에 위치 업데이트를 전송하는 데 도움이 되는 유틸리티를 제공합니다. SDK는 구성 가능한 업데이트 간격을 사용하여 위치 업데이트의 로컬 필터링을 지원합니다. 이렇게 하면 데이터 비용이 절감되고 Android 애플리케이션의 간헐적인 연결이 최적화됩니다.

Android 추적 SDK는 GitHub: [Android용 Amazon Location 모바일 추적 SDK](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-android)에서 사용할 수 있습니다. 또한 모바일 인증 SDK와 AWS SDK는 [AWS Maven 리포지토리](https://central.sonatype.com/artifact/software.amazon.location/tracking)에서 모두 사용할 수 있습니다. Android 추적 SDK는 일반 AWS SDK와 함께 작동하도록 설계되었습니다.

이 섹션에서는 Amazon Location 모바일 추적 Android SDK에 대한 다음 주제를 다룹니다.

**Topics**
+ [설치](#loc-mobile-tracking-install-android)
+ [사용법](#loc-mobile-tracking-usage-android)
+ [필터](#loc-mobile-tracking-android-filters)
+ [Android 모바일 SDK 추적 함수](#loc-mobile-tracking-functions)
+ [예제](#loc-mobile-tracking-example-android)

## 설치
<a name="loc-mobile-tracking-install-android"></a>

SDK를 설치하려면 Android Studio에서 build.gradle 파일의 종속성 섹션에 다음 줄을 추가합니다.

```
implementation("software.amazon.location:tracking:0.0.1")
implementation("software.amazon.location:auth:0.0.1")
implementation("com.amazonaws:aws-android-sdk-location:2.72.0")
```

## 사용법
<a name="loc-mobile-tracking-usage-android"></a>

이 절차는 SDK를 사용하여 `LocationTracker` 객체를 인증하고 생성하는 방법을 보여줍니다.

**참고**  
이 절차에서는 [설치](#loc-mobile-tracking-install-android) 섹션에 언급된 라이브러리를 가져온 것으로 가정합니다.

1. 코드에서 다음 클래스를 가져옵니다.

   ```
   import software.amazon.location.tracking.LocationTracker
   import software.amazon.location.tracking.config.LocationTrackerConfig
   import software.amazon.location.tracking.util.TrackingSdkLogLevel
   import com.amazonaws.services.geo.AmazonLocationClient
   import software.amazon.location.auth.AuthHelper
   import software.amazon.location.auth.LocationCredentialsProvider
   ```

1. 그런 다음 `LocationTracker` 객체를 생성하는 데 `LocationCredentialsProvider` 파라미터가 필요하므로 `AuthHelper`를 생성합니다.

   ```
   // Create an authentication helper using credentials from Amazon Cognito
   val authHelper = AuthHelper(applicationContext)
   val locationCredentialsProvider : LocationCredentialsProvider = authHelper.authenticateWithCognitoIdentityPool("My-Cognito-Identity-Pool-Id")
   ```

1. 이제 `LocationCredentialsProvider` 및 `LocationTrackerConfig`를 사용하여 `LocationTracker` 객체를 생성합니다.

   ```
   val config = LocationTrackerConfig(
       trackerName = "MY-TRACKER-NAME",
       logLevel = TrackingSdkLogLevel.DEBUG,
       accuracy = Priority.PRIORITY_HIGH_ACCURACY,
       latency = 1000,
       frequency = 5000,
       waitForAccurateLocation = false,
       minUpdateIntervalMillis = 5000,
   )
   locationTracker = LocationTracker(
       applicationContext,
       locationCredentialsProvider,
       config,
   )
   ```

## 필터
<a name="loc-mobile-tracking-android-filters"></a>

Amazon Location 모바일 추적 Android SDK에는 3개의 내장 위치 필터가 있습니다.
+ `TimeLocationFilter`: 정의된 시간 간격을 기준으로 업로드할 현재 위치를 필터링합니다.
+ `DistanceLocationFilter`: 지정된 거리 임계값을 기준으로 위치 업데이트를 필터링합니다.
+ `AccuracyLocationFilter`: 마지막 업데이트 이후 이동한 거리를 현재 위치의 정확도와 비교하여 위치 업데이트를 필터링합니다.

이 예제에서는 생성 시 `LocationTracker`에 필터를 추가합니다.

```
val config = LocationTrackerConfig(
    trackerName = "MY-TRACKER-NAME",
    logLevel = TrackingSdkLogLevel.DEBUG,
    accuracy = Priority.PRIORITY_HIGH_ACCURACY,
    latency = 1000,
    frequency = 5000,
    waitForAccurateLocation = false,
    minUpdateIntervalMillis = 5000,
    locationFilters = mutableListOf(TimeLocationFilter(), DistanceLocationFilter(), AccuracyLocationFilter())
)
locationTracker = LocationTracker(
    applicationContext,
    locationCredentialsProvider,
    config,
)
```

이 예제에서는 `LocationTracker`를 사용하여 런타임 시 필터를 활성화 및 비활성화합니다.

```
// To enable the filter
locationTracker?.enableFilter(TimeLocationFilter())

// To disable the filter
locationTracker?.disableFilter(TimeLocationFilter())
```

## Android 모바일 SDK 추적 함수
<a name="loc-mobile-tracking-functions"></a>

Android용 Amazon Location 모바일 추적 SDK에는 다음 함수가 포함됩니다.
+ **클래스**: `LocationTracker`

  `constructor(context: Context,locationCredentialsProvider: LocationCredentialsProvider,trackerName: String)` 또는 `constructor(context: Context,locationCredentialsProvider: LocationCredentialsProvider,clientConfig: LocationTrackerConfig)`

  이는 `LocationTracker` 객체를 생성하는 초기화 기능입니다. `LocationCredentialsProvider` , `trackerName`의 인스턴스와 선택적으로 `LocationTrackingConfig`의 인스턴스가 필요합니다. 구성이 제공되지 않으면 기본값으로 초기화됩니다.
+ **클래스**: `LocationTracker`

  `start(locationTrackingCallback: LocationTrackingCallback)`

  사용자의 위치에 액세스하여 Amazon Location 트래커로 전송하는 프로세스를 시작합니다.
+ **클래스**: `LocationTracker`

  `isTrackingInForeground()`

  위치 추적이 현재 진행 중인지 확인합니다.
+ **클래스**: `LocationTracker`

  `stop()`

  사용자의 위치를 추적하는 프로세스를 중지합니다.
+ **클래스**: `LocationTracker`

  `startTracking()`

  사용자의 위치에 액세스하여 AWS 트래커로 전송하는 프로세스를 시작합니다.
+ **클래스**: `LocationTracker`

  `startBackground(mode: BackgroundTrackingMode, serviceCallback: ServiceCallback)`

  애플리케이션이 백그라운드에 있는 동안 사용자의 위치에 액세스하여 AWS 트래커로 전송하는 프로세스를 시작합니다. `BackgroundTrackingMode`에는 다음 옵션이 있습니다.
  + `ACTIVE_TRACKING`: 이 옵션은 사용자의 위치 업데이트를 적극적으로 추적합니다.
  + `BATTERY_SAVER_TRACKING`: 이 옵션은 15분마다 사용자의 위치 업데이트를 추적합니다.
+ **클래스**: `LocationTracker`

  `stopBackgroundService()`

  애플리케이션이 백그라운드에 있는 동안 사용자의 위치에 액세스하여 AWS 트래커로 전송하는 프로세스를 중지합니다.
+ **클래스**: `LocationTracker`

  `getTrackerDeviceLocation()`

  Amazon Location 서비스에서 디바이스 위치를 검색합니다.
+ **클래스**: `LocationTracker`

  `getDeviceLocation(locationTrackingCallback: LocationTrackingCallback?)`

  융합된 위치 공급자 클라이언트에서 현재 디바이스 위치를 검색하여 Amazon Location 트래커에 업로드합니다.
+ **클래스**: `LocationTracker`

  `uploadLocationUpdates(locationTrackingCallback: LocationTrackingCallback?)`

  구성된 위치 필터를 기반으로 필터링한 후 Amazon Location 서비스에 디바이스 위치를 업로드합니다.
+ **클래스**: `LocationTracker`

  `enableFilter(filter: LocationFilter)`

  특정 위치 필터를 활성화합니다.
+ **클래스**: `LocationTracker`

  `checkFilterIsExistsAndUpdateValue(filter: LocationFilter)`

  특정 위치 필터를 비활성화합니다.
+ **클래스**: `LocationTrackerConfig`

  `LocationTrackerConfig( // Required var trackerName: String, // Optional var locationFilters: MutableList = mutableListOf( TimeLocationFilter(), DistanceLocationFilter(), ), var logLevel: TrackingSdkLogLevel = TrackingSdkLogLevel.DEBUG, var accuracy: Int = Priority.PRIORITY_HIGH_ACCURACY, var latency: Long = 1000, var frequency: Long = 1500, var waitForAccurateLocation: Boolean = false, var minUpdateIntervalMillis: Long = 1000, var persistentNotificationConfig: NotificationConfig = NotificationConfig()) `

  이렇게 하면 사용자 정의 파라미터 값으로 `LocationTrackerConfig`가 초기화됩니다. 파라미터 값이 제공되지 않으면 기본값으로 설정됩니다.
+ **클래스**: `LocationFilter`

  `shouldUpload(currentLocation: LocationEntry, previousLocation: LocationEntry?): Boolean`

  `LocationFilter`는 사용자가 사용자 지정 필터 구현을 위해 구현할 수 있는 프로토콜입니다. 이전 위치와 현재 위치를 비교하고 현재 위치를 업로드해야 하는지를 반환하는 `shouldUpload` 함수를 구현합니다.

## 예제
<a name="loc-mobile-tracking-example-android"></a>

다음 코드 샘플은 모바일 추적 SDK 기능을 보여줍니다.

이 예제에서는 `LocationTracker`를 사용하여 백그라운드에서 추적을 시작하고 중지합니다.

```
// For starting the location tracking
locationTracker?.startBackground(
BackgroundTrackingMode.ACTIVE_TRACKING,
object : ServiceCallback {
    override fun serviceStopped() {
        if (selectedTrackingMode == BackgroundTrackingMode.ACTIVE_TRACKING) {
            isLocationTrackingBackgroundActive = false
        } else {
            isLocationTrackingBatteryOptimizeActive = false
        }
    }
},
)

// For stopping the location tracking
locationTracker?.stopBackgroundService()
```

# Amazon Location에서 MapLibre 도구 및 관련 라이브러리 사용
<a name="dev-maplibre"></a>

[MapLibre](https://maplibre.org/)는 주로 웹 또는 모바일 애플리케이션에서 지도를 표시하기 위한 렌더링 엔진입니다. 하지만 플러그인에 대한 지원도 포함하며 Amazon Location의 다른 측면과 함께 작업할 수 있는 기능도 제공합니다. 다음은 작업하려는 지역 또는 위치를 기반으로 사용할 수 있는 도구를 설명합니다.

**참고**  
Amazon Location의 모든 측면을 사용하려면 [사용하려는 언어의 AWS SDK](dev-by-language.md)를 설치하세요.
+ **맵**

  애플리케이션에 지도를 표시하려면 Amazon Location에서 제공하는 데이터를 사용하고 화면에 그릴 맵 렌더링 엔진이 필요합니다. 맵 렌더링 엔진은 맵을 이동 및 확대하거나 마커, 푸시핀 및 기타 주석을 맵에 추가하는 기능도 제공합니다.

  Amazon Location Service에서는 [MapLibre](https://github.com/maplibre/maplibre-gl-js) 렌더링 엔진을 사용하여 맵을 렌더링할 것을 권장합니다. MapLibre GL JS는 자바스크립트로 지도를 표시하는 엔진이며, MapLibre Native는 iOS 또는 안드로이드용 지도를 제공합니다.

  또한 MapLibre는 핵심 기능을 확장하기 위한 플러그인 에코시스템을 갖추고 있습니다. 자세한 내용은 [https://maplibre.org/maplibre-gl-js/docs/plugins/](https://maplibre.org/maplibre-gl-js/docs/plugins/)를 참조하세요.
+ **Places 검색**

  검색 사용자 인터페이스를 더 간단하게 만들려면 웹용 [MapLibre 지오코더](https://github.com/maplibre/maplibre-gl-geocoder)를 사용할 수 있습니다(Android 애플리케이션은 [Android Places 플러그인](https://github.com/maplibre/maplibre-plugins-android/tree/master/plugin-places)을 사용할 수 있음).

  [Amazon Location for MapLibre 지오코더 라이브러리](https://github.com/aws-geospatial/amazon-location-for-maplibre-gl-geocoder?tab=readme-ov-file)를 사용하여 JavaScript 애플리케이션에서 `amazon-location-for-maplibre-gl-geocoder`와 함께 Amazon Location을 사용하는 프로세스를 간소화합니다.

  자세한 내용은 [Amazon Location MapLibre 지오코더 GL 플러그인 사용](dev-maplibre-geocoder.md) 섹션을 참조하세요.
+ **Routes**
+ **Geofences 및 Trackers**

  MapLibre에는 지오펜스 및 추적을 위한 특정 렌더링 또는 도구가 없지만 렌더링 기능과 [플러그인](https://maplibre.org/maplibre-gl-js/docs/plugins/)을 사용하여 지오펜스와 추적된 장치를 맵에 표시할 수 있습니다.

  추적 대상 디바이스는 [MQTT](tracking-using-mqtt.md)를 사용하거나 Amazon Location Service에 업데이트를 수동으로 전송할 수 있습니다. [AWS Lambda](https://docs.aws.amazon.com/lambda/)을 사용하여 지오펜스 이벤트에 응답할 수 있습니다.

Amazon Location Service에 추가 기능을 제공하는 데 사용할 수 있는 많은 오픈 소스 라이브러리(예: 공간 분석 기능을 제공하는 [Turf](https://github.com/Turfjs/turf))가 있습니다.

많은 라이브러리는 개방형 표준 [GeoJSON](https://geojson.org/) 형식의 데이터를 사용합니다. Amazon Location Service는 JavaScript 애플리케이션에서 사용할 수 있도록 응답을 GeoJSON으로 변환하는 라이브러리를 제공합니다. 자세한 내용은 [Amazon Location Service를 위한 SDK 및 프레임워크](dev-sdks.md) 섹션을 참조하세요.

# 언어별 SDK
<a name="dev-by-language"></a>

**SDK 버전**  
프로젝트에 사용하는 최신 AWS SDK 빌드와 기타 SDK를 사용하고 SDK를 최신 상태로 유지하는 것이 좋습니다. AWS SDK는 최신 특징과 기능과 보안 업데이트도 제공합니다. 예를 들어, JavaScript용 AWS SDK의 최신 빌드를 찾으려면 *JavaScript용 AWS SDK 설명서*의 [브라우저 설치](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html#In_the_Browser) 항목을 참조하세요.

다음 표는 웹, 모바일 또는 백엔드 애플리케이션 등 애플리케이션 유형별로 언어 및 프레임워크용 AWS SDK 및 맵 렌더링 프레임워크 버전에 대한 정보를 제공합니다.

------
#### [ Web frontend ]

웹 프론트엔드 애플리케이션 개발에 사용할 수 있는 AWS SDK 및 맵 렌더링 프레임워크 버전은 다음과 같습니다.


| 언어/프레임워크 | AWS SDK | 맵 렌더링 프레임워크 | 
| --- | --- | --- | 
|  **완전 지원**  | 
|  JavaScript  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  |  [https://github.com/maplibre/maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)  | 
|  ReactJS  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  |  [https://github.com/maplibre/maplibre-react-native](https://github.com/maplibre/maplibre-react-native)  | 
|  TypeScript  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  |  [https://github.com/maplibre/maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)  | 
|  **일부 지원**  | 
|  Flutter  |  [https://docs.amplify.aws/start/q/integration/flutter/](https://docs.amplify.aws/start/q/integration/flutter/) Flutter는 아직 완전히 지원되지는 않지만 AWS Amplify를 통한 지원은 제한적입니다.  |  [https://github.com/maplibre/flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl) MapLibre Flutter 라이브러리는 실험적인 것으로 간주됩니다.  | 
|  Node.js  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  | [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native) [https://www.npmjs.com/package/@maplibre/maplibre-gl-native](https://www.npmjs.com/package/@maplibre/maplibre-gl-native) | 
|  PHP  |  [https://aws.amazon.com/sdk-for-php/](https://aws.amazon.com/sdk-for-php/)  |  PHP에 대한 MapLibre 지원은 없습니다.  | 

------
#### [ Mobile frontend ]

모바일 프론트엔드 애플리케이션 개발에 사용할 수 있는 AWS SDK 및 맵 렌더링 프레임워크 버전은 다음과 같습니다.


| 언어/프레임워크 | AWS SDK | 맵 렌더링 프레임워크 | 
| --- | --- | --- | 
|  **완전 지원**  | 
|  Java  |  [https://aws.amazon.com/sdk-for-java/](https://aws.amazon.com/sdk-for-java/)  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  Kotlin  |  [https://aws.amazon.com/sdk-for-kotlin/](https://aws.amazon.com/sdk-for-kotlin/)  Android용 Amazon Location Service Mobile Authentication SDK: [https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-android](https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-android) Android용 Amazon Location Service Mobile Tracking SDK: [https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-android](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-android)  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native) MapLibre는 Java 기반이므로 사용자 지정 바인딩이 필요합니다.  | 
|  ObjectiveC  |  [https://github.com/aws-amplify/aws-sdk-ios](https://github.com/aws-amplify/aws-sdk-ios)  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  ReactNative  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  |  [https://github.com/maplibre/maplibre-react-native](https://github.com/maplibre/maplibre-react-native)  | 
|  Swift  |  [https://aws.amazon.com/sdk-for-swift/](https://aws.amazon.com/sdk-for-swift/) iOS용 Amazon Location Service Mobile Authentication SDK: [https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios](https://github.com/aws-geospatial/amazon-location-mobile-auth-sdk-ios) iOS용 Amazon Location Service Mobile Tracking SDK: [https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios](https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios)  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  **일부 지원**  | 
|  Flutter  |  [https://docs.amplify.aws/start/q/integration/flutter/](https://docs.amplify.aws/start/q/integration/flutter/) Flutter는 아직 완전히 지원되지는 않지만 AWS Amplify를 통한 지원은 제한적입니다.  |  [https://github.com/maplibre/flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl) MapLibre Flutter 라이브러리는 실험적인 것으로 간주됩니다.  | 

------
#### [ Backend application ]

백엔드 애플리케이션 개발에 사용할 수 있는 AWS SDK는 다음과 같습니다. 맵 렌더링은 일반적으로 백엔드 애플리케이션에 필요하지 않기 때문에 맵 렌더링 프레임워크는 여기에 열거되지 않았습니다.


| 언어 | AWS SDK | 
| --- | --- | 
|  .NET  |  [https://aws.amazon.com/sdk-for-net/](https://aws.amazon.com/sdk-for-net/)  | 
|  C\$1\$1  |  [https://aws.amazon.com/sdk-for-cpp/](https://aws.amazon.com/sdk-for-cpp/)  | 
|  Go  |  [https://aws.amazon.com/sdk-for-go/](https://aws.amazon.com/sdk-for-go/)  | 
|  Java  |  [https://aws.amazon.com/sdk-for-java/](https://aws.amazon.com/sdk-for-java/)  | 
|  JavaScript  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  | 
|  Node.js  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  | 
|  TypeScript  |  [https://aws.amazon.com/sdk-for-javascript/](https://aws.amazon.com/sdk-for-javascript/)  | 
|  Kotlin  |  [https://aws.amazon.com/sdk-for-kotlin/](https://aws.amazon.com/sdk-for-kotlin/)  | 
|  PHP  |  [https://aws.amazon.com/sdk-for-php/](https://aws.amazon.com/sdk-for-php/)  | 
|  Python  |  [https://aws.amazon.com/sdk-for-python/](https://aws.amazon.com/sdk-for-python/)  | 
|  Ruby  |  [https://aws.amazon.com/sdk-for-ruby/](https://aws.amazon.com/sdk-for-ruby/)  | 
|  Rust  |  [https://aws.amazon.com/sdk-for-rust/](https://aws.amazon.com/sdk-for-rust/) Rust용 AWS SDK는 개발자 평가판으로 제공됩니다.  | 

------

# 언어별 맵 렌더링 SDK
<a name="map-rendering-by-language"></a>

[MapLibre](https://github.com/maplibre/maplibre-gl-js) 렌더링 엔진을 사용하여 Amazon Location Service 맵을 렌더링하도록 권장합니다.

MapLibre는 웹 또는 모바일 애플리케이션에서 맵을 표시하기 위한 엔진입니다. 또한 MapLibre에는 플러그인 모델이 있으며 일부 언어와 플랫폼에서 검색 및 경로를 위한 사용자 인터페이스를 지원합니다.

MapLibre 사용 및 MapLibre에서 제공하는 기능에 대한 자세한 내용은 [Amazon Location에서 MapLibre 도구 및 관련 라이브러리 사용](dev-maplibre.md) 및 [동적 맵을 사용하는 방법](dynamic-maps-how-to.md) 섹션을 참조하세요.

다음 표는 웹 및 모바일 애플리케이션 등의 애플리케이션 유형별로 언어 및 프레임워크용 맵 렌더링 SDK 버전에 대한 정보를 제공합니다.

------
#### [ Web frontend ]

웹 프론트엔드 애플리케이션 개발에 사용할 수 있는 맵 렌더링 SDK는 다음과 같습니다.


| 언어/프레임워크 | 맵 렌더링 프레임워크 | 
| --- | --- | 
|  **완전 지원**  | 
|  JavaScript  |  [https://github.com/maplibre/maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)  | 
|  ReactJS  |  [https://github.com/maplibre/maplibre-react-native](https://github.com/maplibre/maplibre-react-native)  | 
|  TypeScript  |  [https://github.com/maplibre/maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)  | 
|  **일부 지원**  | 
|  Flutter  |  [https://github.com/maplibre/flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl) MapLibre Flutter 라이브러리는 실험적인 것으로 간주됩니다.  | 
|  Node.js  |   Node.js에 대한 MapLibre 지원은 없습니다.  | 
|  PHP  |   PHP에 대한 MapLibre 지원은 없습니다.  | 

------
#### [ Mobile frontend ]

모바일 프론트엔드 애플리케이션 개발에 사용할 수 있는 맵 렌더링 SDK는 다음과 같습니다.


| 언어/프레임워크 | 맵 렌더링 프레임워크 | 
| --- | --- | 
|  **완전 지원**  | 
|  Java  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  Kotlin  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native) MapLibre는 Java 기반이므로 사용자 지정 바인딩이 필요합니다.  | 
|  ObjectiveC  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  ReactNative  |  [https://github.com/maplibre/maplibre-react-native](https://github.com/maplibre/maplibre-react-native)  | 
|  Swift  |  [https://github.com/maplibre/maplibre-native](https://github.com/maplibre/maplibre-native)  | 
|  **일부 지원**  | 
|  Flutter  |  [https://github.com/maplibre/flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl) MapLibre Flutter 라이브러리는 실험적인 것으로 간주됩니다.  | 

------

# 주소 양식 SDK
<a name="address-form-sdk"></a>

Address Form SDK는 스마트 주소 입력 양식 구축을 간소화합니다. SDK로 빌드된 주소 양식은 사용자가 입력을 시작할 때 관련 주소 제안을 제공합니다. 사용자가 제안을 선택하면 주소 양식이 도시, 주, 우편 번호와 같은 필드를 자동으로 채웁니다. 이렇게 하면 수동 입력을 최소화하여 오류를 줄이고 데이터 입력 속도를 높일 수 있습니다. 또한 사용자는 맵에서 선택한 주소를 미리 보고 위치 핀을 조정하여 특정 입구 또는 픽업 위치를 표시할 수 있으므로 정확도가 크게 향상됩니다.

![\[자동 완성 기능을 보여주는 Address Form SDK 데모\]](http://docs.aws.amazon.com/ko_kr/location/latest/developerguide/images/address-form-demo.gif)


## 사용해 보기
<a name="address-form-try-it"></a>

### 데모
<a name="address-form-demo"></a>

완전한 기능을 갖춘 [주소 양식 데모](https://aws-geospatial.github.io/address-form-sdk-js/)를 사용해 보세요.

### 직접 빌드
<a name="address-form-builder"></a>

[시작하기](#address-form-getting-started) 로 이동하여 주소 양식 SDK를 사용하여 주소 양식 구현을 시작하거나이 SDK로 구동되고 [https://console.aws.amazon.com/location/](https://console.aws.amazon.com/location/) Amazon Location Service 콘솔에서 액세스할 수 있는 Location Service의 WYSIWYG [주소 양식 빌더 마법사](https://console.aws.amazon.com/location/solution-builder/home#/address-form)를 사용하여 코드 없는 접근 방식을 시도합니다. 이 대화형 마법사를 사용하면 예측 제안, 자동 필드 모집단 및 유연한 레이아웃을 사용하여 사용자 지정 양식을 생성할 수 있습니다. 개발자는 코드를 작성하지 않고도 쉽게 통합할 수 있도록 ready-to-use 수 있는 패키지를 React JavaScript, React TypeScript 또는 독립 실행형 HTML/JavaScript로 다운로드할 수 있습니다.

## 주요 기능
<a name="address-form-features"></a>

Address Form SDK의 주요 기능은 다음과 같습니다.
+ 주소 및 POIs에 대한 기본 제공 형식 미리 제안을 제공하여 데이터 입력 속도를 높입니다.
+ 보다 정확한 결과를 위해 구성 가능한 장소 유형 검색(예: 우편 번호, 지역)을 활성화합니다.
+ 사용자가 현재 영역을 빠르게 중앙에 배치할 수 있도록 자동 브라우저 위치 감지 기능을 제공합니다.
+ 명확성과 컨텍스트를 높이기 위해 내장 맵 시각화를 표시합니다.
+ 시스템에서 제공한 위치를 잃지 않고 맵에서 주소 위치를 조정할 수 있으므로 정확도와 제어가 모두 보장됩니다.
+ 코딩이 필요 없는 WYSIWYG 빌더 도구가 포함되어 있어 시간과 노력을 절약할 수 있습니다.
+ 미리 입력 APIs에 대한 디바운싱 및 캐싱을 구현하여 성능을 최적화하고 비용을 절감합니다.
+ 애플리케이션의 브랜드 및 사용자 경험에 맞게 스타일 사용자 지정을 지원합니다.

다음 Amazon Location Service API 작업을 사용하여 주소 양식에 주소 정보를 제공합니다.

**[GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html)**  
대화형 맵을 렌더링하기 위한 맵 타일을 검색하여 주소의 위치를 시각화하고 주소의 위치를 조정합니다.

**[Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html)**  
실시간 주소 제안을 사용자 유형으로 제공합니다.

**[Suggest](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html)**  
실시간 주소 및 POI 제안을 사용자 유형으로 제공합니다.

**[ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html)**  
현재 위치에 따라 주소를 자동으로 채우도록 선택한 경우 사용자의 현재 위치를 가장 가까운 알려진 주소 주소로 변환합니다.

**[GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html)**  
자동 완성 또는 제안 API의 결과에서 주소를 선택한 후 선택한 주소에 대한 자세한 장소 정보를 검색합니다.

## 가격 책정
<a name="address-form-pricing"></a>

SDK는 Apache-2.0 라이선스에 따라 무료 [오픈 소스](https://github.com/aws-geospatial/address-form-sdk-js)입니다. API 사용량에 대해서만 비용을 지불합니다. [Amazon Location Service 요금 페이지를](https://aws.amazon.com/location/pricing/) 참조하세요.

## 시작하기
<a name="address-form-getting-started"></a>

주소 양식 SDK는 React 앱 또는 독립 실행형 HTML 및 JavaScript 페이지에서 사용할 수 있습니다. 아래 지침에 따라 시작합니다.

### 사전 조건
<a name="address-form-prerequisites"></a>

**참고**  
주소 양식 SDK가 제대로 작동하려면 필요한 권한이 있는 API 키가 필요합니다. Amazon Location Service 콘솔의 [Address Form SDK Builder 마법사](https://console.aws.amazon.com/location/solution-builder/home#/address-form)를 사용하여 다음 권한을 가진 API 키를 생성하거나 아래 지침에 따라 수동으로 생성합니다.

주소 양식 SDK를 사용하려면 API 키 정책에서 다음 작업을 허용해야 합니다.
+ `geo-maps:GetTile` - 맵 구성 요소를 표시할 때 필요합니다. [GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html) API 참조를 참조하세요.
+ `geo-places:Autocomplete` - 미리 입력 기능에 `Autocomplete` 작업을 사용할 때 필요합니다. [자동 완성](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) API 참조를 참조하세요.
+ `geo-places:Suggest` - 미리 입력 기능에 `Suggest` 작업을 사용할 때 필요합니다. [제안](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html) API 참조를 참조하세요.
+ `geo-places:ReverseGeocode` - 사용자가 브라우저의 지리적 위치 API를 사용하여 현재 위치를 제공하도록 허용할 때 필요합니다. [ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html) API 참조를 참조하세요.
+ `geo-places:GetPlace` - 미리 입력 기능을 사용할 때 필요합니다. [GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html) API 참조를 참조하세요.

[API 키를 사용하여 인증](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html) 가이드에 따라 필요한 권한이 있는 Amazon Location Service API 키를 생성합니다.

필요한 권한이 있는 [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html) API의 키 정책 예제:

#### 주소 양식 권한에 대한 CreateKey 요청
<a name="createkey-example"></a>

```
{
  "KeyName": "ExampleKey",
  "ExpireTime": "YYYY-MM-DDThh:mm:ss.sss",
  "Restrictions": {
    "AllowActions": [
      "geo-maps:GetTile",
      "geo-places:Autocomplete",
      "geo-places:Suggest",
      "geo-places:GetPlace",
      "geo-places:ReverseGeocode"
    ],
    "AllowResources": [
      "arn:aws:geo-maps:<Region>::provider/default",
      "arn:aws:geo-places:<Region>::provider/default"
    ]
  }
}
```

### 설치
<a name="address-form-installation"></a>

#### HTML/JavaScript
<a name="address-form-html-js-install"></a>

HTML 코드에 SDK에 대한 다음 CSS 및 JavaScript 포함

```
...
<head>
...
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
/>
...
</head>
...
<body>
...
<script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
</body>
...
```

#### React
<a name="address-form-react-install"></a>

npm에서 SDK를 설치합니다. `npm install @aws/address-form-sdk-js` 

### SDK 사용
<a name="address-form-use-sdk"></a>

React 앱에 다음 코드를 추가합니다. API 키 `AMAZON_LOCATION_API_KEY` 및 API 키가 생성된 리전`AMAZON_LOCATION_REGION`으로를 업데이트합니다. 양식이 제출되면 `onSubmit` 콜백은 `getData` 비동기 함수를 제공합니다. 이 함수를 `intendedUse` 값으로 호출하여 양식 데이터를 검색합니다.

```
onSubmit: async (getData) => {
  const data = await getData({
    intendedUse: "SingleUse", // or "Storage"
  });
};
```

**참고**  
결과를 저장하거나 캐싱해야 하는 `"Storage"` 경우를 사용합니다. 이렇게 하면 Amazon Location Service[의 용도 요구 사항을](https://docs.aws.amazon.com/location/latest/developerguide/places-intended-use.html) 준수할 수 있습니다.

------
#### [ HTML/JavaScript ]

```
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Address Form</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
    />
  </head>
  <body>
    <form
      id="amazon-location-address-form"
      class="address-form flex-row flex-1"
    >
      <div class="flex-column">
        <input
          data-type="address-form"
          name="addressLineOne"
          data-api-name="suggest"
          data-show-current-location="true"
        />
        <input data-type="address-form" name="addressLineTwo" />
        <input data-type="address-form" name="city" />
        <input data-type="address-form" name="province" />
        <input data-type="address-form" name="postalCode" />
        <input data-type="address-form" name="country" />
        <div class="flex-row">
          <button data-type="address-form" type="submit">Submit</button>
          <button data-type="address-form" type="reset">Reset</button>
        </div>
      </div>
      <div data-type="address-form" data-map-style="Standard,Light"></div>
    </form>
    <></script>
script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"
    <script>
      AddressFormSDK.render({
        root: "#amazon-location-address-form",
        apiKey: "AMAZON_LOCATION_API_KEY",
        region: "AMAZON_LOCATION_REGION",
        showCurrentCountryResultsOnly: true,
        onSubmit: async (getData) => {
          // Get form data with intendedUse parameter
          // Use "SingleUse" for one-time display only
          // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
          const data = await getData({ intendedUse: "SingleUse" });
          console.log(data);
        },
      });
    </script>
  </body>
</html>
```

------
#### [ React ]

```
import React from 'react';
import { AddressForm, Flex } from "@aws/address-form-sdk-js";

export default function App() {
  return (
    <AddressForm
      apiKey="AMAZON_LOCATION_API_KEY"
      region="AMAZON_LOCATION_REGION"
      onSubmit={async (getData) => {
        // Get form data with intendedUse parameter
        // Use "SingleUse" for one-time display only
        // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
        const data = await getData({ intendedUse: "SingleUse" });
        console.log(data);
      }}
    >
      <Flex
        direction="row"
        flex
      >
        <Flex direction="column">
          <input
            data-api-name="autocomplete"
            data-type="address-form"
            name="addressLineOne"
            placeholder="Enter address"
          />
          <input
            data-type="address-form"
            name="addressLineTwo"
          />
          <input
            data-type="address-form"
            name="city"
            placeholder="City"
          />
          <input
            data-type="address-form"
            name="province"
            placeholder="State/Province"
          />
          <input
            data-type="address-form"
            name="postalCode"
          />
          <input
            data-type="address-form"
            name="country"
            placeholder="Country"
          />
          <Flex direction="row">
            <button address-form="submit">
              Submit
            </button>
            <button address-form="reset">
              Reset
            </button>
          </Flex>
        </Flex>
        <AddressFormMap
          mapStyle={[
            'Standard',
            'Light'
          ]}
         />
      </Flex>
    </AddressForm>
  );
}
```

------

## 지원되는 국가
<a name="address-form-supported-countries"></a>

주소 양식 SDK는 Amazon Location Service를 사용하여 전역적으로 주소 자동 채우기를 지원합니다. 다음 국가는 주소 필드 구문 분석을 완벽하게 지원합니다. 여기서 각 주소 구성 요소는 해당 필드에 채워집니다.
+ 오스트레일리아(AU)
+ 캐나다(CA)
+ 프랑스(FR)
+ 홍콩(HK)
+ 아일랜드(IE)
+ 뉴질랜드(NZ)
+ 필리핀(PH)
+ 싱가포르(SG)
+ 영국(GB)
+ 미국(US)

다른 모든 국가는 미리 보기 상태입니다. 미리 보기 국가는 국가별 형식 없이 `addressLineOne` 필드에 전체 주소를 표시합니다. 향후 릴리스는 이러한 동작을 개선하고 최신 버전의 SDK를 사용하여 이러한 개선 사항에 액세스할 수 있습니다.

## 지원되는 AWS 리전
<a name="address-form-supported-aws-regions"></a>

Address Form SDK 및 Address Form Builder 마법사는 API `Current` 버전을 사용하여 Amazon Location Service가 운영되는 모든 AWS 리전에서 사용할 수 APIs. [Amazon Location 지원 리전에서 지원되는 리전](https://docs.aws.amazon.com/location/latest/developerguide/location-regions.html)의 전체 목록을 봅니다.

## API 참조
<a name="address-form-api-reference"></a>

[README API 참조를 참조하세요](https://github.com/aws-geospatial/address-form-sdk-js#api-reference).