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

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Android Studio için Google Haritalar şablonunu kullanarak bir harita görüntüleyen Android uygulaması oluşturun. Oluşturmak istediğiniz mevcut bir Android Studio projeniz varsa Proje Yapılandırması bölümüne bakın.

Bu hızlı başlangıç kılavuzu, Java veya Kotlin ile temel Android geliştirme sürecine aşina olan geliştiriciler için hazırlanmıştır.

Geliştirme ortamını ayarlama

  1. Android Studio Arctic Fox veya üzeri 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ü kullandığınızdan emin olun.

Android cihaz kurma

Android için Haritalar SDK'sını kullanan bir uygulamayı çalıştırmak için bu uygulamayı Android 4.0 veya sonraki bir sürümü temel alan ve Google API'lerini içeren bir Android cihaza veya Android emülatörüne dağıtmanız gerekir.

  • Android cihaz kullanmak için Donanımları kullanarak uygulama ç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 sunulan Android Sanal Cihaz (AVD) Yöneticisini kullanarak emülatörü yükleyebilirsiniz.

Android Studio'da Google Haritalar projesi oluşturma

  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 kategorisinin altında Google Haritalar Etkinliği'ni 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 desteklenmektedir. Kotlin hakkında daha fazla bilgi edinmek için Kotlin ile Android uygulamaları geliştirme sayfasına göz atın.

    • Minimum SDK'yı, test cihazınızla uyumlu bir SDK sürümü olarak ayarlayın. Şu anda Android API Seviye 19 (Android 4.4, KitKat) veya sonraki bir sürüm olan, Android SDK'nın 18.0.x sürümü için gerekli olan minimum sürümden daha büyük bir sürüm seçmelisiniz. SDK sürümü gereksinimleri hakkında en son bilgiler için Sürüm Notları'na bakın.

  4. Son'u tıklayın.

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

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

  6. AndroidManifest.xml dosyası, bir Google Haritalar API'sı anahtarı alma ve ardından bu dosyayı local.property dosyanıza eklemeyle ilgili talimatları içerir. API anahtarınızı AndroidManifest.xml dosyasına eklemeyin. Böylece API anahtarınızı daha az güvenli bir şekilde depolarsınız. Bunun yerine, Cloud projesi oluşturmak ve API anahtarı yapılandırmak için sonraki bölümlerde yer alan talimatları uygulayın.

Google Cloud projenizi ayarlayın

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

1. Adım

Konsol

  1. Yeni bir Cloud projesi oluşturmaya başlamak için Google Cloud Console'daki proje seçici sayfasında Proje Oluştur'u tıklayın.

    Proje seçici sayfasına git

  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Projeniz için faturalandırmanın etkinleştirildiğini onaylayın.

    Google Cloud, ücretsiz deneme sürümü sunar. Deneme süresinin sona ermesi, 90 günün sonunda veya hesaba 300 ABD doları tutarında ücret tahakkuk ettikten sonra (hangisi önce gerçekleşirse) sona erer. Dilediğiniz zaman iptal edebilirsiniz. Google Haritalar Platformu'nda yinelenen aylık 200 ABD doları kredi bulunur. Daha fazla bilgi için Faturalandırma hesabı kredileri ve Faturalandırma bölümlerine bakın.

Google Cloud SDK

gcloud projects create "PROJECT"

Google Cloud SDK, , Google Cloud SDK yüklemesi ve aşağıdaki komutlar hakkında daha fazla bilgi edinin:

2. Adım

Google Haritalar Platformu'nu kullanmak için projenizle birlikte kullanmayı planladığınız API'leri veya SDK'ları etkinleştirmeniz gerekir.

Konsol

Android için Haritalar SDK'sını etkinleştirme

Google Cloud SDK

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

Google Cloud SDK, , Google Cloud SDK yüklemesi ve aşağıdaki komutlar hakkında daha fazla bilgi edinin:

3. Adım

Bu adım yalnızca API Anahtarı oluşturma sürecinden geçer. API anahtarınızı üretimde kullanıyorsanız API anahtarınızı kısıtlamanızı önemle tavsiye ederiz. Ürüne özel API Anahtarları Kullanma sayfasında daha fazla bilgi bulabilirsiniz.

API anahtarı, kullanım ve faturalandırma amacıyla projenizle ilişkili isteklerin kimliğini doğrulayan benzersiz bir tanımlayıcıdır. Projenizle ilişkilendirilmiş en az bir API anahtarınız olmalıdır.

API anahtarı oluşturmak için:

Konsol

  1. Google Haritalar Platformu > Kimlik bilgileri sayfasına gidin.

    Kimlik bilgileri sayfasına git

  2. Kimlik bilgileri sayfasında Kimlik bilgisi oluştur > API anahtarı'nı tıklayın.
    API anahtarı oluşturuldu iletişim kutusunda yeni oluşturulan API anahtarınız gösterilir.
  3. Kapat'ı tıklayın.
    Yeni API anahtarı, Kimlik bilgileri sayfasında API anahtarları altında listelenir.
    (Üretimde kullanmadan önce API anahtarını kısıtlamayı unutmayın.)

Google Cloud SDK

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

Google Cloud SDK, , Google Cloud SDK yüklemesi ve aşağıdaki komutlar hakkında daha fazla bilgi edinin:

Uygulamanıza API anahtarını ekleme

Bu bölümde, API anahtarınıza uygulamanızın güvenli bir şekilde başvuruda bulunabilmesi için nasıl depolanacağı açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminizde kontrol etmemelisiniz. Bu yüzden, anahtarınızı projenizin kök dizininde bulunan local.properties dosyasında depolamanızı öneririz. local.properties dosyası hakkında daha fazla bilgi için Gradle özellik dosyaları bölümüne bakın.

Bu görevi kolaylaştırmak için Secrets Gradle Plugin for Android'i kullanmanızı öneririz. Eklentiyi yüklemek ve API anahtarınızı depolamak için:

  1. Android Studio'da proje düzeyindeki build.gradle dosyanızı açın ve buildscript altındaki dependencies öğesine aşağıdaki kodu ekleyin.
    plugins {
        // ...
        id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
    }
  2. Ardından, modül düzeyindeki build.gradle dosyanızı açın ve aşağıdaki kodu plugins öğesine ekleyin.
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. Dosyayı kaydedin ve projenizi Gradle ile senkronize edin.
  4. Proje düzeyindeki dizininizde local.properties öğesini açıp aşağıdaki kodu ekleyin. YOUR_API_KEY yerine API anahtarınızı yazın.
    MAPS_API_KEY=YOUR_API_KEY
        
  5. Dosyayı kaydedin.
  6. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY adresine gidip android:value attribute dosyasını aşağıdaki gibi güncelleyin:
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Not: Yukarıda gösterildiği gibi, API anahtarı için com.google.android.geo.API_KEY önerilen meta veri adıdır. Bu ada sahip bir anahtar, Android platformunda Google Haritalar SDK'sı da dahil olmak üzere Android platformunda birden fazla Google Haritalar tabanlı API'nin kimliğini doğrulamak için kullanılabilir. Geriye dönük uyumluluk için API aynı zamanda com.google.android.maps.v2.API_KEY adını da destekler. Bu eski ad, yalnızca Android Maps API v2'de kimlik doğrulamaya olanak tanır. Bir uygulama, API anahtarı meta veri adlarından yalnızca birini belirtebilir. Her ikisi de belirtilmişse API bir istisna atar.

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 olan MapsActivity.kt olarak ayarlarsanız.

Harita etkinliğinin ana öğeleri:

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

  • GoogleMap nesnesi, harita verilerine ve görünüme erişim sağlar. Bu, Android için Haritalar SDK'sının ana sınıfıdır. Nesneleri Eşleme kılavuzunda, SupportMapFragment ve GoogleMap nesneleri daha ayrıntılı olarak açıklanmaktadır.

  • moveCamera işlevi, haritayı Sidney Avustralya'nın 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ünüm kılavuzuna bakın.

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

Haritalar etkinlik dosyası aşağıdaki kodu içerir:

Java


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));
    }
}

      

Kotlin


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))
    }
}

      

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çeriyor.

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    // ...
}

Haritalar'a bağımlılığı yönetme hakkında daha fazla bilgi için Sürüm oluşturma konusuna bakın.

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 bulunur. activity_maps.xml dosyası, aşağıdaki öğeleri içeren bir parça bildirir:

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

XML düzen dosyası aşağıdaki 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ğıtın ve çalıştırın

Syndney Australia merkezli harita ve işaretçinin yer aldığı ekran görüntüsü.

Uygulamayı başarıyla çalıştırdığınızda, aşağıdaki ekran görüntüsünde görüldüğü üzere, şehirde bir işaretleyiciyle birlikte Sidney Avustralya merkezli bir harita görüntülenir.

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, Başlatma emülatörü 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ı geliştirmek için Gradle'ı başlatıp sonuçları cihazınızda veya emülatörde gösterir. Uygulamanın başlatılması birkaç dakikayı bulabilir.

Sonraki adımlar

  • Harita oluşturma: Bu konu, haritanızın başlangıç ve çalışma zamanı ayarlarını (ör. kamera konumu, harita türü, kullanıcı arayüzü bileşenleri ve hareketler) nasıl ayarlayacağınızı açıklar.

  • Android uygulamanıza harita ekleme (Kotlin): Bu codelab'de, Android için Haritalar SDK'sının bazı ek özelliklerini gösteren bir uygulamayla ilgili yol gösterilir.

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