Maps JavaScript API Uygulamanızı V2'den V3'e Yükseltme

Maps JavaScript API 2. sürümü 26 Mayıs 2021'den itibaren kullanılamamaktadır. Sonuç olarak, sitenizin v2 haritaları çalışmayı durdurur ve JavaScript hataları döndürür. Haritaları sitenizde kullanmaya devam etmek için Maps JavaScript API v3'e geçin. Bu kılavuz, işlem boyunca size yol gösterecektir.

Genel Bakış

Her uygulamanın geçiş süreci biraz farklıdır ancak tüm projelerde ortak olan bazı adımlar vardır:

  1. Yeni bir anahtar alın. Maps JavaScript API artık anahtarları yönetmek için Google Cloud Console'u kullanıyor. Hâlâ 2. sürüm anahtarı kullanıyorsanız taşıma işlemine başlamadan önce yeni API anahtarınızı edindiğinizden emin olun.
  2. API Bootstrap'inizi güncelleyin. Çoğu uygulama, Maps JavaScript API v3'ü aşağıdaki kodla yükler:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. Kodu güncelleyin. Gerekli değişiklik miktarı, uygulamanıza bağlı olarak büyük ölçüde değişir. Sık karşılaşılan değişiklikler şunlardır:
    • Her zaman google.maps ad alanını referans olarak kullanın. 3. sürümde, tüm Maps JavaScript API kodu, genel ad alanı yerine google.maps.* ad alanında depolanır. Çoğu nesne de bu sürecin bir parçası olarak yeniden adlandırıldı. Örneğin, GMap2 yerine google.maps.Map yüklenir.
    • Kullanımdan kaldırılmış yöntemlere yapılan tüm referansları kaldırın. GDownloadURL ve GLog gibi bazı genel amaçlı yardımcı program yöntemleri kaldırıldı. Bu işlevi üçüncü taraf yardımcı program kitaplıklarıyla değiştirin veya bu referansları kodunuzdan kaldırın.
    • (İsteğe bağlı) Kodunuza kitaplık ekleyin. Birçok özellik, her uygulamanın yalnızca API'nin kullanılacak bölümlerini yüklemesi gerektiği için yardımcı kitaplıklara aktarıldı.
    • (İsteğe bağlı) Projenizi v3 haricilerini kullanacak şekilde yapılandırın. V3 harici öğeleri, kodunuzu Closure Compiler ile doğrulamanıza veya IDE'nizde otomatik tamamlamayı tetiklemenize yardımcı olmak için kullanılabilir. Gelişmiş Derleme ve Stajyerler hakkında daha fazla bilgi edinin.
  4. Test edin ve tekrarlayın. Bu noktada hâlâ yapmanız gereken bazı işler var ancak yeni v3 harita uygulamanıza doğru iyi bir yoldasınız.

Maps JavaScript API'nin 3. sürümünde yapılan değişiklikler

Taşıma işleminizi planlamadan önce, Haritalar JavaScript API v2 ile Haritalar JavaScript API v3 arasındaki farkları anlamak için zaman ayırmanız gerekir. Maps JavaScript API'nin en yeni sürümü, modern JavaScript programlama tekniklerine, kitaplıkların daha fazla kullanılmasına ve basitleştirilmiş bir API'ye odaklanarak sıfırdan yazılmıştır. API'ye birçok yeni özellik eklendi ve bilinen bazı özellikler değiştirildi ya da kaldırıldı. Bu bölümde, iki sürüm arasındaki temel farklılıklardan bazıları vurgulanmaktadır.

v3 API'deki değişikliklerden bazıları şunlardır:

  • Basitleştirilmiş bir çekirdek kitaplık. Ek işlevlerin çoğu kitaplıklara taşındı. Bu sayede Core API'nin yüklenmesi ve ayrıştırma süreleri azaltıldı. Böylece haritanız tüm cihazlarda hızlı bir şekilde yüklenebilir.
  • Poligon oluşturma ve işaretçi yerleşimi gibi çeşitli özelliklerin performansı iyileştirildi.
  • Mobil proxy'ler ve kurumsal güvenlik duvarları tarafından kullanılan ortak adresleri daha iyi barındırmak için istemci taraflı kullanım sınırlamalarına yönelik yeni bir yaklaşım.
  • Çeşitli modern tarayıcılar ve mobil tarayıcılar için destek eklendi. Internet Explorer 6 desteği kaldırıldı.
  • Genel amaçlı yardımcı sınıfların çoğu kaldırıldı ( GLog veya GDownloadUrl). Günümüzde, Closure veya jQuery gibi benzer işlevler sunan birçok mükemmel JavaScript kitaplığı mevcuttur.
  • Herhangi bir mobil cihazda yüklenecek bir HTML5 Street View uygulaması.
  • Kendi fotoğraflarınızla özel Street View panoramaları oluşturarak kayak pistlerinin, satılık evlerin veya ilgi çekici diğer yerlerin panoramalarını paylaşabilirsiniz.
  • Temel haritadaki öğelerin görüntülenmesini benzersiz görsel stilinize uyacak şekilde değiştirmenize olanak tanıyan stilize haritalar özelleştirmeleri.
  • ElevationService ve Distance Matrix gibi çeşitli yeni hizmetler için destek
  • İyileştirilmiş yol tarifi hizmetleri, alternatif rotalar, rota optimizasyonu ( satıcı seyahati problemine yaklaşık çözümler), bisiklet yol tarifleri ( bisiklet katmanı ile), toplu taşıma yol tarifleri ve sürükle bırak yol tarifleri sunar.
  • Geocoding API v2'deki accuracy değerinden daha doğru tür bilgileri sağlayan güncellenmiş bir coğrafi kodlama biçimi.
  • Tek bir haritada birden fazla bilgi panosunun desteklenmesi

Uygulamanızı Yükseltme

Yeni Anahtarınız

Maps JavaScript API'nin 3. sürümü, 2. sürümdeki yeni bir anahtar sistemini kullanır. Uygulamanızda zaten v3 anahtarı kullanıyor olabilirsiniz. Bu durumda herhangi bir değişiklik yapmanız gerekmez. Doğrulamak için, Maps JavaScript API'yi yüklediğiniz URL'de key parametresini kontrol edin. Anahtar değeri "ABQIAA" ile başlıyorsa v2 anahtarı kullanıyorsunuz demektir. V2 anahtarınız varsa taşıma işleminin bir parçası olarak anahtarınızı v3 sürümüne geçirmeniz gerekir. Bu işlem sonucunda:

Anahtar, Maps JavaScript API v3 yüklenirken iletilir. API anahtarları oluşturma hakkında daha fazla bilgi edinin.

İş için Google Haritalar API'leri müşterisiyseniz key parametresi yerine client parametresini kullanan bir istemci kimliği kullanıyor olabileceğinizi unutmayın. İstemci kimlikleri, Haritalar JavaScript API v3'te hâlâ desteklenmektedir ve anahtar yükseltme sürecinden geçmeleri gerekmez.

API yükleniyor

Kodunuzda yapmanız gereken ilk değişiklik, API'yi yükleme şeklinizle ilgilidir. 2. sürümde, Maps JavaScript API'yi http://maps.google.com/maps adresine gönderilen bir istek üzerinden yüklersiniz. Maps JavaScript API 3.0 sürümünü yüklüyorsanız aşağıdaki değişiklikleri yapmanız gerekir:

  1. API'yi //maps.googleapis.com/maps/api/js adresinden yükleme
  2. file parametresini kaldırın.
  3. key parametresini yeni v3 anahtarınızla güncelleyin. Work için Google Haritalar API'si müşterileri client parametresi kullanmalıdır.
  4. (Yalnızca Google Haritalar Platformu Premium Planı) client parametresinin, Google Haritalar Platformu Premium Planı Geliştirici Kılavuzu'nda açıklandığı şekilde sağlandığından emin olun.
  5. En son yayınlanan sürümü istemek için v parametresini kaldırın veya değerini v3 sürümlendirme şemasına göre değiştirin.
  6. (İsteğe bağlı) hl parametresini language ile değiştirin ve değerini koruyun.
  7. (İsteğe bağlı) İsteğe bağlı kitaplıkları yüklemek için libraries parametresi ekleyin.

En basit durumda, v3 önyüklemesi yalnızca API anahtarı parametrenizi belirtir:

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

Aşağıdaki örnekte, Maps JavaScript API v2'nin en son sürümünün Almanca olarak istendiği görülüyor:

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

Aşağıdaki örnek, v3 için eşdeğer bir istektir.

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

google.maps ad alanını kullanıma sunuyoruz

Maps JavaScript API v3'teki en dikkat çekici değişiklik muhtemelen google.maps ad alanının kullanıma sunulmasıydı. v2 API, tüm nesneleri varsayılan olarak Global ad alanına yerleştirir. Bu, ad çakışmasına neden olabilir. 3. sürümde tüm nesneler google.maps ad alanında bulunur.

Uygulamanızı v3'e taşırken yeni ad alanını kullanmak için kodunuzu değiştirmeniz gerekir. Maalesef "G" aramak ve "google.maps" ile değiştirmek tam olarak işe yaramaz. Ancak kodunuzu incelerken bu yöntemi uygulamak iyi bir fikirdir. Aşağıda, v2 ve v3'teki eşdeğer sınıflara dair bazı örnekler verilmiştir.

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

Eski Kodları Kaldırma

Haritalar JavaScript API'si sürüm 3, sürüm 2'deki işlevlerin çoğuna paralel işlevlere sahiptir. Ancak artık desteklenmeyen bazı sınıflar vardır. Taşıma işleminiz kapsamında bu sınıfları üçüncü taraf yardımcı kitaplıklarıyla değiştirmeniz veya bu referansları kodunuzdan kaldırmanız gerekir. Closure veya jQuery gibi benzer işlevler sunan birçok mükemmel JavaScript kitaplığı vardır.

Aşağıdaki sınıfların Maps JavaScript API v3'te eşdeğeri yoktur:

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

Kodu Karşılaştırma

v2 ve v3 API'leri ile yazılmış oldukça basit iki uygulamayı karşılaştıralım.

<!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>

Gördüğünüz gibi, iki uygulama arasında birkaç fark var. Önemli değişikliklerden bazıları şunlardır:

  • API'nin yüklendiği adres değişti.
  • GBrowserIsCompatible() ve GUnload() yöntemleri artık v3'te gerekli değildir ve API'den kaldırılmıştır.
  • GMap2 nesnesi, API'deki merkezi nesne olarak google.maps.Map ile değiştirilir.
  • Mülkler artık Seçenekler sınıfları aracılığıyla yüklenir. Yukarıdaki örnekte, harita yüklemek için gereken üç özelliği (center, zoom ve mapTypeId) bir satır içi MapOptions nesnesi aracılığıyla belirledik.
  • Varsayılan kullanıcı arayüzü, v3'te varsayılan olarak açıktır. Bunu, MapOptions nesnesinde disableDefaultUI özelliğini true olarak ayarlayarak devre dışı bırakabilirsiniz.

Özet

Bu noktada, Haritalar JavaScript API'nin 2. sürümünden 3. sürümüne geçişinizle ilgili bazı önemli noktaları öğrenmiş olacaksınız. Bilmeniz gereken başka bilgiler de vardır ancak bu bilgiler uygulamanıza bağlıdır. Aşağıdaki bölümlerde, karşılaşabileceğiniz belirli durumlar için taşıma talimatları verilmiştir. Ayrıca, yükseltme işlemi sırasında faydalı bulabileceğiniz çeşitli kaynaklar da vardır.

Bu makaleyle ilgili sorun veya sorularınız olursa lütfen bu sayfanın üst kısmındaki GERİ BİLDİRİM GÖNDER bağlantısını kullanın.

Ayrıntılı Referans

Bu bölümde, Maps JavaScript API'nin hem 2. hem de 3. sürümünün en popüler özelliklerinin ayrıntılı bir karşılaştırması sunulmaktadır. Referansın her bölümü ayrı ayrı okunacak şekilde tasarlanmıştır. Bu referansı baştan sona okumamanızı, bunun yerine taşıma işleminize yardımcı olması için bu materyali duruma göre kullanmanızı öneririz.

  • Etkinlikler: Etkinlikleri kaydetme ve işleme.
  • Denetimler: Haritada görünen gezinme denetimlerini yönetme
  • Yer paylaşımları: Haritaya nesne ekleme ve düzenleme
  • Harita Türleri: Temel haritayı oluşturan karolar.
  • Katmanlar: KML veya Trafik katmanları gibi grup halinde içerik ekleme ve düzenleme.
  • Hizmetler: Google'ın coğrafi kodlama, yol tarifi veya Street View hizmetleri ile çalışır.

Etkinlikler

Maps JavaScript API v3'ün etkinlik modeli, v2'de kullanılana benzer olsa da arka planda çok şey değişti.

Denetimler

Maps JavaScript API, kullanıcıların haritanızla etkileşime girmesine olanak tanıyan kullanıcı arayüzü denetimlerini gösterir. Bu denetimlerin nasıl görüneceğini özelleştirmek için API'yi kullanabilirsiniz.

Katmanlar

Yer paylaşımları, noktaları, çizgileri, alanları veya nesne koleksiyonlarını belirtmek için haritaya "eklediğiniz" nesneleri yansıtır.

Harita Türleri

v2 ve v3'te kullanılabilen harita türleri biraz farklıdır ancak temel harita türlerinin tümü API'nin her iki sürümünde de kullanılabilir. v2, varsayılan olarak standart "boyalı" yol haritası karolarını kullanır. Ancak v3, google.maps.Map nesnesi oluştururken belirli bir harita türü belirtilmesini gerektirir.

Katmanlar

Katmanlar, haritadaki bir veya daha fazla yer paylaşımından oluşan nesnelerdir. Tek bir birim olarak değiştirilebilirler ve genellikle nesne koleksiyonlarını yansıtırlar.

Hizmetler