Mengupgrade Aplikasi Maps JavaScript API dari V2 ke V3

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Maps JavaScript API v2 tidak lagi tersedia mulai 26 Mei 2021. Akibatnya, peta v2 situs Anda akan berhenti berfungsi dan akan menampilkan error JavaScript. Untuk terus menggunakan peta di situs Anda, lakukan migrasi ke Maps JavaScript API v3. Panduan ini akan membantu Anda melalui proses tersebut.

Ringkasan

Setiap aplikasi akan memiliki proses migrasi yang sedikit berbeda; Namun, ada beberapa langkah yang sama untuk semua project:

  1. Dapatkan kunci baru. Maps JavaScript API kini menggunakan Google Cloud Console untuk mengelola kunci. Jika masih menggunakan kunci v2, pastikan Anda mendapatkan kunci API baru sebelum memulai migrasi.
  2. Update Bootstrap API. Sebagian besar aplikasi akan memuat Maps JavaScript API v3 dengan kode berikut:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. Perbarui kode Anda. Jumlah perubahan yang diperlukan akan sangat bergantung pada aplikasi Anda. Perubahan umum mencakup:
    • Selalu referensikan namespace google.maps. Di v3, semua kode Maps JavaScript API disimpan di namespace google.maps.*, bukan namespace global. Sebagian besar objek juga telah diganti namanya sebagai bagian dari proses ini. Misalnya, Anda akan memuat google.maps.Map, bukan GMap2.
    • Hapus semua referensi ke metode yang tidak digunakan lagi. Sejumlah metode utilitas tujuan umum telah dihapus, seperti GDownloadURL dan GLog. Ganti fungsionalitas ini dengan library utilitas pihak ketiga, atau hapus referensi ini dari kode Anda.
    • (Opsional) Tambahkan library ke kode Anda. Banyak fitur yang telah dieksternalkan ke dalam library utilitas sehingga setiap aplikasi hanya perlu memuat bagian API yang akan digunakan.
    • (Opsional) Konfigurasikan project Anda untuk menggunakan externs v3. Externs v3 dapat digunakan untuk membantu memvalidasi kode Anda dengan Closure Compiler, atau untuk memicu pelengkapan otomatis di IDE. Pelajari lebih lanjut Kompilasi Lanjutan dan Eksternal.
  4. Uji dan iterasi. Pada titik ini Anda masih memiliki beberapa pekerjaan yang harus dilakukan, tetapi kabar baiknya adalah, Anda akan segera menuju aplikasi peta v3 baru Anda!

Perubahan pada V3 Maps JavaScript API

Sebelum merencanakan migrasi, Anda harus meluangkan waktu untuk memahami perbedaan antara Maps JavaScript API v2 dan Maps JavaScript API v3. Versi terbaru Maps JavaScript API telah ditulis dari awal, dengan fokus pada teknik pemrograman JavaScript modern, peningkatan penggunaan library, dan API yang disederhanakan. Banyak fitur baru yang telah ditambahkan ke API, dan beberapa fitur yang dikenal telah diubah atau bahkan dihapus. Bagian ini menyoroti beberapa perbedaan utama antara kedua rilis tersebut.

Beberapa perubahan dalam API v3 meliputi:

  • Pustaka inti yang efisien. Banyak fungsi tambahan telah dipindahkan ke library, membantu mengurangi waktu pemuatan dan penguraian untuk Core API yang memungkinkan peta Anda dimuat dengan cepat di perangkat apa pun.
  • Peningkatan performa beberapa fitur, seperti rendering poligon dan penempatan penanda.
  • Pendekatan baru terhadap batas penggunaan sisi klien agar dapat mengakomodasi alamat bersama yang digunakan oleh proxy seluler dan firewall perusahaan dengan lebih baik.
  • Penambahan dukungan untuk beberapa browser modern dan browser seluler. Dukungan untuk Internet Explorer 6 telah dihapus.
  • Menghapus banyak class helper tujuan umum ( GLog atau GDownloadUrl). Saat ini, ada banyak library JavaScript luar biasa yang menyediakan fungsi serupa, seperti Closure atau jQuery.
  • Implementasi HTML5 Street View yang akan dimuat pada semua perangkat seluler.
  • Panorama Street View Khusus dengan foto Anda sendiri, yang memungkinkan Anda berbagi panorama lereng ski, rumah dijual, atau tempat menarik lainnya.
  • Penyesuaian Maps Bergaya yang memungkinkan Anda mengubah tampilan elemen pada peta dasar agar cocok dengan gaya visual unik Anda.
  • Dukungan untuk beberapa layanan baru, seperti ElevationService dan Distance Matrix.
  • Layanan rute yang ditingkatkan memberikan rute alternatif, pengoptimalan rute (perkiraan solusi untuk masalah staf penjualan yang bepergian), rute sepeda (dengan lapisan bersepeda), rute transportasi umum, dan rute yang dapat ditarik.
  • Format Geocoding yang diperbarui yang memberikan informasi jenis yang lebih akurat daripada nilai accuracy dari Geocoding API v2.
  • Dukungan untuk beberapa Jendela Info pada satu Peta

Meningkatkan Versi Aplikasi Anda

Kunci Baru Anda

Maps JavaScript API v3 menggunakan sistem kunci baru dari v2. Anda mungkin sudah menggunakan kunci v3 dengan aplikasi, sehingga perubahan tidak diperlukan. Untuk memverifikasi, periksa URL tempat Anda memuat Maps JavaScript API untuk parameter key-nya. Jika nilai kunci dimulai dengan 'ABQIAA', berarti Anda menggunakan kunci v2. Jika memiliki kunci v2, Anda harus mengupgrade ke kunci v3 sebagai bagian dari migrasi, yang akan:

Kunci ini diteruskan saat memuat Maps JavaScript API v3. Pelajari cara membuat kunci API lebih lanjut.

Perhatikan bahwa jika Anda adalah pelanggan Google Maps API for Work, Anda mungkin menggunakan client ID dengan parameter client, bukan menggunakan parameter key. Client ID masih didukung di Maps JavaScript API v3 dan tidak perlu melalui proses upgrade kunci.

Memuat API

Modifikasi pertama yang perlu Anda lakukan pada kode Anda melibatkan cara Anda memuat API. Di v2, Anda memuat Maps JavaScript API melalui permintaan ke http://maps.google.com/maps. Jika memuat Maps JavaScript API v3, Anda harus membuat perubahan berikut:

  1. Memuat API dari //maps.googleapis.com/maps/api/js
  2. Hapus parameter file.
  3. Perbarui parameter key dengan kunci v3 baru. Pelanggan Google Maps API for Work harus menggunakan parameter client.
  4. (Khusus Premium Plan Google Maps Platform) Pastikan parameter client diberikan seperti yang dijelaskan dalam Panduan Developer Premium Plan Google Maps Platform.
  5. Hapus parameter v untuk meminta versi terbaru yang dirilis atau ubah nilainya sesuai dengan skema pembuatan versi v3.
  6. (Opsional) Ganti parameter hl dengan language dan pertahankan nilainya.
  7. (Opsional) Tambahkan parameter libraries untuk memuat library opsional.

Dalam kasus yang paling sederhana, bootstrap v3 hanya akan menentukan parameter kunci API Anda:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

Contoh di bawah ini meminta versi terbaru Maps JavaScript API v2 dalam bahasa Jerman:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

Contoh di bawah adalah permintaan ekuivalen untuk v3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

Memperkenalkan namespace google.maps

Mungkin perubahan yang paling mencolok dalam Maps JavaScript API v3 adalah pengenalan namespace google.maps. API v2 menempatkan semua objek dalam namespace Global secara default, yang dapat mengakibatkan konflik penamaan. Dalam v3, semua objek berada dalam namespace google.maps.

Saat memigrasikan aplikasi ke v3, Anda harus mengubah kode untuk menggunakan namespace baru. Sayangnya, menelusuri "G" dan mengganti dengan "google.maps." tidak akan berhasil sepenuhnya; namun, praktik terbaik yang berlaku adalah berlaku saat meninjau kode Anda. Berikut adalah beberapa contoh class yang setara dalam v2 dan v3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Membuang Kode yang Tidak Terpakai

Maps JavaScript API v3 memiliki paralel untuk sebagian besar fungsionalitas di v2; namun, ada beberapa class yang tidak lagi didukung. Sebagai bagian dari migrasi, Anda harus mengganti class ini dengan library utilitas pihak ketiga, atau menghapus referensi ini dari kode. Ada banyak library JavaScript luar biasa yang menyediakan fungsi serupa, seperti Closure atau jQuery.

Class berikut tidak memiliki kesamaan dalam Maps JavaScript API v3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Membandingkan Kode

Mari kita bandingkan dua aplikasi yang agak sederhana yang telah ditulis dengan API v2 dan v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

Seperti yang Anda lihat, ada beberapa perbedaan antara kedua aplikasi tersebut. Perubahan penting meliputi:

  • Alamat dari mana API dimuat telah berubah.
  • Metode GBrowserIsCompatible() dan GUnload() tidak lagi diperlukan di v3, dan telah dihapus dari API.
  • Objek GMap2 digantikan oleh google.maps.Map sebagai objek pusat dalam API.
  • Properti sekarang dimuat melalui kelas Options. Pada contoh di atas, kita menetapkan tiga properti yang diperlukan untuk memuat peta — center, zoom, dan mapTypeId — melalui objek MapOptions yang inline.
  • UI default aktif secara default dalam v3. Anda dapat menonaktifkannya dengan menetapkan properti disableDefaultUI ke true di objek MapOptions.

Ringkasan

Pada tahap ini, Anda telah memahami beberapa poin penting yang terlibat dalam migrasi dari Maps JavaScript API ke v2 ke v3. Ada lebih banyak informasi yang mungkin perlu Anda ketahui, tetapi bergantung pada aplikasi Anda. Di bagian berikut, kami telah menyertakan petunjuk migrasi untuk kasus tertentu yang mungkin Anda temui. Selain itu, ada beberapa referensi yang mungkin dapat membantu Anda selama proses upgrade.

  • Maps JavaScript API v3 Dokumentasi Developer adalah tempat terbaik untuk mempelajari lebih lanjut API dan cara kerjanya.
  • Maps JavaScript API v3 Referensi akan membantu Anda mempelajari lebih lanjut class dan metode baru di API v3.
  • Komunitas Stack Overflow adalah tempat yang tepat untuk mengajukan pertanyaan terkait kode. Di situs tersebut, pertanyaan dan jawaban yang terkait dengan Maps JavaScript API menggunakan tag 'google-maps' atau 'google-maps-api-3' .
  • Pelanggan Premium Plan Google Maps Platform sebaiknya membaca Dokumentasi Premium Plan Google Maps Platform.
  • Blog Developer Geo Google adalah cara yang tepat untuk mencari tahu tentang perubahan terbaru pada API.

Jika ada masalah atau pertanyaan tentang artikel ini, harap gunakan link KIRIM MASUKAN di bagian atas halaman ini.

Referensi Detail

Bagian ini memberikan perbandingan mendetail tentang fitur yang paling populer untuk Maps JavaScript API untuk v2 dan v3. Setiap bagian referensi dirancang untuk dibaca satu per satu. Sebaiknya Anda tidak membaca referensi ini secara keseluruhan; sebagai gantinya, gunakan materi ini untuk membantu migrasi Anda berdasarkan kasus per kasus.

  • Peristiwa - mendaftarkan dan menangani peristiwa.
  • Kontrol - memanipulasi kontrol navigasi yang muncul pada peta.
  • Overlay - menambahkan dan mengedit objek pada peta.
  • Jenis Peta - ubin yang membentuk peta dasar.
  • Lapisan - menambahkan dan mengedit konten sebagai grup, seperti lapisan KML atau Traffic.
  • Layanan - berfungsi dengan geocoding, rute, atau layanan Street View Google.

Peristiwa

Model peristiwa untuk Maps JavaScript API v3 mirip dengan yang digunakan pada v2, meskipun banyak yang telah berubah di balik layar.

Kontrol

Maps JavaScript API menampilkan kontrol UI yang memungkinkan pengguna berinteraksi dengan peta Anda. Anda dapat menggunakan API untuk menyesuaikan tampilan kontrol ini.

Overlay

Overlay mencerminkan objek yang Anda "tambahkan" ke peta untuk menentukan titik, garis, area, atau kumpulan objek.

Tipe Peta

Jenis peta yang tersedia di v2 dan v3 sedikit berbeda, tetapi semua jenis peta dasar tersedia di kedua versi API. Secara default, v2 menggunakan ubin peta jalan standar "dicat". Namun, v3 memerlukan jenis peta tertentu untuk diberikan saat membuat objek google.maps.Map.

Lapisan

Lapisan adalah objek pada peta yang terdiri dari satu atau beberapa overlay. Objek dapat dimanipulasi sebagai satu unit dan umumnya mencerminkan koleksi objek.

Services (Layanan)