Maps API di Wear OS

Dengan menggunakan Maps SDK for Android, Anda dapat membuat aplikasi wearable berbasis peta yang berjalan langsung di perangkat Wear OS by Google. Pengguna aplikasi Anda dapat melihat lokasi mereka di peta cukup dengan melihat ke pergelangan tangannya. Misalnya, pengguna dapat menandai posisinya pada rute kemudian memperbesarnya untuk melihat secara detail, atau mengetuk penanda untuk melihat jendela info yang disediakan aplikasi Anda.

Halaman ini menjelaskan fungsi API yang tersedia pada perangkat Wear dan membantu Anda memulai pembuatan aplikasi.

Memulai Wear OS

Membuat aplikasi wearable dengan Maps SDK for Android pada dasarnya sama dengan membuat aplikasi Google Maps untuk perangkat Android lainnya. Perbedaannya terletak pada desain Anda untuk faktor bentuk perangkat wearable yang lebih kecil, untuk mengoptimalkan kegunaan dan performa aplikasi.

Android Studio adalah alat yang direkomendasikan untuk pengembangan Wear OS, karena menyediakan penyiapan project, penyertaan library, dan kepraktisan paket.

Untuk mendapatkan bantuan umum dalam mendesain aplikasi wearable, lihat pedoman desain Wear OS. Untuk mendapatkan bantuan dalam membuat aplikasi wearable pertama Anda, lihat panduan untuk membuat aplikasi wearable.

Membuat aplikasi peta pertama Anda di Wear OS

Panduan cepat ini mengasumsikan Anda telah memahami Maps SDK for Android, telah mengikuti panduan Wear OS untuk membuat modul wearable di aplikasi, dan sekarang Anda ingin menambahkan peta ke modul wearable.

Menambahkan dependensi untuk modul Wear

Pastikan dependensi berikut disertakan dalam file build.gradle di modul Wear OS aplikasi Anda:

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

Untuk informasi selengkapnya tentang dependensi, lihat panduan untuk Menambahkan modul Wear OS dalam project yang ada.

Menerapkan gestur geser untuk menutup dan menetapkan warna latar belakang awal

Sebaiknya gunakan SwipeDismissFrameLayout untuk menampilkan peta di perangkat wearable. Dengan menggunakan class SwipeDismissFrameLayout, Anda dapat menerapkan gestur geser untuk menutup yang memberi pengguna cara untuk keluar dari aplikasi dengan menggeser dari tepi layar paling kiri.

Untuk menetapkan warna latar belakang awal kustom, gunakan atribut XML map:backgroundColor untuk menentukan warna yang akan ditampilkan hingga petak peta sebenarnya dimuat.

Tambahkan elemen SwipeDismissFrameLayout dan backgroundColor ke definisi tata letak Anda sebagai penampung SupportMapFragment:

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

Saat mendapatkan objek SwipeDismissFrameLayout dalam aktivitas Anda, tambahkan callback dan tetapkan perilaku callback ini untuk melakukan tindakan penutupan yang diperlukan seperti yang ditunjukkan di bawah:

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

    // ...
}

      

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

    // ...
}

      

Menambahkan peta

Gunakan metode callback onMapReady(GoogleMap) seperti biasa, untuk mendapatkan handle ke objek GoogleMap. Callback akan dipicu jika peta sudah siap digunakan. Dalam metode callback, Anda dapat menambahkan penanda atau polyline ke peta, menambahkan pemroses, atau memindahkan kamera. Contoh di bawah menunjukkan penambahan penanda di dekat Sydney Opera House:

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

      

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

      

Mengaktifkan mode standby

Maps SDK for Android mendukung mode standby untuk aplikasi wearable. Aplikasi yang mendukung mode standby kadang-kadang disebut aplikasi selalu aktif (always on). Mode standby diaktifkan saat pengguna tidak lagi menggunakan aplikasi secara aktif, dan memungkinkan aplikasi untuk tetap terlihat di perangkat wearable.

Maps SDK for Android menyediakan rendering peta yang disederhanakan dengan warna terbatas untuk digunakan dalam mode standby, dan gaya peta secara otomatis disesuaikan jika perangkat beralih dari mode interaktif ke mode standby. Semua penanda, objek, dan kontrol UI akan menghilang dalam mode standby. Penyesuaian ini akan mengurangi konsumsi daya aplikasi dan memastikan tampilan dan nuansa yang konsisten dengan aplikasi standby lainnya, seperti tampilan jam.

Ikuti langkah-langkah berikut untuk memastikan aplikasi Anda menggunakan mode standby peta.

1. Update Android SDK Anda untuk menyertakan Android 6.0 (API 23) atau versi yang lebih tinggi, yang menyediakan API yang memungkinkan aktivitas untuk beralih ke mode standby. Untuk informasi tentang cara mengupdate SDK, lihat dokumentasi Android tentang menambahkan paket SDK.
2. Pastikan project Anda menargetkan Android 6.0 atau versi yang lebih tinggi, dengan menetapkan targetSdkVersion ke 23 atau versi yang lebih tinggi di manifes aplikasi.
3. Tambahkan dependensi wearable ke file build.gradle aplikasi Anda. Lihat contoh di halaman ini.
4. Tambahkan entri koleksi bersama wearable ke manifes aplikasi wearable, seperti yang dijelaskan di kelas pelatihan Android tentang menjaga agar aplikasi Anda tetap terlihat.
5. Tambahkan izin WAKE_LOCK ke manifes aplikasi perangkat genggam dan wearable, seperti yang dijelaskan dalam kelas pelatihan Android tentang menjaga agar aplikasi Anda tetap terlihat.
6. Dalam metode onCreate() aktivitas Anda, panggil metode AmbientModeSupport.attach(). Tindakan ini akan memberi tahu sistem operasi bahwa aplikasi akan selalu aktif, sehingga jika baterai perangkat hampir habis, aplikasi akan masuk ke mode standby dan bukan kembali ke tampilan jam.
7. Terapkan antarmuka AmbientModeSupport.AmbientCallbackProvider dalam Aktivitas Anda agar dapat menerima perubahan status mode standby.
8. Atur agar peta Anda mendukung mode standby. Anda dapat melakukannya dengan menetapkan atribut map:ambientEnabled="true" dalam file tata letak XML aktivitas, atau melakukannya secara terprogram dengan menetapkan GoogleMapOptions.ambientEnabled(true). Setelan ini akan memberi tahu API agar memuat lebih dahulu petak peta yang diperlukan untuk digunakan dalam mode standby.
9. Saat aktivitas ini beralih ke mode standby, sistem akan memanggil metode onEnterAmbient() dalam AmbientCallback yang Anda berikan. Ganti onEnterAmbient() lalu panggil SupportMapFragment.onEnterAmbient(ambientDetails) atau MapView.onEnterAmbient(ambientDetails). API akan beralih ke rendering non-interaktif dan rendah-warna untuk peta.
10. Begitu pula, dalam onExitAmbient(), panggil SupportMapFragment.onExitAmbient() atau MapView.onExitAmbient(). API akan beralih ke rendering normal untuk peta.

Contoh kode berikut akan mengaktifkan mode standby dalam aktivitas:

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

      

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

      

Anda bisa memperbarui layar saat aplikasi berada dalam mode standby. Untuk detail selengkapnya tentang memperbarui konten dan tentang mode standby secara umum, lihat kelas pelatihan Android tentang menjaga agar aplikasi Anda tetap terlihat.

Menggunakan Street View di Wear OS

Street View didukung sepenuhnya pada perangkat wearable.

Agar pengguna dapat keluar dari aplikasi saat menampilkan panorama Street View, gunakan antarmuka StreetViewPanorama.OnStreetViewPanoramaLongClickListener untuk memproses gestur klik lama. Jika pengguna mengklik lama suatu tempat pada gambar Street View, Anda akan menerima peristiwa onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). Panggil DismissOverlayView.show() untuk menampilkan tombol keluar.

Kode contoh

Aplikasi contoh tersedia di GitHub, yang dapat digunakan sebagai titik awal untuk aplikasi Anda. Contoh ini menunjukkan cara menyiapkan Google Maps dasar di Wear OS.

Fungsi yang didukung dalam Maps API di Wear OS

Bagian ini menguraikan beberapa perbedaan dalam fungsi yang didukung untuk peta di perangkat wearable jika dibandingkan dengan perangkat genggam (ponsel dan tablet). Semua fitur API yang tidak disebutkan di bawah ini akan bekerja seperti yang didokumentasikan untuk API lengkap.

Praktik terbaik untuk pengembangan dengan Maps API di Wear OS

Cara memberikan pengalaman pengguna terbaik di aplikasi Anda:

• Peta harus memenuhi sebagian besar layar. Hal ini diperlukan untuk mengoptimalkan kegunaan peta pada perangkat wearable dengan faktor bentuk kecil.
• Saat mendesain pengalaman pengguna aplikasi Anda, pertimbangkan fakta bahwa perangkat wearable memiliki daya baterai yang rendah. Membuat layar tetap aktif dan peta terlihat akan memengaruhi performa baterai.