Xamarin.Forms Inisialisasi dan Konfigurasi Peta

Artikel
02/07/2020

Kontrol ini Map menggunakan kontrol peta asli pada setiap platform. Ini memberikan pengalaman peta yang cepat dan akrab bagi pengguna, tetapi berarti bahwa beberapa langkah konfigurasi diperlukan untuk mematuhi persyaratan API setiap platform.

Inisialisasi peta

Map Kontrol disediakan oleh Xamarin.Forms.Peta Paket NuGet, yang harus ditambahkan ke setiap proyek dalam solusi.

Setelah menginstal Xamarin.Forms.Peta Paket NuGet, harus diinisialisasi di setiap proyek platform.

Di iOS, ini harus terjadi di AppDelegate.cs dengan memanggil Xamarin.FormsMaps.Init metode setelahXamarin.Forms.Forms.Init metode :

Xamarin.FormsMaps.Init();

Di Android, ini harus terjadi di MainActivity.cs dengan memanggil Xamarin.FormsMaps.Init metode setelahXamarin.Forms.Forms.Init metode :

Xamarin.FormsMaps.Init(this, savedInstanceState);

Pada Platform Windows Universal (UWP), ini harus terjadi di MainPage.xaml.cs dengan memanggil Xamarin.FormsMaps.Init metode dari MainPage konstruktor:

Xamarin.FormsMaps.Init("INSERT_AUTHENTICATION_TOKEN_HERE");

Untuk informasi tentang token autentikasi yang diperlukan di UWP, lihat Platform Windows Universal.

Setelah paket NuGet ditambahkan dan metode inisialisasi yang disebut di dalam setiap aplikasi, Xamarin.Forms.Maps API dapat digunakan dalam proyek kode bersama.

Konfigurasi platform

Konfigurasi tambahan diperlukan di Android dan Platform Windows Universal (UWP) sebelum peta akan ditampilkan. Selain itu, pada iOS, Android, dan UWP, mengakses lokasi pengguna memerlukan izin lokasi untuk diberikan ke aplikasi.

iOS

Menampilkan dan berinteraksi dengan peta di iOS tidak memerlukan konfigurasi tambahan apa pun. Namun, untuk mengakses layanan lokasi, Anda harus mengatur kunci berikut di Info.plist:

iOS 11 dan yang lebih baru
- NSLocationWhenInUseUsageDescription – untuk menggunakan layanan lokasi saat aplikasi sedang digunakan
- NSLocationAlwaysAndWhenInUseUsageDescription – untuk menggunakan layanan lokasi setiap saat
iOS 10 dan yang lebih lama
- NSLocationWhenInUseUsageDescription – untuk menggunakan layanan lokasi saat aplikasi sedang digunakan
- NSLocationAlwaysUsageDescription – untuk menggunakan layanan lokasi setiap saat

Untuk mendukung iOS 11 dan yang lebih lama, Anda dapat menyertakan ketiga kunci: NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, dan NSLocationAlwaysUsageDescription.

Representasi XML untuk kunci ini di Info.plist ditunjukkan di bawah ini. Anda harus memperbarui string nilai untuk mencerminkan bagaimana aplikasi Anda menggunakan informasi lokasi:

<key>NSLocationAlwaysUsageDescription</key>
<string>Can we use your location at all times?</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Can we use your location when your application is being used?</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Can we use your location at all times?</string>

Entri Info.plist juga dapat ditambahkan dalam tampilan Sumber saat mengedit file Info.plist :

Info.plist untuk iOS 8

Perintah kemudian ditampilkan ketika aplikasi mencoba mengakses lokasi pengguna, meminta akses:

Android

Proses konfigurasi untuk menampilkan dan berinteraksi dengan peta di Android adalah:

Dapatkan kunci GOOGLE Peta API dan tambahkan ke manifes.
Tentukan nomor versi layanan Google Play dalam manifes.
Tentukan persyaratan untuk pustaka Apache HTTP Legacy dalam manifes.
[opsional] Tentukan izin WRITE_EXTERNAL_STORAGE dalam manifes.
[opsional] Tentukan izin lokasi dalam manifes.
[opsional] Minta izin lokasi runtime di MainActivity kelas .

Untuk contoh file manifes yang dikonfigurasi dengan benar, lihat AndroidManifest.xml dari aplikasi sampel.

Mendapatkan kunci GOOGLE Peta API

Untuk menggunakan Google Peta API di Android, Anda harus membuat kunci API. Untuk melakukannya, ikuti petunjuk dalam Mendapatkan kunci GOOGLE Peta API.

Setelah Anda mendapatkan kunci API, kunci API harus ditambahkan dalam <application> elemen file Properties/AndroidManifest.xml :

<application ...>
    <meta-data android:name="com.google.android.geo.API_KEY" android:value="PASTE-YOUR-API-KEY-HERE" />
</application>

Ini menyematkan kunci API ke dalam manifes. Tanpa kunci Map API yang valid, kontrol akan menampilkan kisi kosong.

Catatan

com.google.android.geo.API_KEY adalah nama metadata yang direkomendasikan untuk kunci API. Untuk kompatibilitas mundur, com.google.android.maps.v2.API_KEY nama metadata dapat digunakan, tetapi hanya mengizinkan autentikasi ke Android Peta API v2.

Agar APK dapat mengakses Google Peta, Anda harus menyertakan sidik jari SHA-1 dan nama paket untuk setiap keystore (debug dan rilis) yang Anda gunakan untuk menandatangani APK Anda. Misalnya, jika Anda menggunakan satu komputer untuk debug dan komputer lain untuk menghasilkan APK rilis, Anda harus menyertakan sidik jari sertifikat SHA-1 dari keystore debug komputer pertama dan sidik jari sertifikat SHA-1 dari keystore rilis komputer kedua. Ingat juga untuk mengedit kredensial kunci jika Nama Paket aplikasi berubah. Lihat Mendapatkan kunci GOOGLE Peta API.

Tentukan nomor versi layanan Google Play

Tambahkan deklarasi berikut dalam <application> elemen AndroidManifest.xml:

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />

Ini menyematkan versi layanan Google Play yang dikompilasi aplikasi, ke dalam manifes.

Tentukan persyaratan untuk pustaka warisan HTTP Apache

Jika aplikasi Anda Xamarin.Forms menargetkan API 28 atau yang lebih tinggi, Anda harus menambahkan deklarasi berikut dalam <application> elemen AndroidManifest.xml:

<uses-library android:name="org.apache.http.legacy" android:required="false" />

Ini memberi tahu aplikasi untuk menggunakan pustaka klien Apache Http, yang telah dihapus dari bootclasspath di Android 9.

Tentukan izin WRITE_EXTERNAL_STORAGE

Jika aplikasi Anda menargetkan API 22 atau yang lebih rendah, mungkin perlu menambahkan WRITE_EXTERNAL_STORAGE izin ke manifes, sebagai turunan dari <manifest> elemen:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Ini tidak diperlukan jika aplikasi Anda menargetkan API 23 atau yang lebih besar.

Tentukan izin lokasi

Jika aplikasi Anda perlu mengakses lokasi pengguna, Anda harus meminta izin dengan menambahkan ACCESS_COARSE_LOCATION izin atau ACCESS_FINE_LOCATION ke manifes (atau keduanya), sebagai turunan dari <manifest> elemen:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.companyname.myapp">
  ...
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

Izin ini ACCESS_COARSE_LOCATION memungkinkan API untuk menggunakan WiFi atau data seluler, atau keduanya, untuk menentukan lokasi perangkat. Izin ini ACCESS_FINE_LOCATION memungkinkan API untuk menggunakan Global Positioning System (GPS), WiFi, atau data seluler untuk menentukan lokasi yang tepat sebisa mungkin.

Atau, izin ini dapat diaktifkan dengan menggunakan editor manifes untuk menambahkan izin berikut:

AccessCoarseLocation
AccessFineLocation

Ini ditunjukkan pada cuplikan layar di bawah ini:

Izin yang diperlukan untuk Android

Meminta izin lokasi runtime bahasa umum

Jika aplikasi Anda menargetkan API 23 atau yang lebih baru dan perlu mengakses lokasi pengguna, aplikasi harus memeriksa untuk melihat apakah aplikasi tersebut memiliki izin yang diperlukan saat runtime, dan memintanya jika tidak memilikinya. Ini dapat dicapai sebagai berikut:

MainActivity Di kelas , tambahkan bidang berikut:

const int RequestLocationId = 0;

readonly string[] LocationPermissions =
{
    Manifest.Permission.AccessCoarseLocation,
    Manifest.Permission.AccessFineLocation
};

MainActivity Di kelas , tambahkan penimpaan berikutOnStart:

protected override void OnStart()
{
    base.OnStart();

    if ((int)Build.VERSION.SdkInt >= 23)
    {
        if (CheckSelfPermission(Manifest.Permission.AccessFineLocation) != Permission.Granted)
        {
            RequestPermissions(LocationPermissions, RequestLocationId);
        }
        else
        {
            // Permissions already granted - display a message.
        }
    }
}

Asalkan aplikasi menargetkan API 23 atau lebih besar, kode ini melakukan pemeriksaan izin runtime untuk izin.AccessFineLocation Jika izin belum diberikan, permintaan izin dibuat dengan memanggil RequestPermissions metode .

MainActivity Di kelas , tambahkan penimpaan berikutOnRequestPermissionsResult:

public override void OnRequestPermissionsResult(int requestCode, string[] permissions, [GeneratedEnum] Permission[] grantResults)
{
    if (requestCode == RequestLocationId)
    {
        if ((grantResults.Length == 1) && (grantResults[0] == (int)Permission.Granted))
            // Permissions granted - display a message.
        else
            // Permissions denied - display a message.
    }
    else
    {
        base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
    }
}

Penimpaan ini menangani hasil permintaan izin.

Efek keseluruhan dari kode ini adalah bahwa ketika aplikasi meminta lokasi pengguna, dialog berikut ditampilkan yang meminta izin:

Platform Windows Universal

Di UWP, aplikasi Anda harus diautentikasi sebelum dapat menampilkan peta dan menggunakan layanan peta. Untuk mengautentikasi aplikasi, Anda harus menentukan kunci autentikasi peta. Untuk informasi selengkapnya, lihat Meminta kunci autentikasi peta. Token autentikasi kemudian harus ditentukan dalam FormsMaps.Init("AUTHORIZATION_TOKEN") panggilan metode, untuk mengautentikasi aplikasi dengan Bing Peta.

Catatan

Pada UWP, untuk menggunakan layanan peta seperti geocoding, Anda juga harus mengatur MapService.ServiceToken properti ke nilai kunci autentikasi. Ini dapat dicapai dengan baris kode berikut: Windows.Services.Maps.MapService.ServiceToken = "INSERT_AUTH_TOKEN_HERE";.

Selain itu, jika aplikasi Anda perlu mengakses lokasi pengguna, Anda harus mengaktifkan kemampuan lokasi dalam manifes paket. Ini dapat dicapai sebagai berikut:

Di Penjelajah Solusi, klik ganda package.appxmanifest dan pilih tab Kemampuan.

Di daftar Kapabilitas, centang kotak untuk Lokasi. Ini menambahkan location kemampuan perangkat ke file manifes paket.

<Capabilities>
  <!-- DeviceCapability elements must follow Capability elements (if present) -->
  <DeviceCapability Name="location"/>
</Capabilities>

Rilis build

Build rilis UWP menggunakan kompilasi asli .NET untuk mengkompilasi aplikasi langsung ke kode asli. Namun, konsekuensi dari ini adalah bahwa renderer untuk Map kontrol pada UWP dapat ditautkan keluar dari yang dapat dieksekusi. Ini dapat diperbaiki dengan menggunakan kelebihan metode Forms.Init khusus UWP dalam App.xaml.cs:

var assembliesToInclude = new [] { typeof(Xamarin.Forms.Maps.UWP.MapRenderer).GetTypeInfo().Assembly };
Xamarin.Forms.Forms.Init(e, assembliesToInclude);

Kode ini meneruskan perakitan tempat Xamarin.Forms.Maps.UWP.MapRenderer kelas berada, ke Forms.Init metode . Ini memastikan bahwa rakitan tidak ditautkan dari yang dapat dieksekusi oleh proses kompilasi asli .NET.

Penting

Kegagalan untuk melakukan ini akan mengakibatkan Map kontrol tidak muncul saat menjalankan build rilis.

Bagikan melalui

Xamarin.Forms Inisialisasi dan Konfigurasi Peta

Inisialisasi peta

Konfigurasi platform

iOS

Android

Mendapatkan kunci GOOGLE Peta API

Tentukan nomor versi layanan Google Play

Tentukan persyaratan untuk pustaka warisan HTTP Apache

Tentukan izin WRITE_EXTERNAL_STORAGE

Tentukan izin lokasi

Meminta izin lokasi runtime bahasa umum

Platform Windows Universal

Rilis build

Sumber Daya Tambahan:

Bagikan melalui

Xamarin.Forms Inisialisasi dan Konfigurasi Peta

Inisialisasi peta

Konfigurasi platform

iOS

Android

Mendapatkan kunci GOOGLE Peta API

Tentukan nomor versi layanan Google Play

Tentukan persyaratan untuk pustaka warisan HTTP Apache

Tentukan izin WRITE_EXTERNAL_STORAGE

Tentukan izin lokasi

Meminta izin lokasi runtime bahasa umum

Platform Windows Universal

Rilis build

Tautan terkait

Sumber Daya Tambahan: