Partager via

Xamarin.Forms Initialisation et configuration de la carte

  • Article

Le Map contrôle utilise le contrôle de carte natif sur chaque plateforme. Cela offre une expérience de mappage rapide et familière pour les utilisateurs, mais cela signifie que certaines étapes de configuration sont nécessaires pour respecter les exigences de l’API de chaque plateforme.

Initialisation de la carte

Le Map contrôle est fourni par .Xamarin.FormsCartes Package NuGet, qui doit être ajouté à chaque projet de la solution.

Après avoir installé .Xamarin.FormsCartes Le package NuGet doit être initialisé dans chaque projet de plateforme.

Sur iOS, cela doit se produire dans AppDelegate.cs en appelant la Xamarin.FormsMaps.Init méthode après la Xamarin.Forms.Forms.Init méthode :

Xamarin.FormsMaps.Init();

Sur Android, cela doit se produire dans MainActivity.cs en appelant la Xamarin.FormsMaps.Init méthode après la Xamarin.Forms.Forms.Init méthode :

Xamarin.FormsMaps.Init(this, savedInstanceState);

Sur le plateforme Windows universelle (UWP), cela doit se produire dans MainPage.xaml.cs en appelant la Xamarin.FormsMaps.Init méthode du MainPage constructeur :

Xamarin.FormsMaps.Init("INSERT_AUTHENTICATION_TOKEN_HERE");

Pour plus d’informations sur le jeton d’authentification requis sur UWP, consultez plateforme Windows universelle.

Une fois le package NuGet ajouté et la méthode d’initialisation appelée à l’intérieur de chaque application, Xamarin.Forms.Maps les API peuvent être utilisées dans le projet de code partagé.

Configuration de la plateforme

Une configuration supplémentaire est requise sur Android et l’plateforme Windows universelle (UWP) avant l’affichage de la carte. En outre, sur iOS, Android et UWP, l’accès à l’emplacement de l’utilisateur nécessite que les autorisations d’emplacement aient été accordées à l’application.

iOS

L’affichage et l’interaction avec une carte sur iOS ne nécessitent aucune configuration supplémentaire. Toutefois, pour accéder aux services d’emplacement, vous devez définir les clés suivantes dans Info.plist :

Pour prendre en charge iOS 11 et versions antérieures, vous pouvez inclure les trois clés suivantes : NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescriptionet NSLocationAlwaysUsageDescription.

La représentation XML de ces clés dans Info.plist est illustrée ci-dessous. Vous devez mettre à jour les valeurs pour refléter la string façon dont votre application utilise les informations d’emplacement :

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

Les entrées Info.plist peuvent également être ajoutées en mode Source lors de la modification du fichier Info.plist :

Info.plist pour iOS 8

Une invite s’affiche ensuite lorsque l’application tente d’accéder à l’emplacement de l’utilisateur, en demandant l’accès :

Capture d’écran de la demande d’autorisation d’emplacement sur iOS

Android

Le processus de configuration pour l’affichage et l’interaction avec une carte sur Android est le suivant :

  1. Obtenez une clé API Google Cartes et ajoutez-la au manifeste.
  2. Spécifiez le numéro de version des services Google Play dans le manifeste.
  3. Spécifiez la condition requise pour la bibliothèque Héritée Apache HTTP dans le manifeste.
  4. [facultatif] Spécifiez l’autorisation WRITE_EXTERNAL_STORAGE dans le manifeste.
  5. [facultatif] Spécifiez les autorisations d’emplacement dans le manifeste.
  6. [facultatif] Demandez des autorisations d’emplacement d’exécution dans la MainActivity classe.

Pour obtenir un exemple de fichier manifeste correctement configuré, consultez AndroidManifest.xml de l’exemple d’application.

Obtenir une clé API Google Cartes

Pour utiliser l’API Google Cartes sur Android, vous devez générer une clé API. Pour ce faire, suivez les instructions de l’obtention d’une clé API Google Cartes.

Une fois que vous avez obtenu une clé API, elle doit être ajoutée dans l’élément <application> du fichier Properties/AndroidManifest.xml :

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

Cela incorpore la clé API dans le manifeste. Sans clé API valide, le Map contrôle affiche une grille vide.

Remarque

com.google.android.geo.API_KEY est le nom de métadonnées recommandé pour la clé API. Pour la compatibilité descendante, le com.google.android.maps.v2.API_KEY nom des métadonnées peut être utilisé, mais autorise uniquement l’authentification auprès de l’API Android Cartes v2.

Pour que votre APK accède à Google Cartes, vous devez inclure des empreintes digitales SHA-1 et des noms de package pour chaque magasin de clés (débogage et mise en production) que vous utilisez pour signer votre APK. Par exemple, si vous utilisez un ordinateur pour déboguer et un autre ordinateur pour générer l’APK de mise en production, vous devez inclure l’empreinte digitale du certificat SHA-1 à partir du magasin de clés de débogage du premier ordinateur et de l’empreinte digitale du certificat SHA-1 à partir du magasin de clés de mise en production du deuxième ordinateur. N’oubliez pas également de modifier les informations d’identification de clé si le nom du package de l’application change. Consultez Obtenir une clé API Google Cartes.

Spécifier le numéro de version des services Google Play

Ajoutez la déclaration suivante dans l’élément <application> de AndroidManifest.xml :

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

Cela incorpore la version des services Google Play que l’application a été compilée avec, dans le manifeste.

Spécifier la condition requise pour la bibliothèque héritée Apache HTTP

Si votre Xamarin.Forms application cible l’API 28 ou une version ultérieure, vous devez ajouter la déclaration suivante dans l’élément <application> de AndroidManifest.xml :

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

Cela indique à l’application d’utiliser la bibliothèque cliente Apache Http, qui a été supprimée de l’application bootclasspath dans Android 9.

Spécifier l’autorisation WRITE_EXTERNAL_STORAGE

Si votre application cible l’API 22 ou inférieure, il peut être nécessaire d’ajouter l’autorisation WRITE_EXTERNAL_STORAGE au manifeste, en tant qu’enfant de l’élément <manifest> :

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

Cela n’est pas nécessaire si votre application cible l’API 23 ou ultérieure.

Spécifier les autorisations d’emplacement

Si votre application doit accéder à l’emplacement de l’utilisateur, vous devez demander l’autorisation en ajoutant ou en ajoutant les ACCESS_COARSE_LOCATIONACCESS_FINE_LOCATION autorisations au manifeste (ou les deux), en tant qu’enfant de l’élément <manifest> :

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

L’autorisation ACCESS_COARSE_LOCATION permet à l’API d’utiliser des données Wi-Fi ou mobiles, ou les deux, pour déterminer l’emplacement de l’appareil. Les ACCESS_FINE_LOCATION autorisations permettent à l’API d’utiliser le système de positionnement global (GPS), le Wi-Fi ou les données mobiles pour déterminer un emplacement précis possible.

Vous pouvez également activer ces autorisations à l’aide de l’éditeur de manifeste pour ajouter les autorisations suivantes :

  • AccessCoarseLocation
  • AccessFineLocation

Voici ce qui s’affiche dans la capture d’écran ci-dessous :

Autorisations requises pour Android

Demander des autorisations d’emplacement d’exécution

Si votre application cible l’API 23 ou une version ultérieure et doit accéder à l’emplacement de l’utilisateur, elle doit case activée pour voir s’il dispose de l’autorisation requise au moment de l’exécution et le demander s’il ne l’a pas. Cela peut être accompli de la façon suivante :

  1. Dans la MainActivity classe, ajoutez les champs suivants :

    const int RequestLocationId = 0;

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

  2. Dans la MainActivity classe, ajoutez le remplacement suivant OnStart :

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

    À condition que l’application cible l’API 23 ou une version ultérieure, ce code effectue une autorisation d’exécution case activée pour l’autorisationAccessFineLocation. Si l’autorisation n’a pas été accordée, une demande d’autorisation est effectuée en appelant la RequestPermissions méthode.

  3. Dans la MainActivity classe, ajoutez le remplacement suivant OnRequestPermissionsResult :

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

    Ce remplacement gère le résultat de la demande d’autorisation.

L’effet global de ce code est que lorsque l’application demande l’emplacement de l’utilisateur, la boîte de dialogue suivante s’affiche qui demande l’autorisation :

Capture d’écran de la demande d’autorisation d’emplacement sur Android

Plateforme Windows universelle

Sur UWP, votre application doit être authentifiée avant de pouvoir afficher une carte et consommer des services de carte. Pour authentifier votre application, vous devez spécifier une clé d’authentification de mappage. Pour plus d’informations, consultez Demander une clé d’authentification de mappage. Le jeton d’authentification doit ensuite être spécifié dans l’appel FormsMaps.Init("AUTHORIZATION_TOKEN") de méthode pour authentifier l’application auprès de Bing Cartes.

Remarque

Sur UWP, pour utiliser des services cartographiques tels que le géocodage, vous devez également définir la MapService.ServiceToken propriété sur la valeur de clé d’authentification. Cette opération peut être effectuée avec la ligne de code suivante : Windows.Services.Maps.MapService.ServiceToken = "INSERT_AUTH_TOKEN_HERE";.

En outre, si votre application doit accéder à l’emplacement de l’utilisateur, vous devez activer la fonctionnalité d’emplacement dans le manifeste du package. Cela peut être accompli de la façon suivante :

  1. Dans Explorateur de solutions, double-cliquez sur package.appxmanifest et sélectionnez l’onglet Fonctionnalités.

  2. Dans la liste Fonctionnalités, case activée la zone emplacement. Cela ajoute la fonctionnalité d’appareil location au fichier manifeste du package.

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

Builds de mise en production

Les builds de version UWP utilisent la compilation native .NET pour compiler l’application directement dans du code natif. Toutefois, une conséquence est que le renderer du Map contrôle sur UWP peut être lié hors de l’exécutable. Cela peut être résolu à l’aide d’une surcharge spécifique à UWP de la Forms.Init méthode dans App.xaml.cs :

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

Ce code transmet l’assembly dans lequel réside la Xamarin.Forms.Maps.UWP.MapRenderer classe, à la Forms.Init méthode. Cela garantit que l’assembly n’est pas lié à l’exécutable par le processus de compilation natif .NET.

Important

L’échec de cette opération entraîne l’apparition du contrôle lors de l’exécution Map d’une build de mise en production.