모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Maps JavaScript API 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Maps JavaScript API 및 관련 서비스 활성화
  3. 적합한 키 생성
계속

버전 관리

Google Maps JavaScript API 팀은 새로운 기능, 버그 수정, 성능 개선으로 API를 정기적으로 업데이트합니다. 이 페이지에서는 테스트 환경이나 프로덕션 환경에 상관없이 여러분의 애플리케이션에서 사용할 수 있는 API 버전에 대해 설명합니다. API 버전은 다음과 같은 이름을 가집니다.

  • 시험용
  • 릴리스
  • 동결

또한, 애플리케이션의 유형이나 목적에 따라 버전 관리 절차를 관리하는 모범 사례를 제공합니다.

버전 롤오버 및 버전 유형

저희는 매 분기마다 새로운 번호의 버전을 제공하고 공개적으로 사용할 수 있도록 시험용 버전으로 릴리스합니다. 동시에 이전 시험용 버전은 릴리스 버전이 되고, 이전 릴리스 버전은 동결 버전이 됩니다. 이 프로세스를 버전 롤오버라고 합니다.

분기 내내 시험용 버전과 릴리스 버전에 지속적으로 버그 수정을 추가합니다. 이러한 업데이트는 Google Maps JavaScript API 릴리스 노트에 기록됩니다.

Google Maps JavaScript API 부트스트랩 요청의 v 매개변수를 지정하여 애플리케이션에서 로드할 API의 버전을 나타낼 수 있습니다. 다음과 같은 옵션이 지원됩니다.

  • v=3.exp로 지정된 시험용 버전.
  • v=3으로 지정된 릴리스 버전.
  • 특정 버전 번호. 예: v=3.25 또는 v=3.26.

버전을 명확히 지정하지 않을 경우 기본 플랜 고객(키를 제공하지 않는 고객 포함)은 기본적으로 시험용 버전을 받습니다. 프리미엄 플랜을 이용하는 고객이 버전을 지정하지 않는다면 기본적으로 릴리스 버전을 받습니다.

시험용 버전

시험용 버전(현재 3.27)에는 공개적으로 사용 가능한 최신 기능과 버그 수정이 포함됩니다. 실험 버전에 적용된 변경 사항은 안정적인 기능을 보장하지 않습니다. 시험용 버전으로 애플리케이션을 정기 테스트하는 것이 좋습니다. API를 로드할 때 v=3.27를 추가하면 됩니다. 위험을 감수할 수 있을 경우, v=3.exp를 추가하면 항상 모든 최신 기능이 포함된 최신 시험용 버전을 받을 수 있습니다.

다음 부트스트랩으로 시험용 버전을 지정할 수 있습니다.

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.exp
        &key=YOUR_API_KEY&callback=initMap">

릴리스 버전

우리는 기능 집합을 안정적으로 유지하면서 릴리스 버전에 지속적으로 버그 수정을 적용합니다. 수정 사항은 릴리스 노트에 기록됩니다.

현재 릴리스 버전은 3.26입니다. 다음 부트스트랩 중 하나로 요청할 수 있습니다.

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3
        &key=YOUR_API_KEY&callback=initMap">

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.26
        &key=YOUR_API_KEY&callback=initMap">

동결 버전

새로운 번호가 붙은 버전을 릴리스할 때 이전 릴리스 버전을 동결합니다. 즉, 더 이상 정기적 버그 수정으로 업데이트하지 않습니다. 그러나 법적 사유 등이 있을 때는 가끔 변경할 수도 있습니다.

새로운 동결 버전이 생길 때마다 이전 동결 버전을 사용 중단합니다. v=3.0 등과 같이 사용이 중단된 버전을 지정하면, 언제나 현재 동결 버전을 반환합니다.

현재 동결 버전은 3.25입니다. 다음 부트스트랩으로 요청할 수 있습니다.

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.25
        &key=YOUR_API_KEY&callback=initMap">

모범 사례

Google Maps JavaScript API 팀은 API의 여러 버전에서 호환성을 유지하기 위해 최선을 다합니다. 그러나 운영상의 사유 및 최신 서비스를 지속적으로 제공하기 위해 간혹 기존 기능과 상호작용하는 기능을 변경하는 경우도 있습니다. 이러한 경우, 특히 고급 애플리케이션의 경우에는 코드가 기대대로 작동하도록 Google Maps JavaScript API를 사용하여 수정해야 할 필요가 있습니다. 다양한 일반적인 시나리오에서 버전 사용에 대한 권장 모범 사례를 아래에서 제시합니다.

가용성/트래픽이 높은 애플리케이션의 경우

안정성과 가용성을 보장하기 위해 추가 작업을 수행할 의사가 있는 경우

버전 롤오버에서 문제가 발생하지 않도록 부트스트랩에서 API의 현재 릴리스 버전 번호를 명시적으로 지정하는 것이 좋습니다. 예: v=3.26. 시간이 지나면서 API의 동결 버전으로 분류되지 않도록 Google Maps JS API v3 Notifications and Announcements 그룹에서 Google의 버전 롤오버 알림을 구독하는 것이 중요합니다.

버전 롤오버가 있은 후에는(매 분기) 개발자의 프로덕션 시스템이 API의 동결 버전을 요청합니다. 이때는 API의 새로운 릴리스 버전으로 애플리케이션을 테스트할 수 있도록 스테이징/개발 환경을 설정하는 것이 좋습니다. 문제가 발생하면 코드에서 필요한 내용을 수정할 수 있습니다. 애플리케이션이 새 API 릴리스 버전에서 원활하게 작동할 것으로 확신하면, 애플리케이션을 업데이트하는 동시에 필요한 수정 사항(있을 경우)을 적용하여 새 릴리스 버전에 해당하는 버전 번호를 요청할 수 있습니다.

일반 애플리케이션의 경우

부트스트랩 요청에서 v=3를 지정하도록 권장합니다. 그러면 이미 대량의 트래픽을 경험하고 필요한 버그 수정이 적용된 Google Maps JavaScript API의 최신 릴리스 버전을 받을 수 있습니다. 대부분의 경우, 버전 롤오버 시 아무런 작업도 필요 없어야 합니다. 그러나 애플리케이션이 지속적으로 원활히 작동할 수 있도록 Google Maps JS API v3 Notifications and Announcements 그룹에서 Google의 버전 롤오버 알림을 구독하는 것이 좋습니다.

롤오버가 발생한 후에 애플리케이션이 새로운 버전의 Google Maps JavaScript API를 사용하게 됩니다. 릴리스 노트를 참고하여 여러분에게 영향을 미칠 수 있는 변경 사항을 알아볼 수도 있습니다. 애플리케이션 내에서 올바르게 작동하지 않는 것이 발견되면, 필요에 따라 코드를 수정하는 동안 부트스트랩 요청에서 현재 동결 버전의 번호를 명시적으로 지정하여 구 버전으로 전환할 수 있습니다.

첨단 애플리케이션의 경우

최신 기능에 신속히 액세스하고자 할 경우

지속적인 가용성이 덜 중요한 애플리케이션의 경우, Google Maps JavaScript API의 시험용 버전(v=3.exp)을 요청하여 모든 최신 기능을 얻는 것이 좋습니다. 시험용 버전은 매주 릴리스 전에 Google이 철저히 테스트하며, 일반적으로 상당히 안정적입니다. 그러나 매주 릴리스 주기는 애플리케이션이 지속적으로 기대대로 작동하게 하려면 더욱 신중을 기해야 함을 의미합니다.

버전 검사

디버깅 시에는 google.maps.version 속성을 사용하여 애플리케이션에서 Google Maps JavaScript API의 최신 버전을 받습니다. 다음 코드 샘플은 브라우저 콘솔에 API 버전을 기록합니다. (브라우저 콘솔에 대한 자세한 내용은 브라우저에서 오류 확인을 참조하세요.)

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

API 버전 관련 문서

개발자 가이드는 항상 시험용 버전을 설명합니다.

또한, 각 버전에 대해 별도로 관리되는 참조가 있습니다.

다음에 대한 의견 보내기...

Google Maps JavaScript API
Google Maps JavaScript API
도움이 필요하시나요? 지원 페이지를 방문하세요.