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ı bölümüne bakın.

Bu hızlı başlangıç kılavuzu, Java veya Kotlin ile temel Android geliştirme konusunda bilgi sahibi olan geliştiricilere yöneliktir.

Geliştirme ortamını ayarlama

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

• Android cihaz kullanmak için Uygulamaları bir donanım cihazında çalıştırma başlıklı makaledeki talimatları uygulayın.
• Android emülatörü kullanmak için bir sanal cihaz oluşturabilir ve Android Studio ile birlikte sunulan Android Sanal Cihaz (AVD) Yöneticisi'ni 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 penceresinde, 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 konusuna bakın.

   • Minimum SDK'yı test cihazınızla uyumlu bir SDK sürümüne ayarlayın. Android'in 18.0.x sürümü için Haritalar SDK'sının gerektirdiği, şu anda Android API Seviye 19 (Android 4.4, KitKat) veya sonraki bir sürümü seçmeniz gerekir. SDK sürümü gereksinimleri hakkında en güncel bilgiler için Sürüm Notları'na göz atı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ğiniz farklı bir ada sahip olabilir ancak kurulum sırasında yapılandırdığınız ad olacaktır.

6. AndroidManifest.xml dosyası, bir Google Haritalar API anahtarı alma ve bunu local.property dosyanıza ekleme ile 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 saklarsı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 oluşturma

Aşağıdaki sekmeleri tıklayarak gereken 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"

API anahtarını uygulamanıza ekleme

Bu bölümde, API anahtarınızın uygulamanız tarafından güvenli bir şekilde referans alınabilmesi için nasıl depolanacağı açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize kontrol etmemeniz gerekir. Bu nedenle, anahtarı projenizin kök dizininde bulunan local.properties dosyasında depolamanızı öneririz. local.properties dosyası hakkında daha fazla bilgi için Gradle mülklerindeki 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 aşağıdaki kodu buildscript altındaki dependencies öğesine 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çın, ardından 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 konumuna 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 önerilen meta veri adı com.google.android.geo.API_KEY. Bu ada sahip bir anahtar, Android platformundaki Haritalar SDK'sı da dahil olmak üzere Android platformunda birden fazla Google Haritalar tabanlı API'de kimlik doğrulaması yapmak 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'de kimlik doğrulamaya olanak tanır. Bir uygulama, API anahtarı meta veri adlarından yalnızca birini belirtebilir. Her ikisi de belirtilirse 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ı

Harita etkinliği dosyası, uygulamanın ana etkinliğidir ve haritayı yönetmek ve görüntülemek için kullanılacak 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.

Haritalar etkinliğinin ana öğeleri:

• SupportMapFragment nesnesi, haritanın 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. Harita Nesneleri kılavuzunda, SupportMapFragment ve GoogleMap nesneleri daha ayrıntılı olarak açıklanmaktadır.

• moveCamera işlevi, haritayı Sidney Avustralya'nın LatLng koordinatlarına 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 etkinliği dosyası şu kodu içerir:

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

      

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

      

Module 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 {
    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üzeni dosyası

activity_maps.xml dosyası, uygulamanın kullanıcı arayüzünün 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 haritalar etkinliği dosyasında tanımlanan MapsActivity olarak ayarlar.
• android:name, parçanın sınıf adını haritalar etkinliği dosyasında kullanılan parça türü olan SupportMapFragment olarak ayarlar.

XML düzeni 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

Uygulamayı başarıyla çalıştırdığınızda, aşağıdaki ekran görüntüsünde görüldüğü gibi, şehir üzerinde 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, Emulator'ı başlat radyo düğmesini 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 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 bir harita ekleme (Kotlin): Bu codelab'de, Android için Haritalar SDK'sının bazı ek özelliklerini gösteren bir uygulama adım adım açıklanmaktadır.

• 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ızı sağlar.