Android için Haritalar SDK'sı Hızlı Başlangıç Kılavuzu

Android Studio için Google Haritalar şablonunu kullanarak harita görüntüleyen bir Android uygulaması oluşturun. Ayarlamak istediğiniz mevcut bir Android Studio projeniz varsa Proje Yapılandırması'na bakın.

Bu hızlı başlangıç kılavuzu, Java veya Kotlin ile temel Android geliştirme konusunda bilgi sahibi olan geliştiriciler için hazırlanmıştır.

Geliştirme ortamını ayarlama

1. Android Studio Arctic Fox veya daha yeni bir sürüm gerekir. Henüz yapmadıysanız indirin ve yükleyin.
2. Android Studio'da Android Gradle eklentisini 7.0 veya daha yeni bir sürümünü kullandığınızdan emin olun.

• Android cihaz kullanmak için Uygulamaları donanım cihazında çalıştırma başlıklı makaledeki talimatları uygulayın.
• Android emülatörü kullanmak için sanal bir cihaz oluşturabilir ve Android Studio ile birlikte gelen Android Virtual Device (AVD) Manager'ı kullanarak emülatörü yükleyebilirsiniz.

Android Studio'da Google Haritalar projesi oluşturma

Android Studio'da Google Haritalar projesi oluşturma prosedürü Flamingo'da ve Android Studio'nun sonraki sürümlerinde değiştirildi. Android Studio'nun kendi sürümünüz için aşağıdaki adımları uyguladığınızdan emin olun.

1. Android Studio'yu açın ve Android Studio'ya hoş geldiniz penceresinde Yeni Proje Oluştur'u tıklayın.

2. Yeni Proje penceresindeki Telefon ve Tablet kategorisinde Boş Etkinlik'i seçip İleri'yi tıklayın.

3. Google Haritalar Etkinliği formunu doldurun:

   • Dil'i Java veya Kotlin olarak ayarlayın. Her iki dil de Android için Haritalar SDK'sı tarafından tam olarak desteklenir. Kotlin hakkında daha fazla bilgi edinmek için Kotlin ile Android uygulamaları geliştirme bölümüne bakın.

   • Minimum SDK'yı, test cihazınızla uyumlu bir SDK sürümüne ayarlayın. Android API düzeyi 19 (Android 4.4, KitKat) veya daha üst bir sürüm olan, Android için Haritalar SDK'sı 18.0.x sürümü için gereken minimum sürümden daha yüksek bir sürüm seçmeniz gerekir. SDK sürümü gereksinimleriyle ilgili en son bilgiler için Sürüm Notları'na bakın.

4. Son'u tıklayın.

   Android Studio, Gradle'ı başlatır ve projeyi oluşturur. Bu işlem zaman alabilir.

5. Derleme tamamlandığında Android Studio AndroidManifest.xml ve MapsActivity dosyalarını açar. Etkinliğinizin farklı bir adı olabilir, ancak kurulum sırasında yapılandırdığınız addır.

6. Google Haritalar Görüntüleme Etkinliği'ni ekleyin:

   1. Google Haritalar Görünüm Etkinliği'ni eklemek istediğiniz paketi sağ tıklayın.
   2. Yeni > Google > Google Haritalar Görüntüleme Etkinliği'ni seçin.

   

   Daha fazla bilgi için Şablondan kod ekleme bölümüne bakın

7. AndroidManifest.xml dosyası, bir Google Haritalar API anahtarı alma ve bu anahtarı local.properties dosyanıza ekleme talimatlarını içerir. API anahtarınızı AndroidManifest.xml dosyasına eklemeyin. Bu şekilde API anahtarınız daha az güvenli bir şekilde depolanır. Bunun yerine, bir Cloud projesi oluşturmak ve API anahtarı yapılandırmak için sonraki bölümlerde yer alan talimatları uygulayın.

Google Cloud projenizi oluşturun

Aşağıdaki sekmeleri tıklayarak gerekli Cloud Console kurulum adımlarını tamamlayın:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Uygulamanıza API anahtarını ekleyin

Bu bölümde, uygulamanızın güvenli bir şekilde başvuruda bulunabilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize kontrol etmemeniz gerekir. Bu nedenle, projenizin kök dizininde bulunan secrets.properties dosyasında saklamanızı öneririz. secrets.properties dosyası hakkında daha fazla bilgi edinmek için Gradle özellik dosyaları bölümüne bakın.

Bu görevi kolaylaştırmak için Android için Secrets Gradle Plugin'i kullanmanızı öneririz.

Google Haritalar projenize Android için Secrets Gradle Eklentisi'ni yüklemek için:

1. Android Studio'da proje düzeyindeki build.gradle dosyanızı açın ve aşağıdaki kodu buildscript altındaki dependencies öğesine ekleyin.

   Modern

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }
   

2. Modül düzeyindeki build.gradle dosyanızı açıp plugins öğesine aşağıdaki kodu ekleyin.

   Modern

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. Dosyayı kaydedin ve projenizi Gradle ile senkronize edin.
4. Proje düzeyindeki dizininizde secrets.properties dosyasını açın ve ardından aşağıdaki kodu ekleyin. YOUR_API_KEY öğesini API anahtarınızla değiştirin.

   MAPS_API_KEY=YOUR_API_KEY 

5. Dosyayı kaydedin.
6. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY bölümüne gidip android:value attribute değerini şu şekilde güncelleyin:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

7. İsteğe bağlı olarak, farklı bir gizli anahtar dosyası veya diğer özellikleri belirtmek için eklentinin özelliklerini düzenleyin. Android Studio'da, proje düzeyindeki build.gradle dosyanızı açın ve secrets özelliğini düzenleyin:

   secrets {
       // Optionally specify a different file name containing your secrets.
       // The plugin defaults to "local.properties"
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = 'local.defaults.properties'
   
       // Configure which keys should be ignored by the plugin by providing regular expressions.
       // "sdk.dir" is ignored by default.
       ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
       ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
   }

Not: Yukarıda gösterildiği gibi, API anahtarı için önerilen meta veri adı com.google.android.geo.API_KEY'dir. Bu ada sahip bir anahtar, Android için Haritalar SDK'sı dahil olmak üzere Android platformundaki birden fazla Google Haritalar tabanlı API'nin kimliğini doğrulamak için kullanılabilir. API, geriye dönük uyumluluk için com.google.android.maps.v2.API_KEY adını da destekler. Bu eski ad, yalnızca Android Maps API v2 ile kimlik doğrulaması yapılmasına izin verir. Bir uygulama, API anahtarı meta veri adlarından yalnızca birini belirtebilir. Her ikisi de belirtilirse API bir istisna oluşturur.

Koda bakın

Şablon tarafından sağlanan kodu inceleyin. Özellikle Android Studio projenizde aşağıdaki dosyalara bakın.

Haritalar etkinlik dosyası

Haritalar etkinlik dosyası, uygulamanın ana etkinliğidir ve haritayı yönetip görüntülemek için gereken kodu içerir. Varsayılan olarak, etkinliği tanımlayan dosyanın adı MapsActivity.java veya Kotlin'i uygulamanızın dili olarak MapsActivity.kt olarak ayarlarsanız.

Harita etkinliğinin ana öğeleri:

• SupportMapFragment nesnesi haritanın yaşam döngüsünü yönetir ve uygulama kullanıcı arayüzünün üst öğesidir.

• GoogleMap nesnesi, harita verilerine ve görünümüne erişim sağlar. Bu, Android için Haritalar SDK'sının ana sınıfıdır. Harita Nesneleri kılavuzu, SupportMapFragment ve GoogleMap nesnelerini daha ayrıntılı olarak açıklar.

• moveCamera işlevi, haritayı Sidney Avustralya için LatLng koordinatlarında ortalar. Harita eklerken yapılandırılacak ilk ayarlar genellikle harita konumu ve kamera ayarlarıdır (ör. görüntüleme açısı, harita yönü ve yakınlaştırma düzeyi). Ayrıntılar için Kamera ve Görüntüleme kılavuzuna bakın.

• addMarker işlevi, Sidney'in koordinatlarına bir işaretçi ekler. Ayrıntılar için İşaretçiler kılavuzuna bakın.

Haritalar etkinlik dosyası şu kodu içerir:

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}

      

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

Modül Gradle dosyası

build.gradle Modül dosyası, Android için Haritalar SDK'sının gerektirdiği aşağıdaki harita bağımlılığını içerir.

dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

Haritalar bağımlılığını yönetme hakkında daha fazla bilgi edinmek için Sürüm oluşturma başlıklı makaleyi inceleyin.

XML düzen dosyası

activity_maps.xml dosyası, uygulamanın kullanıcı arayüzü yapısını tanımlayan XML düzen dosyasıdır. Dosya res/layout dizininde bulunuyor. activity_maps.xml dosyası, aşağıdaki öğeleri içeren bir parça tanımlıyor:

• tools:context, parçanın varsayılan etkinliğini harita etkinlik dosyasında tanımlanan MapsActivity olarak ayarlar.
• android:name, parçanın sınıf adını SupportMapFragment olarak ayarlar. Bu, haritalar etkinlik dosyasında kullanılan parça türüdür.

XML düzen dosyası şu kodu içerir:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

Uygulamayı dağıtma ve çalıştırma

Uygulamayı başarılı bir şekilde çalıştırdığınızda, merkezde Sidney Avustralya'yı gösteren bir harita görüntülenir ve aşağıdaki ekran görüntüsünde görüldüğü gibi şehirde bir işaretçi bulunur.

Uygulamayı dağıtmak ve çalıştırmak için:

1. Android Studio'da, uygulamanızı çalıştırmak için Çalıştır menü seçeneğini (veya oynat düğmesi simgesini) tıklayın.
2. Bir cihaz seçmeniz istendiğinde aşağıdaki seçeneklerden birini belirleyin:
   • Bilgisayarınıza bağlı Android cihazı seçin.
   • Alternatif olarak Emülatörü başlat radyo düğmesini seçin ve ayarladığınız sanal cihazı seçin.
3. OK (Tamam) seçeneğini tıklayın. Android Studio, uygulamanızı oluşturmak için Gradle'ı başlatır ve ardından sonuçları cihazınızda veya emülatörünüzde görüntüler. Uygulamanın başlatılması birkaç dakika sürebilir.

Sonraki adımlar

• Harita oluşturma: Bu konuda, haritanız için kamera konumu, harita türü, kullanıcı arayüzü bileşenleri ve hareketler gibi ilk ve çalışma zamanı ayarlarını nasıl yapacağınız açıklanmaktadır.

• Android uygulamanıza harita ekleyin (Kotlin): Bu codelab, Android için Haritalar SDK'sının bazı ek özelliklerini gösteren bir uygulamada size yol gösterir.

• Haritalar Android KTX kitaplığını kullanın: Bu Kotlin uzantı (KTX) kitaplığı, Android için Haritalar SDK'sını kullanırken çeşitli Kotlin dil özelliklerinden yararlanmanızı sağlar.