Wear OS'te Maps API

Giyilebilir cihazdaki bir harita

Android için Haritalar SDK'sını kullanarak doğrudan Wear OS by Google cihazlarda çalışan, harita tabanlı bir giyilebilir uygulama oluşturabilirsiniz. Uygulamanızın kullanıcıları sadece bileklerine bakarak haritadaki konumlarını görebilir. Örneğin, bir rota üzerindeki konumlarını çizebilirler, örneğin, ayrıntılar için haritayı yakınlaştırabilirler veya uygulamanız tarafından sağlanan bir bilgi penceresini görmek için bir işaretçiye dokunabilirler.

Bu sayfada, Wear cihazlarda kullanılabilen API işlevleri açıklanmakta ve uygulamanızı oluşturmaya başlamanıza yardımcı olmaktadır.

Wear OS'i kullanmaya başlama

Android için Haritalar SDK'sı ile giyilebilir bir uygulama oluşturmak, diğer Android cihazlar için bir Google Haritalar uygulaması oluşturmakla temelde aynıdır. Aradaki fark, uygulamanın kullanılabilirliğini ve performansını optimize etmek için giyilebilir cihazın daha küçük form faktörüne yönelik tasarımınızdadır.

Android Studio; proje kurulumu, kitaplığa dahil etme ve paketleme kolaylığı sağladığından Wear OS geliştirme için önerilen araçtır.

Giyilebilir cihaz tasarımıyla ilgili genel yardım için Wear OS tasarım yönergelerine bakın. İlk giyilebilir uygulamanızı oluşturma konusunda yardım için giyilebilir cihaz uygulamaları oluşturma rehberine bakın.

Wear OS'te ilk harita uygulamanızı oluşturma

Bu hızlı rehberde, Android için Haritalar SDK'sı hakkında bilgi sahibi olduğunuz, uygulamanızda giyilebilir modül oluşturmak için Wear OS kılavuzlarını izlediğiniz ve artık giyilebilir modüle bir harita eklemek istediğiniz varsayılır.

Wear modülünüz için bağımlılık ekleme

Aşağıdaki bağımlılıkların uygulamanızın Wear OS modülünün build.gradle dosyasına eklendiğinden emin olun:

dependencies {
    // ...
    compileOnly 'com.google.android.wearable:wearable:2.9.0'
    implementation 'com.google.android.support:wearable:2.9.0'
    implementation 'com.google.android.gms:play-services-maps:18.2.0'

    // This dependency is necessary for ambient mode
    implementation 'androidx.wear:wear:1.3.0'
}

Bağımlılıklar hakkında daha fazla bilgi için Mevcut projenize Wear OS modülü ekleme adlı kılavuza göz atın.

Kapatmak için hızlıca kaydırma hareketi uygulama ve ilk arka plan rengini ayarlama

Haritayı giyilebilir cihazda görüntülemek için bir SwipeDismissFrameLayout kullanmanız önerilir. SwipeDismissFrameLayout sınıfını kullanarak ekranı kısmak için kaydırma hareketini uygulayarak kullanıcılara ekranın en sol kenarından hızlıca kaydırarak uygulamadan çıkma olanağı tanıyabilirsiniz.

Özel bir başlangıç arka plan rengi ayarlamak için, gerçek harita döşemeleri yüklenene kadar görüntülenecek rengi tanımlamak üzere map:backgroundColor XML özelliğini kullanın.

SwipeDismissFrameLayout ve backgroundColor öğelerini, düzen tanımınıza SupportMapFragment kapsayıcısı olarak ekleyin:

  <androidx.wear.widget.SwipeDismissFrameLayout
      android:id="@+id/map_container"
      android:layout_width="match_parent"
      android:layout_height="match_parent">
    <fragment
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        map:backgroundColor="#fff0b2dd" />
  </androidx.wear.widget.SwipeDismissFrameLayout>

Etkinliğinizde SwipeDismissFrameLayout nesnesini edindiğinizde, bir geri çağırma ekleyin ve aşağıda gösterildiği gibi gerekli kapatma işlemini gerçekleştirmek için geri çağırma davranışını ayarlayın:

Kotlin



class MainActivity : AppCompatActivity(), OnMapReadyCallback,
                     AmbientModeSupport.AmbientCallbackProvider {


    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(MainActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        val mapFrameLayout = findViewById<SwipeDismissFrameLayout>(R.id.map_container)
        mapFrameLayout.addCallback(object : SwipeDismissFrameLayout.Callback() {
            override fun onDismissed(layout: SwipeDismissFrameLayout) {
                onBackPressed()
            }
        })

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    // ...
}

      

Java


public class MainActivity extends AppCompatActivity implements OnMapReadyCallback,
    AmbientModeSupport.AmbientCallbackProvider {


    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(MainActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        final SwipeDismissFrameLayout mapFrameLayout = (SwipeDismissFrameLayout) findViewById(
            R.id.map_container);
        mapFrameLayout.addCallback(new SwipeDismissFrameLayout.Callback() {
            @Override
            public void onDismissed(SwipeDismissFrameLayout layout) {
                onBackPressed();
            }
        });

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    // ...
}

      

Harita ekleme

GoogleMap nesnesinin bir tanıtıcısını almak için her zamanki gibi onMapReady(GoogleMap) geri çağırma yöntemini kullanın. Geri çağırma, harita kullanıma hazır olduğunda tetiklenir. Geri çağırma yönteminde haritaya işaretçi veya çoklu çizgi ekleyebilir, işleyici ekleyebilir ya da kamerayı hareket ettirebilirsiniz. Aşağıdaki örnekte Sidney Opera Binası'nın yakınına bir işaretçi eklenmiştir:

Kotlin



private val sydney = LatLng(-33.85704, 151.21522)

override fun onMapReady(googleMap: GoogleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(
        MarkerOptions().position(sydney)
            .title("Sydney Opera House")
    )

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 10f))
}

      

Java


private static final LatLng SYDNEY = new LatLng(-33.85704, 151.21522);

@Override
public void onMapReady(@NonNull GoogleMap googleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(new MarkerOptions().position(SYDNEY)
        .title("Sydney Opera House"));

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 10));
}

      

Ambiyans modunu etkinleştirme

Android için Haritalar SDK'sı, giyilebilir uygulamalar için ambiyans modunu destekler. Ambiyans modunu destekleyen uygulamalar bazen her zaman açık olarak adlandırılır. Ambiyans modu, kullanıcı artık uygulamayı aktif olarak kullanmıyorken etkinleştirilir ve uygulamanın giyilebilir cihazda görünür durumda kalmasına izin verir.

Android için Haritalar SDK'sı, ambiyans modunda kullanılmak üzere haritanın basitleştirilmiş ve düşük renklerle oluşturulmasını sağlar. Cihaz etkileşimli moddan ambiyans moduna geçtiğinde harita stili otomatik olarak ayarlanır. Ambiyans modunda tüm işaretçiler, nesneler ve kullanıcı arayüzü kontrolleri kaybolur. Bu, uygulamanızın güç tüketimini azaltır ve kadranlar gibi diğer ortam uygulamalarıyla tutarlı bir görünüm ve tarz sağlar.

Uygulamanızın, haritanın ambiyans modunu kullandığından emin olmak için aşağıdaki adımları uygulayın:

  1. Android SDK'nızı, etkinliklerin ambiyans moduna geçmesine izin veren API'ler sağlayan Android 6.0 (API 23) veya sonraki sürümünü içerecek şekilde güncelleyin. SDK'nızı nasıl güncelleyeceğiniz hakkında bilgi edinmek için SDK paketleri ekleme ile ilgili Android belgelerine bakın.
  2. Uygulama manifestinde targetSdkVersion değerini 23 veya daha yüksek bir değere ayarlayarak projenizin Android 6.0 veya sonraki bir sürümü hedeflediğinden emin olun.
  3. Giyilebilir cihaz bağımlılarını uygulamanızın build.gradle dosyasına ekleyin. Bu sayfadaki örneğe bakın.
  4. Uygulamanızı görünür tutma ile ilgili Android eğitim sınıfında açıklandığı gibi, giyilebilir cihaz paylaşılan kitaplık girişini giyilebilir uygulama manifest dosyasına ekleyin.
  5. Uygulamanızı görünür tutma ile ilgili Android eğitim sınıfında açıklandığı gibi, elde kullanılan ve giyilebilir uygulama manifestlerine WAKE_LOCK iznini ekleyin.
  6. Etkinliğinizin onCreate() yönteminde AmbientModeSupport.attach() yöntemini çağırın. Bu işlem, işletim sistemine uygulamanın her zaman açık olduğunu bildirir. Böylece, cihaz kapatıldığında saat yüzüne dönmek yerine ambiyans moduna girer.
  7. Ambiyans modu durumundaki değişiklikleri alabilmesi için AmbientModeSupport.AmbientCallbackProvider arayüzünü Etkinliğinize uygulayın.
  8. Haritanızı, ambiyans modunu destekleyecek şekilde ayarlayın. Bunu, etkinliğin XML düzen dosyasında map:ambientEnabled="true" özelliğini ayarlayarak veya GoogleMapOptions.ambientEnabled(true) özelliğini ayarlayarak programatik olarak yapabilirsiniz. Bu ayar, API'ye ambiyans modunda kullanılması için gerekli harita karolarını önceden yüklemesi gerektiğini bildirir.
  9. Etkinlik ambiyans moduna geçtiğinde sistem, sağladığınız AmbientCallback içinde onEnterAmbient() yöntemini çağırır. onEnterAmbient() değerini geçersiz kılın ve SupportMapFragment.onEnterAmbient(ambientDetails) veya MapView.onEnterAmbient(ambientDetails) işlevini çağırın. API, haritanın etkileşimli olmayan ve düşük renkli bir şekilde oluşturulmasına geçer.
  10. Benzer şekilde, onExitAmbient() için SupportMapFragment.onExitAmbient() veya MapView.onExitAmbient() aramasında. API, haritanın normal şekilde oluşturulmasına döner.

Aşağıdaki kod örneği, etkinlikte ambiyans modunu etkinleştirir:

Kotlin



class AmbientActivity : AppCompatActivity(), AmbientModeSupport.AmbientCallbackProvider {

    private lateinit var mapFragment: SupportMapFragment

    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(AmbientActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
    }

    override fun getAmbientCallback(): AmbientModeSupport.AmbientCallback {
        return object : AmbientModeSupport.AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            override fun onEnterAmbient(ambientDetails: Bundle) {
                super.onEnterAmbient(ambientDetails)
                mapFragment.onEnterAmbient(ambientDetails)
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            override fun onExitAmbient() {
                super.onExitAmbient()
                mapFragment.onExitAmbient()
            }
        }
    }
}

      

Java


public class AmbientActivity extends AppCompatActivity implements
    AmbientModeSupport.AmbientCallbackProvider {

    private SupportMapFragment mapFragment;

    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(AmbientActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
    }

    @Override
    public AmbientCallback getAmbientCallback() {
        return new AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            @Override
            public void onEnterAmbient(Bundle ambientDetails) {
                super.onEnterAmbient(ambientDetails);
                mapFragment.onEnterAmbient(ambientDetails);
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            @Override
            public void onExitAmbient() {
                super.onExitAmbient();
                mapFragment.onExitAmbient();
            }
        };
    }
}

      

Uygulama ambiyans modundayken ekranı güncelleyebilirsiniz. İçerik güncelleme ve genel olarak ambiyans modu hakkında daha fazla bilgi edinmek için uygulamanızı görünür tutma ile ilgili Android eğitim sınıfını inceleyin.

Wear OS'te Street View'ı kullanma

Street View, giyilebilir cihazlarda tam olarak desteklenmektedir.

Bir Street View panoramasını görüntülerken kullanıcıların uygulamadan çıkmasına izin vermek için, uzun tıklama hareketini dinlemek üzere StreetViewPanorama.OnStreetViewPanoramaLongClickListener arayüzünü kullanın. Kullanıcı Street View görüntüsünde bir yeri uzun süre tıkladığında onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation) etkinliği alırsınız. Çıkış düğmesini görüntülemek için DismissOverlayView.show() numaralı telefonu arayın.

Örnek kod

GitHub'da, uygulamanız için başlangıç noktası olarak kullanabileceğiniz örnek bir uygulama mevcuttur. Örnekte, Wear OS'te temel bir Google Haritası'nın nasıl oluşturulacağı gösterilmektedir.

Wear OS'te Maps API'de desteklenen işlevler

Bu bölümde, giyilebilir cihazlardaki haritalar için desteklenen işlevler, avuç içi cihazlarla (telefonlar ve tabletler) karşılaştırıldığında ne gibi farklar olduğu özetlenmiştir. Aşağıda belirtilmeyen tüm API özellikleri, tam API için belgelendiği gibi çalışmalıdır.

İşlevler
Tam etkileşimli mod ve basit mod

Android için Haritalar SDK'sını tam etkileşimli modda veya basit modda kullanabilirsiniz. Giyilebilir cihazda performansı optimize etmek istiyorsanız ve uygulamanızın hareketler veya haritayı kaydırma ve yakınlaştırma gibi etkileşimleri desteklemesi gerekmiyorsa basit modu tercih edebilirsiniz.

Basit modda, kullanıcı haritaya dokunduğunda Google Haritalar mobil uygulamasını başlatma niyeti devre dışıdır ve giyilebilir bir cihazda etkinleştirilemez.

Basit mod ve tam etkileşimli mod arasındaki farkların tam listesi için basit mod dokümanlarına bakın.

Harita araç çubuğu Harita araç çubuğu devre dışı ve giyilebilir cihazlarda etkinleştirilemez.
Kullanıcı arayüzü kontrolleri Giyilebilir cihazlarda kullanıcı arayüzü kontrolleri varsayılan olarak devre dışıdır. Buna yakınlaştırma, pusula ve konum denetimlerim dahildir. Her zamanki gibi UiSettings sınıfını kullanarak bunları etkinleştirebilirsiniz.
Hareketler Tek dokunmalı hareketler beklendiği gibi çalışır. Örneğin, haritayı kaydırmak için dokunup sürükleme, yakınlaştırmak için iki kez dokunma ve uzaklaştırmak için iki parmakla dokunma verilebilir. Çoklu dokunma hareketleri desteği, kullanıcının cihazına bağlı olarak değişir. Çoklu dokunma hareketlerine örnek olarak haritayı yatırmak için iki parmakla itme, yakınlaştırmak için sıkıştırma ve iki parmakla döndürme verilebilir.
İç mekan haritaları ve binalar İç mekan haritaları giyilebilir cihazlarda varsayılan olarak devre dışıdır. GoogleMap.setIndoorEnabled(true) çağrısı yaparak bunları etkinleştirebilirsiniz. İç mekan haritaları etkinleştirildiğinde, haritada varsayılan kat seviyesi gösterilir. Seviye seçici kullanıcı arayüzü öğesi, giyilebilir cihazlarda desteklenmez.
Karo yer paylaşımları Karo yer paylaşımları giyilebilir cihazlarda desteklenmez.

Wear OS'te Google Maps API ile geliştirme için en iyi uygulamalar

Uygulamanızda en iyi kullanıcı deneyimini nasıl sağlarsınız?

  • Harita, ekranın büyük bir kısmını kaplamalıdır. Bu, bir giyilebilir cihazın küçük form faktöründe haritanın kullanılabilirliğini optimize etmek için gereklidir.
  • Uygulamanızın kullanıcı deneyimini tasarlarken giyilebilir bir cihazın düşük pil gücüne sahip olduğunu göz önünde bulundurun. Ekranı etkin ve haritayı görünür kılmak pil performansını etkiler.