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

Maps JavaScript API v2, 26 Mayıs 2021 tarihinden itibaren kullanılamamaktadır. Bunun sonucunda, sitenizin v2 haritaları çalışmayı durduracak ve JavaScript hataları döndürecektir. Sitenizde haritaları kullanmaya devam etmek için Maps JavaScript API v3'e geçiş yapın. Bu kılavuz, süreç boyunca size yardımcı olacaktır.

Genel bakış

Her uygulamanın taşıma süreci biraz farklı bir süreç olsa da tüm projelerde ortak olan bazı adımlar vardır:

  1. Yeni bir anahtar alın. Maps JavaScript API, anahtarları yönetmek için artık Google Cloud Console'u kullanıyor. Hâlâ v2 anahtarı kullanıyorsanız taşıma işlemine başlamadan önce yeni API anahtarınızı aldığınızdan emin olun.
  2. API Önyükleyicinizi 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. Kodunuzu güncelleyin. Gereken değişiklik miktarı büyük ölçüde uygulamanıza bağlıdır. Sık yapılan değişiklikler şunlardır:
    • Her zaman google.maps ad alanına başvurun. v3'te, tüm Maps JavaScript API kodları, genel ad alanı yerine google.maps.* ad alanında depolanır. Çoğu nesne de bu süreç kapsamında yeniden adlandırılmıştır. Örneğin, GMap2 yerine artık google.maps.Map yükleyeceksiniz.
    • Eski yöntemlere yapılan tüm referansları kaldırın. GDownloadURL ve GLog gibi çeşitli 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 yardımcı program kitaplıklarına harici hale getirilmiştir. Böylece her uygulama, API'nin yalnızca kullanılacak parçalarını yüklemek zorunda kalır.
    • (İsteğe bağlı) Projenizi v3 externs kullanacak şekilde yapılandırın. v3 externs, kodunuzu Closure Derleyici ile doğrulamaya yardımcı olmak veya IDE'nizde otomatik tamamlamayı tetiklemek için kullanılabilir. Gelişmiş Derleme ve Harici Kaynaklar hakkında daha fazla bilgi edinin.
  4. Test edin ve tekrarlayın. Bu noktada hâlâ yapmanız gereken bazı şeyler olacak. Ancak v3 harita uygulamanıza doğru yolda ilerliyorsunuz.

Maps JavaScript API V3'teki değişiklikler

Taşıma işleminizi planlamadan önce, Maps JavaScript API v2 ile Maps JavaScript API v3 arasındaki farkları anlamalısınız. Maps JavaScript API'nin en yeni sürümü, modern JavaScript programlama tekniklerine, kitaplık kullanımını artırmaya ve basitleştirilmiş bir API'ye odaklanarak sıfırdan yazılmıştır. API'ye birçok yeni özellik eklendi ve bilindik bazı özellikler değiştirildi, hatta kaldırıldı. Bu bölümde, iki sürüm arasındaki bazı önemli farklar vurgulanmaktadır.

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

  • Sadeleştirilmiş bir temel kitaplık. Haritanızın tüm cihazlarda hızlı bir şekilde yüklenmesini sağlayan Core API'nin yükleme ve ayrıştırma sürelerini azaltmaya yardımcı olan yardımcı işlevlerin birçoğu kitaplıklara taşındı.
  • Poligon oluşturma ve işaretçi yerleşimi gibi birçok özelliğin performansı iyileştirildi.
  • Mobil proxy'ler ve kurumsal güvenlik duvarları tarafından kullanılan paylaşılan adreslerin daha iyi barındırılması için istemci tarafı kullanım sınırlarına yeni bir yaklaşım.
  • Bazı modern tarayıcı ve mobil tarayıcılar için destek eklendi. Internet Explorer 6 desteği kaldırılmıştır.
  • Genel amaçlı yardımcı sınıfların ( GLog veya GDownloadUrl) çoğu kaldırıldı. Günümüzde Closure veya jQuery gibi benzer işlevler sunan birçok mükemmel JavaScript kitaplığı mevcuttur.
  • Tüm mobil cihazlara yüklenen bir HTML5 Street View uygulaması.
  • Kendi fotoğraflarınızla oluşturulan özel Street View panoramaları sayesinde kayak pistlerinin, satılık evlerin veya diğer ilgi çekici yerlerin panoramalarını paylaşabilirsiniz.
  • Temel haritadaki öğelerin görünümünü benzersiz görsel stilinize uyacak şekilde değiştirmenize olanak tanıyan Stilli Haritalar özelleştirmeleri.
  • ElevationService ve Mesafe Matrisi gibi çeşitli yeni hizmetler için destek.
  • İyileştirilmiş yol tarifi hizmetleri; alternatif rotalar, rota optimizasyonu ( seyahat eden satış görevlisi sorunu için yaklaşık çözümler), bisiklet için yol tarifleri ( bisiklet katmanı ile), toplu taşıma yol tarifleri ve sürüklenebilir yol tarifleri sağlar.
  • 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 çok Bilgi Penceresi desteği

Uygulamanızı Yeni Sürüme Geçirme

Yeni Anahtarınız

Maps JavaScript API v3, v2'den yeni bir anahtar sistemi kullanıyor. Uygulamanızda zaten bir v3 anahtarı kullanıyor olabilirsiniz. Bu durumda değişiklik yapmanız gerekmez. Doğrulamak amacıyla, Maps JavaScript API'yi yüklediğiniz URL'de key parametresi olup olmadığını kontrol edin. Anahtar değeri "ABQIAA" ile başlıyorsa v2 anahtarı kullanıyorsunuzdur. v2 anahtarınız varsa taşıma işleminin parçası olarak bir v3 anahtarına yükseltme yapmanız gerekir. Bu sayede:

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

Google Maps API for Work müşterisiyseniz key parametresi yerine client parametresiyle birlikte bir istemci kimliği kullanıyor olabilirsiniz. İstemci kimlikleri, Maps JavaScript API v3'te desteklenmeye devam etmektedir ve anahtarın yeni sürüme geçirilmesi gerekmez.

API yükleniyor

Kodunuzda yapmanız gereken ilk değişiklik, API'yi nasıl yüklediğinizle ilgilidir. v2'de, Maps JavaScript API'yi http://maps.google.com/maps isteği üzerinden yüklersiniz. Maps JavaScript API v3'ü yüklüyorsanız aşağıdaki değişiklikleri yapmanız gerekir:

  1. //maps.googleapis.com/maps/api/js ürününden API'yi yükleyin
  2. file parametresini kaldırın.
  3. key parametresini yeni v3 anahtarınızla güncelleyin. Google Maps API for Work müşterileri bir 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ığı gibi sağlandığından emin olun.
  5. Yayınlanan en son sürümü istemek için v parametresini kaldırın veya değerini v3 sürüm oluşturma şemasına uygun olarak 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 bir libraries parametresi ekleyin.

En basit şekilde, 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 Almanca en son sürümü istenmektedir:

<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 üzerindeki muhtemelen en dikkat çekici değişiklik, google.maps ad alanının kullanıma sunulmasıdır. v2 API, tüm nesneleri varsayılan olarak Küresel ad alanına yerleştirir. Bu durum, adlandırma çakışmalarına neden olabilir. v3 içindeki tüm nesneler google.maps ad alanında bulunur.

Uygulamanızı v3'e taşırken yeni ad alanından yararlanmak için kodunuzu değiştirmeniz gerekir. Maalesef "G" harfinin aranması ve "google.maps" ile değiştirilmesi tam olarak işe yaramayacaktır. Ancak, kodunuzu incelerken bu yararlı bir genel kuraldır. Aşağıda v2 ve v3'teki eş değer sınıflarla ilgili 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 Kodu Kaldırma

Maps JavaScript API v3'te, v2'deki işlevlerin çoğu için benzerlikler vardır ancak artık desteklenmeyen bazı sınıflar da mevcuttur. Taşıma işleminizin bir parçası olarak, bu sınıfları üçüncü taraf yardımcı program kitaplıklarıyla değiştirmeli veya bu referansları kodunuzdan kaldırmalısınız. Closure veya jQuery gibi birçok mükemmel JavaScript kitaplığı benzer işlevler sağlar.

Aşağıdaki sınıflar Maps JavaScript API v3'te paralel değildir:

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

Kod Karşılaştırma

v2 ve v3 API'leriyle 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 vardır. Önemli değişiklikler şunlardır:

  • API'nın 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ükleniyor. Yukarıdaki örnekte, bir haritayı satır içi MapOptions nesnesi aracılığıyla yüklemek için gereken üç özelliği (center, zoom ve mapTypeId) ayarladık.
  • v3'te varsayılan kullanıcı arayüzü varsayılan olarak açıktır. MapOptions nesnesinde disableDefaultUI özelliğini true olarak ayarlayarak bunu devre dışı bırakabilirsiniz.

Özet

Bu aşamada, Maps JavaScript API'nin v2'den v3'e geçişiyle ilgili bazı önemli noktalara dair fikir edinmiş olacaksınız. Bilmeniz gereken başka bilgiler de mevcuttur, ancak bunlar uygulamanıza bağlı olarak değişir. Karşılaşabileceğiniz belirli durumlara özel taşıma talimatlarını aşağıdaki bölümlerde bulabilirsiniz. Ayrıca, yükseltme işlemi sırasında faydalı bulabileceğiniz çeşitli kaynaklar da mevcuttur.

Bu makaleyle ilgili sorunlarınız 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 v2 ve v3 için en popüler özelliklerinin ayrıntılı bir karşılaştırması yer almaktadır. Referansın her bölümü ayrı ayrı okunacak şekilde tasarlanmıştır. Bu referansı bütünüyle okumamanızı öneririz. Bunun yerine, durum bazında taşıma işleminize yardımcı olması için bu materyali kullanın.

  • Etkinlikler: Etkinlikleri kaydetme ve işleme.
  • Kontroller - Haritada görünen gezinme denetimlerini değiştirme.
  • Katmanlar - Haritaya nesne ekleme ve haritadaki nesneleri düzenleme.
  • Harita Türleri - temel haritayı oluşturan bloklar.
  • Katmanlar - KML veya Trafik katmanları gibi içeriği grup olarak ekleme ve düzenleme.
  • Hizmetler: Google'ın coğrafi kodlaması, yol tarifleri veya Street View hizmetleriyle çalışma.

Etkinlikler

Maps JavaScript API v3'ün etkinlik modeli, v2'de kullanılana benzer ancak ayrıntılarında çok fazla değişiklik olmuştur.

Denetimler

Maps JavaScript API, kullanıcıların haritanızla etkileşime girmesine olanak tanıyan kullanıcı arayüzü denetimlerini görüntüler. API'yi kullanarak bu kontrollerin görünümünü özelleştirebilirsiniz.

Yer paylaşımları

Katmanlar; noktaları, çizgileri, alanları veya nesne koleksiyonlarını belirtmek için haritaya "eklediğiniz" nesneleri yansıtır.

Harita Türleri

v2 ve v3'te bulunan harita türleri biraz farklı olsa da tüm temel harita türleri API'nin her iki sürümünde de kullanılabilir. Varsayılan olarak v2, standart "boyalı" yol haritası desenlerini kullanır. Ancak v3, google.maps.Map nesnesi oluşturulurken belirli bir harita türünün sağlanmasını gerektirir.

Katmanlar

Katmanlar, harita üzerinde bir veya daha fazla yer paylaşımından oluşan nesnelerdir. Tek bir birim olarak işlenebilirler ve genellikle nesne koleksiyonlarını yansıtırlar.

Hizmetler