Passer au contenu
Capgo - Live Updates for Capacitor Apps Capgo

Commencer

##Installation

Ce plugin prend en charge Capacitor v7 :

CapacitorPlugin
v7v7
Terminal window
npm install @capgo/background-geolocation
npx cap update

Platform Setup

Section titled “Platform Setup”

iOS

Section titled “iOS”

Ajoutez les clés suivantes à Info.plist. :

<dict>
  ...
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>We need to track your location</string>
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>We need to track your location while your device is locked.</string>
  <key>UIBackgroundModes</key>
  <array>
    <string>location</string>
  </array>
  ...
</dict>

Android

Section titled “Android”

Définissez l’option android.useLegacyBridge sur true dans votre configuration Capacitor. Cela empêche les mises à jour de localisation de s’arrêter après 5 minutes en arrière-plan. See https://capacitorjs.com/docs/config and https://github.com/capacitor-community/background-geolocation/issues/89.

Sur Android 13+, l’application a besoin de l’autorisation d’exécution POST_NOTIFICATIONS pour afficher la notification persistante informant l’utilisateur que sa position est utilisée en arrière-plan. Cette autorisation d’exécution est demandée une fois l’autorisation de localisation accordée.

Si votre application transfère les mises à jour de localisation à un serveur en temps réel, sachez qu’après 5 minutes en arrière-plan, Android limitera les requêtes HTTP lancées à partir de WebView. La solution consiste à utiliser un plugin HTTP natif tel que CapacitorHttp. See https://github.com/capacitor-community/background-geolocation/issues/14.

Une configuration spécifique à Android peut être effectuée dans strings.xml :

<resources>
    <!--
        The channel name for the background notification. This will be visible
        when the user presses & holds the notification. It defaults to
        "Background Tracking".
    -->
    <string name="capacitor_background_geolocation_notification_channel_name">
        Background Tracking
    </string>


    <!--
        The icon to use for the background notification. Note the absence of a
        leading "@". It defaults to "mipmap/ic_launcher", the app's launch icon.


        If a raster image is used to generate the icon (as opposed to a vector
        image), it must have a transparent background. To make sure your image
        is compatible, select "Notification Icons" as the Icon Type when
        creating the image asset in Android Studio.


        An incompatible image asset will cause the notification to misbehave in
        a few telling ways, even if the icon appears correctly:


          - The notification may be dismissable by the user when it should not
            be.
          - Tapping the notification may open the settings, not the app.
          - The notification text may be incorrect.
    -->
    <string name="capacitor_background_geolocation_notification_icon">
        drawable/ic_tracking
    </string>


    <!--
        The color of the notification as a string parseable by
        android.graphics.Color.parseColor. Optional.
    -->
    <string name="capacitor_background_geolocation_notification_color">
        yellow
    </string>
</resources>

Utilisation

Section titled “Utilisation”
import { BackgroundGeolocation } from "@capgo/background-geolocation";


BackgroundGeolocation.start(
    {
        backgroundMessage: "Cancel to prevent battery drain.",
        backgroundTitle: "Tracking You.",
        requestPermissions: true,
        stale: false,
        distanceFilter: 50
    },
    (location, error) => {
        if (error) {
            if (error.code === "NOT_AUTHORIZED") {
                if (window.confirm(
                    "This app needs your location, " +
                    "but does not have permission.\n\n" +
                    "Open settings now?"
                )) {
                    // It can be useful to direct the user to their device's
                    // settings when location permissions have been denied. The
                    // plugin provides the 'openSettings' method to do exactly
                    // this.
                    BackgroundGeolocation.openSettings();
                }
            }
            return console.error(error);
        }
        return console.log(location);
    }
).then(() => {
    // When location updates are no longer needed, the plugin should be stopped by calling
    BackgroundGeolocation.stop();
});


// Set a planned route to get a notification sound when a new location arrives and it's not on the route:


BackgroundGeolocation.setPlannedRoute({soundFile: "assets/myFile.mp3", route: [[1,2], [3,4]], distance: 30 });


// If you just want the current location, try something like this. The longer
// the timeout, the more accurate the guess will be. I wouldn't go below about 100ms.
function guessLocation(callback, timeout) {
    let last_location;
    BackgroundGeolocation.start(
        {
            requestPermissions: false,
            stale: true
        },
        (location) => {
            last_location = location || undefined;
        }
    ).then(() => {
        setTimeout(() => {
            callback(last_location);
            BackgroundGeolocation.stop();
        }, timeout);
    });
}

API

Section titled “API”

début(…)

Section titled “début(…)”
start(options: StartOptions, callback: (position?: Location | undefined, error?: CallbackError | undefined) => void) => Promise<void>

Pour commencer à écouter les changements dans l’emplacement de l’appareil, appelez cette méthode. Une promesse est renvoyée pour indiquer que l’appel est terminé. Le rappel sera appelé à chaque fois qu’un nouvel emplacement est disponible, ou s’il y a eu une erreur lors de l’appel de cette méthode. Ne comptez pas sur le rejet d’une promesse pour cela.

ParamTapezDescriptif
optionsStartOptionsLes options de configuration
callback(position?: Location, error?: CallbackError) => voidLa fonction de rappel invoquée lorsqu’un nouvel emplacement est disponible ou qu’une erreur se produit

arrête()

Section titled “arrête()”
stop() => Promise<void>

Arrête les mises à jour de localisation.

openSettings()

Section titled “openSettings()”
openSettings() => Promise<void>

Opens the device’s location settings page. Utile pour demander aux utilisateurs d’activer les services de localisation ou d’ajuster les autorisations.

setPlannedRoute(…)

Section titled “setPlannedRoute(…)”
setPlannedRoute(options: SetPlannedRouteOptions) => Promise<void>

Lit un fichier sonore lorsque l’utilisateur s’écarte de l’itinéraire prévu. Cela doit être utilisé pour jouer un son (en arrière-plan également, uniquement pour les natifs).| Paramètres | Tapez | Descriptif | | ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------- | | options | SetPlannedRouteOptions | Les options de paramétrage de l’itinéraire prévu et du fichier son |

##Interfaces

### Options de démarrage

Les options de configuration des mises à jour de localisation.| Accessoire | Tapez | Descriptif | Par défaut | | -------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | backgroundMessage | string | Si l’option “backgroundMessage” est définie, le plugin fournira des mises à jour de localisation, que l’application soit en arrière-plan ou au premier plan. Si elle n’est pas définie, les mises à jour de localisation ne sont garanties qu’au premier plan. Cela est vrai sur les deux plateformes. Le Android, une notification doit être affichée pour continuer à recevoir des mises à jour de localisation en arrière-plan. Cette option spécifie le texte de cette notification. | | | backgroundTitle | string | Le titre de la notification mentionnée ci-dessus. | "Utiliser votre position" | | requestPermissions | boolean | Indique si les autorisations doivent être demandées automatiquement à l’utilisateur, si elles ne sont pas déjà accordées. | true | | stale | boolean | Si « vrai », des emplacements obsolètes peuvent être fournis pendant que l’appareil obtient une position GPS. Vous êtes responsable de la vérification de la propriété « time ». Si « faux », les emplacements sont garantis être à jour. | false | | distanceFilter | number | Distance en mètres que l’appareil doit parcourir avant qu’une nouvelle mise à jour de localisation ne soit déclenchée. Ceci est utilisé pour filtrer les petits mouvements et réduire le nombre de mises à jour.| 0 |### Localisation

Représente un emplacement géographique avec divers attributs. Contient toutes les propriétés de localisation standard renvoyées par les fournisseurs GPS/réseau.

AccessoireTapezDescriptif
latitudenumberLatitude en degrés. Plage : -90,0 à +90,0
longitudenumberLongitude en degrés. Plage : -180,0 à +180,0
accuracynumberRayon d’incertitude horizontale en mètres, avec un niveau de confiance de 68 %. Des valeurs inférieures indiquent une localisation plus précise.
altitudenumber | nullMètres au-dessus du niveau de la mer (ou nul si non disponible).
altitudeAccuracynumber | nullIncertitude verticale en mètres, avec un niveau de confiance de 68 % (ou nul si non disponible).
simulatedbooleantrue si l’emplacement a été simulé par un logiciel plutôt que par GPS. Utile pour détecter des emplacements fictifs en cours de développement ou de test.
bearingnumber | nullÉcart par rapport au nord vrai en degrés (ou nul si non disponible). Plage : 0,0 à 360,0
speednumber | nullVitesse en mètres par seconde (ou nulle si non disponible).
timenumber | nullHeure à laquelle l’emplacement a été produit, en millisecondes depuis l’époque Unix. Utilisez ceci pour vérifier si un emplacement est obsolète lorsque vous utilisez stale: true.

Erreur de rappel

Section titled “Erreur de rappel”

Objet d’erreur qui peut être transmis au rappel de début d’emplacement. Étend l’erreur standard avec des codes d’erreur facultatifs.

AccessoireTapezDescriptif
codestringCode d’erreur facultatif pour une gestion des erreurs plus spécifique.

Définir les options d’itinéraire planifié| Accessoire | Tapez | Descriptif | Par défaut |

Section titled “Définir les options d’itinéraire planifié| Accessoire | Tapez | Descriptif | Par défaut |”

| --------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | soundFile | string | Le nom du fichier son à lire. Il doit s’agir d’un chemin relatif sonore valide dans le dossier public de l’application pour fonctionner à la fois sur les plates-formes Web et natives. Il n’est pas nécessaire d’inclure le dossier public dans le chemin. | | | route | [number, number][] | L’itinéraire planifié sous la forme d’un tableau de paires de longitude et de latitude. Chaque paire représente un point sur l’itinéraire. Ceci est utilisé pour définir un itinéraire que l’utilisateur peut suivre. L’itinéraire est utilisé pour émettre un son lorsque l’utilisateur s’en écarte. | | | distance | number | La distance en mètres que l’utilisateur doit s’écarter de l’itinéraire prévu pour déclencher le son. Ceci est utilisé pour déterminer à quelle distance de l’itinéraire l’utilisateur peut se trouver avant que le son ne soit joué. Si elle n’est pas spécifiée, une valeur par défaut de 50 mètres est utilisée. | 50 |