Geofences erstellen und überwachen

Beim Geofencing wird der aktuelle Standort des Nutzers mit seiner Nähe zu Orten kombiniert, die für ihn interessant sein könnten. So markieren Sie Ort von Interesse, geben Sie den Breiten- und Längengrad an. Um die Entfernung für den Standort hinzufügen, fügen Sie einen Umkreis hinzu. Breitengrad, Längengrad und Radius definieren einen Geofence, kreisförmiger Fläche oder Zaun um den betreffenden Ort herum.

Sie können mehrere aktive Geofences haben, mit einem Limit von 100 pro App und pro Gerätenutzer. Für jede können Sie die Standortdienste bitten, Ihnen Eingangs- und Ausstiegsereignisse zu senden. Sie können aber auch Ein Verweildauer bzw. eine Wartezeit im Geofence-Bereich, bevor ein Ereignis ausgelöst wird. Ich kann die Dauer eines Geofence durch Angabe einer Ablaufzeit in Millisekunden begrenzen. Nach Ablauf des Geofences wird er von den Standortdiensten automatisch entfernt.

In dieser Lektion erfahren Sie, wie Sie Geofences hinzufügen und entfernen und wie Sie Geofence-Übergänge erkennen. mit BroadcastReceiver.

Hinweis:Auf Wear-Geräten nutzen die Geofencing APIs nicht effizient Energie. Wir empfehlen diese APIs nicht für Wear. Weitere Informationen finden Sie unter Energie und Akku schonen.

Einrichtung für die Geofence-Überwachung

Der erste Schritt beim Anfordern von Geofencing-Monitoring besteht darin, Berechtigungen. Damit Sie Geofencing verwenden können, muss Ihre App Folgendes anfordern:

• ACCESS_FINE_LOCATION
• ACCESS_BACKGROUND_LOCATION Ihre App ist auf Android 10 (API-Level 29) oder höher ausgerichtet.

Weitere Informationen finden Sie im Leitfaden zum Anfordern von Berechtigungen zur Standortermittlung.

Wenn Sie mit BroadcastReceiver auf Geofence-Übergänge warten möchten, fügen Sie ein Element mit dem Dienstnamen hinzu. Dieses Element muss Ein untergeordnetes Element des <application>-Elements:

<application
   android:allowBackup="true">
   ...
   <receiver android:name=".GeofenceBroadcastReceiver"/>
<application/>

Wenn Sie auf die Standort-APIs zugreifen möchten, müssen Sie eine Instanz des Geofencing-Clients erstellen. So stellen Sie eine Verbindung zu Ihrem Client her:

KotlinJava

lateinit var geofencingClient: GeofencingClient

override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    geofencingClient = LocationServices.getGeofencingClient(this)
}

private GeofencingClient geofencingClient;

@Override
public void onCreate(Bundle savedInstanceState) {
    // ...
    geofencingClient = LocationServices.getGeofencingClient(this);
}

Geofences erstellen und hinzufügen

Ihre App muss Geofences mithilfe der Builder-Klasse der Location API für Erstellen von Geofence-Objekten und die Convenience-Klasse für das Hinzufügen dieser Objekte. Für die Verarbeitung der Intents, die von Standortdiensten bei Geofence-Übergängen gesendet werden, können Sie PendingIntent, wie in diesem Abschnitt gezeigt.

Hinweis: Auf Geräten mit nur einem Nutzer ist die Anzahl der Geofences pro App auf 100 beschränkt. Auf Geräten mit mehreren Nutzern ist die Anzahl der Geofences pro App und Nutzer auf 100 beschränkt.

Geofence-Objekte erstellen

Erstellen Sie zuerst mit Geofence.Builder einen Geofence und legen Sie den gewünschten Radius, die Dauer und die Übergangstypen für den Geofence fest. So füllen Sie beispielsweise ein Listenobjekt:

KotlinJava

geofenceList.add(Geofence.Builder()
        // Set the request ID of the geofence. This is a string to identify this
        // geofence.
        .setRequestId(entry.key)

        // Set the circular region of this geofence.
        .setCircularRegion(
                entry.value.latitude,
                entry.value.longitude,
                Constants.GEOFENCE_RADIUS_IN_METERS
        )

        // Set the expiration duration of the geofence. This geofence gets automatically
        // removed after this period of time.
        .setExpirationDuration(Constants.GEOFENCE_EXPIRATION_IN_MILLISECONDS)

        // Set the transition types of interest. Alerts are only generated for these
        // transition. We track entry and exit transitions in this sample.
        .setTransitionTypes(Geofence.GEOFENCE_TRANSITION_ENTER or Geofence.GEOFENCE_TRANSITION_EXIT)

        // Create the geofence.
        .build())

geofenceList.add(new Geofence.Builder()
    // Set the request ID of the geofence. This is a string to identify this
    // geofence.
    .setRequestId(entry.getKey())

    .setCircularRegion(
            entry.getValue().latitude,
            entry.getValue().longitude,
            Constants.GEOFENCE_RADIUS_IN_METERS
    )
    .setExpirationDuration(Constants.GEOFENCE_EXPIRATION_IN_MILLISECONDS)
    .setTransitionTypes(Geofence.GEOFENCE_TRANSITION_ENTER |
            Geofence.GEOFENCE_TRANSITION_EXIT)
    .build());

In diesem Beispiel werden Daten aus einer Konstantendatei abgerufen. In der Praxis können Apps basierend auf dem Standort des Nutzers dynamisch Geofences erstellen.

Geofences und erste Trigger angeben

Im folgenden Snippet wird die Klasse GeofencingRequest verwendet. und der verschachtelten GeofencingRequestBuilder-Klasse Geben Sie die zu überwachenden Geofences an und legen Sie fest, wie verwandte Geofence-Ereignisse ausgelöst werden:

KotlinJava

private fun getGeofencingRequest(): GeofencingRequest {
    return GeofencingRequest.Builder().apply {
        setInitialTrigger(GeofencingRequest.INITIAL_TRIGGER_ENTER)
        addGeofences(geofenceList)
    }.build()
}

private GeofencingRequest getGeofencingRequest() {
    GeofencingRequest.Builder builder = new GeofencingRequest.Builder();
    builder.setInitialTrigger(GeofencingRequest.INITIAL_TRIGGER_ENTER);
    builder.addGeofences(geofenceList);
    return builder.build();
}

Dieses Beispiel zeigt die Verwendung von zwei Geofence-Triggern. Die GEOFENCE_TRANSITION_ENTER-Übergang wird ausgelöst, wenn ein Gerät einen Geofence betritt, und die GEOFENCE_TRANSITION_EXIT-Übergang wird ausgelöst, wenn ein Gerät einen Geofence verlässt. Angabe INITIAL_TRIGGER_ENTER teilt den Standortdiensten mit, GEOFENCE_TRANSITION_ENTER sollte ausgelöst werden, wenn sich das Gerät bereits im Geofence befindet.

In vielen Fällen empfiehlt es sich, stattdessen INITIAL_TRIGGER_DWELL, Dadurch werden nur dann Ereignisse ausgelöst, wenn der Nutzer für eine festgelegte Dauer innerhalb eines Geofence anhält. Dieser Ansatz kann dazu beitragen, „Benachrichtigungs-Spam“ zu reduzieren die sich aufgrund einer hohen Anzahl an Benachrichtigungen die Geofences kurzzeitig betreten und verlassen. Eine weitere Strategie, um die besten Ergebnisse mit Ihren Geofences zu erzielen, besteht darin, einen Mindestradius von 100 Metern festzulegen. Dadurch wird die Standortgenauigkeit berücksichtigt, und trägt dazu bei, den Stromverbrauch der Geräte zu senken.

Übertragungsempfänger für Geofence-Übergänge definieren

Eine Intent, die von den Standortdiensten gesendet wird, kann verschiedene Aktionen auslösen in: Ihrer App an. Sie sollten jedoch keine Aktivität oder Fragmentierung starten, da Komponenten nur als Reaktion auf eine Nutzeraktion sichtbar werden sollen. In vielen Fällen ist eine BroadcastReceiver eine gute Möglichkeit, einen Geofence-Übergang zu verarbeiten. Ein BroadcastReceiver wird aktualisiert, wenn ein Ereignis eintritt, z. B. wenn ein Nutzer ein Geofence betritt oder verlässt. Außerdem kann damit eine lang andauernde Hintergrundarbeit gestartet werden.

Das folgende Snippet zeigt, zum Definieren eines PendingIntent-Objekts, das einen BroadcastReceiver startet:

KotlinJava

class MainActivity : AppCompatActivity() {

    // ...

    private val geofencePendingIntent: PendingIntent by lazy {
        val intent = Intent(this, GeofenceBroadcastReceiver::class.java)
        // We use FLAG_UPDATE_CURRENT so that we get the same pending intent back when calling
        // addGeofences() and removeGeofences().
        PendingIntent.getBroadcast(this, 0, intent, PendingIntent.FLAG_UPDATE_CURRENT)
    }
}

public class MainActivity extends AppCompatActivity {

    // ...

    private PendingIntent getGeofencePendingIntent() {
        // Reuse the PendingIntent if we already have it.
        if (geofencePendingIntent != null) {
            return geofencePendingIntent;
        }
        Intent intent = new Intent(this, GeofenceBroadcastReceiver.class);
        // We use FLAG_UPDATE_CURRENT so that we get the same pending intent back when
        // calling addGeofences() and removeGeofences().
        geofencePendingIntent = PendingIntent.getBroadcast(this, 0, intent, PendingIntent.
                FLAG_UPDATE_CURRENT);
        return geofencePendingIntent;
    }

Geofences hinzufügen

Verwenden Sie die Methode GeofencingClient.addGeofences(), um Geofences hinzuzufügen. Geben Sie das GeofencingRequest-Objekt und die PendingIntent an. Das folgende Snippet veranschaulicht die Verarbeitung der Ergebnisse:

KotlinJava

geofencingClient?.addGeofences(getGeofencingRequest(), geofencePendingIntent)?.run {
    addOnSuccessListener {
        // Geofences added
        // ...
    }
    addOnFailureListener {
        // Failed to add geofences
        // ...
    }
}

geofencingClient.addGeofences(getGeofencingRequest(), getGeofencePendingIntent())
        .addOnSuccessListener(this, new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                // Geofences added
                // ...
            }
        })
        .addOnFailureListener(this, new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Failed to add geofences
                // ...
            }
        });

Geofence-Übergänge verarbeiten

Wenn die Standortdienste erkennen, dass der Nutzer einen Geofence betreten oder verlassen hat, sendet das Intent in der PendingIntent die Sie in die Anfrage zum Hinzufügen von Geofences aufgenommen haben. Ein Übertragungsempfänger wie GeofenceBroadcastReceiver bemerkt, dass Intent aufgerufen wurde und können dann das Geofencing-Ereignis aus dem Intent abrufen, die Art der Geofence-Übergänge bestimmen, und ermitteln, welcher der definierten Geofences ausgelöst wurde. Der Empfänger der Übertragung kann eine App anweisen, Hintergrundarbeiten auszuführen oder, falls gewünscht, eine Benachrichtigung als Ausgabe senden.

Hinweis: Wenn unter Android 8.0 (API-Level 26) und höher eine App im Hintergrund ausgeführt wird, während ein Geofence überwacht wird, reagiert das Gerät alle paar Minuten auf Geofence-Ereignisse. Informationen dazu, wie Sie Ihre App an diese Antwortlimits anpassen, finden Sie unter Standortlimits im Hintergrund.

Das folgende Snippet zeigt, wie Sie eine BroadcastReceiver definieren, die eine Benachrichtigung sendet, wenn ein Geofence-Übergang auftritt. Wenn der Nutzer auf die Benachrichtigung klickt, wird die Hauptaktivität der App angezeigt:

KotlinJava

class GeofenceBroadcastReceiver : BroadcastReceiver() {
    // ...
    override fun onReceive(context: Context?, intent: Intent?) {
        val geofencingEvent = GeofencingEvent.fromIntent(intent)
        if (geofencingEvent.hasError()) {
            val errorMessage = GeofenceStatusCodes
                    .getStatusCodeString(geofencingEvent.errorCode)
            Log.e(TAG, errorMessage)
            return
        }

        // Get the transition type.
        val geofenceTransition = geofencingEvent.geofenceTransition

        // Test that the reported transition was of interest.
        if (geofenceTransition == Geofence.GEOFENCE_TRANSITION_ENTER ||
                geofenceTransition == Geofence.GEOFENCE_TRANSITION_EXIT) {

            // Get the geofences that were triggered. A single event can trigger
            // multiple geofences.
            val triggeringGeofences = geofencingEvent.triggeringGeofences

            // Get the transition details as a String.
            val geofenceTransitionDetails = getGeofenceTransitionDetails(
                    this,
                    geofenceTransition,
                    triggeringGeofences
            )

            // Send notification and log the transition details.
            sendNotification(geofenceTransitionDetails)
            Log.i(TAG, geofenceTransitionDetails)
        } else {
            // Log the error.
            Log.e(TAG, getString(R.string.geofence_transition_invalid_type,
                    geofenceTransition))
        }
    }
}

public class GeofenceBroadcastReceiver extends BroadcastReceiver {
    // ...
    protected void onReceive(Context context, Intent intent) {
        GeofencingEvent geofencingEvent = GeofencingEvent.fromIntent(intent);
        if (geofencingEvent.hasError()) {
            String errorMessage = GeofenceStatusCodes
                    .getStatusCodeString(geofencingEvent.getErrorCode());
            Log.e(TAG, errorMessage);
            return;
        }

        // Get the transition type.
        int geofenceTransition = geofencingEvent.getGeofenceTransition();

        // Test that the reported transition was of interest.
        if (geofenceTransition == Geofence.GEOFENCE_TRANSITION_ENTER ||
                geofenceTransition == Geofence.GEOFENCE_TRANSITION_EXIT) {

            // Get the geofences that were triggered. A single event can trigger
            // multiple geofences.
            List<Geofence> triggeringGeofences = geofencingEvent.getTriggeringGeofences();

            // Get the transition details as a String.
            String geofenceTransitionDetails = getGeofenceTransitionDetails(
                    this,
                    geofenceTransition,
                    triggeringGeofences
            );

            // Send notification and log the transition details.
            sendNotification(geofenceTransitionDetails);
            Log.i(TAG, geofenceTransitionDetails);
        } else {
            // Log the error.
            Log.e(TAG, getString(R.string.geofence_transition_invalid_type,
                    geofenceTransition));
        }
    }
}

Nachdem das Übergangsereignis über PendingIntent erkannt wurde, BroadcastReceiver erhält den Geofence-Übergangstyp und prüft, ob es eines der Ereignisse ist, die die App zum Auslösen verwendet Benachrichtigungen entweder GEOFENCE_TRANSITION_ENTER oder GEOFENCE_TRANSITION_EXIT in diesem Fall. Der Dienst sendet dann eine Benachrichtigung und protokolliert die Details zur Umstellung.

Geofence-Monitoring beenden

Durch das Beenden der Geofencing-Überwachung, wenn sie nicht mehr benötigt oder erwünscht ist, kann der Akku geschont werden. die Stromversorgung und CPU-Zyklen des Geräts. Sie können die Geofence-Überwachung in der Hauptaktivität beenden, mit der Geofences hinzugefügt und entfernt werden. Wenn Sie einen Geofence entfernen, wird die Überwachung sofort beendet. Die API bietet Methoden zur Entfernen von Geofences entweder durch Anfrage-IDs oder durch Entfernen von Geofences, die mit einer bestimmten PendingIntent

Das folgende Snippet entfernt Geofences durch PendingIntent und stoppt alle eine weitere Benachrichtigung, wenn das Gerät zuvor hinzugefügte Geofences erreicht oder verlässt:

KotlinJava

geofencingClient?.removeGeofences(geofencePendingIntent)?.run {
    addOnSuccessListener {
        // Geofences removed
        // ...
    }
    addOnFailureListener {
        // Failed to remove geofences
        // ...
    }
}

geofencingClient.removeGeofences(getGeofencePendingIntent())
        .addOnSuccessListener(this, new OnSuccessListener<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                // Geofences removed
                // ...
            }
        })
        .addOnFailureListener(this, new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Failed to remove geofences
                // ...
            }
        });

Sie können Geofencing mit anderen standortbasierten Funktionen kombinieren, z. B. mit regelmäßigen Standortaktualisierungen. Weitere Informationen finden Sie in den anderen Lektionen dieses Kurses.

Best Practices für Geofencing verwenden

In diesem Abschnitt finden Sie Empfehlungen für die Verwendung von Geofencing mit den Standort-APIs für Android.

Energieverbrauch reduzieren

Mit den folgenden Methoden können Sie den Energieverbrauch in Ihren Apps mit Geofencing optimieren:

• Legen Sie für die Benachrichtigungsreaktion einen höheren Wert fest. Dadurch wird der Energieverbrauch durch eine Erhöhung der Latenz von Geofence-Benachrichtigungen gesenkt. Wenn Sie beispielsweise für die Reaktionsfähigkeit -Minuten, sucht Ihre App nur alle fünf Minuten nach Eingangs- oder Ausgangsbenachrichtigungen. Niedrigere Werte bedeuten nicht unbedingt, dass Nutzer innerhalb dieses Zeitraums benachrichtigt werden. Wenn Sie beispielsweise einen Wert von 5 Sekunden festlegen, kann es etwas länger dauern, bis der Benachrichtigung).

• Verwenden Sie einen größeren Geofence-Radius für Orte, an denen Nutzer viel Zeit verbringen, z. B. zu Hause oder bei der Arbeit. Ein größerer Umkreis reduziert den Stromverbrauch zwar nicht direkt, Die Häufigkeit, mit der die App den Eingang oder das Verlassen prüft, wodurch die Gesamtleistung reduziert wird konsumiert wird.

Optimalen Radius für Ihren Geofence auswählen

Die besten Ergebnisse erzielen Sie, wenn der Mindestradius des Geofence zwischen 100 und 150 Metern liegt. Wenn WLAN verfügbar ist, liegt die Standortgenauigkeit in der Regel zwischen 20 und 50 Metern. Wenn die Standortermittlung in Innenräumen verfügbar ist, kann die Genauigkeit bis zu 5 Meter betragen. Außer in Innenräumen Standort innerhalb des Geofence verfügbar ist, nehmen wir an, dass die WLAN-Standortgenauigkeit 50 Meter.

Wenn die WLAN-Standortermittlung nicht verfügbar ist, z. B. beim Fahren in ländlicher Umgebung, verschlechtert sich. Der Genauigkeitsbereich kann zwischen mehreren Hundert Metern und mehrere Kilometer. In solchen Fällen sollten Sie Geofences mit einem größeren Radius erstellen.

Erläutern Sie Nutzern, warum Ihre App Geofencing verwendet

Da Ihre App bei der Verwendung von Geofencing im Hintergrund auf den Standort zugreift, sollten Sie überlegen, welche Vorteile sie für Nutzer bietet. Erläutern Sie klar, warum Ihre App benötigt diesen Zugriff, um das Verständnis der Nutzer zu verbessern und die Transparenz zu erhöhen.

Weitere Informationen zu Best Practices für den Zugriff auf Standortdaten, einschließlich Geofencing, finden Sie auf der Seite Best Practices für den Datenschutz.

Verwenden Sie den Übergangstyp für die Verweildauer, um Warnmeldungen-Spam zu reduzieren

Wenn Sie eine große Anzahl von Benachrichtigungen erhalten, wenn Sie kurz an einem Geofence vorbeifahren, können Sie die Anzahl der Benachrichtigungen am besten reduzieren, indem Sie den Übergangstyp GEOFENCE_TRANSITION_DWELL anstelle von GEOFENCE_TRANSITION_ENTER verwenden. So wird die Benachrichtigung nur gesendet, wenn sich der Nutzer für einen bestimmten Zeitraum innerhalb eines Geofences aufhält. Sie können die Dauer festlegen, indem Sie eine Loitering-Verzögerung.

Geofences nur bei Bedarf neu registrieren

Registrierte Geofences werden im com.google.process.location-Prozess gespeichert, der dem com.google.android.gms-Paket zugewiesen ist. Für die folgenden Ereignisse muss die App nichts tun, da das System Geofences nach diesen Ereignissen wiederherstellt:

• Die Google Play-Dienste wurden aktualisiert.
• Google Play-Dienste werden aufgrund von Ressourceneinschränkungen vom System beendet und neu gestartet.
• Der Standortprozess stürzt ab.

Die App muss Geofences neu registrieren, wenn sie nach den folgenden Ereignissen noch benötigt werden, da das System sie in den folgenden Fällen nicht wiederherstellen kann:

• Das Gerät wird neu gestartet. Die App sollte auf die Aktion „Boot complete“ des Geräts warten und dann die erforderlichen Geofences neu registrieren.
• Die App wird deinstalliert und neu installiert.
• Die App-Daten werden gelöscht.
• Die Daten der Google Play-Dienste werden gelöscht.
• Die App hat eine GEOFENCE_NOT_AVAILABLE Warnung erhalten. Das passiert in der Regel nachdem NLP, der Network Location Provider von Android, deaktiviert wurde.

Fehler beim Geofence-Einstiegsereignis beheben

Wenn keine Geofences ausgelöst werden, wenn das Gerät in einen Geofence eintritt (Die GEOFENCE_TRANSITION_ENTER-Benachrichtigung wird nicht ausgelöst). Vergewissern Sie sich zuerst, dass Ihre Geofences wie in diesem Leitfaden beschrieben ordnungsgemäß registriert.

Wenn Benachrichtigungen nicht wie erwartet funktionieren, kann das folgende Gründe haben:

• Innerhalb Ihres Geofences ist kein genauer Standort verfügbar oder Ihr Geofence ist zu klein. Auf den meisten Geräten verwendet der Geofence-Dienst nur den Netzwerkstandort für Geofence Auslöser. Der Dienst verwendet diesen Ansatz, da die Standortermittlung über das Netzwerk viel weniger Strom verbraucht, weniger Zeit für die Ermittlung einzelner Standorte benötigt wird und vor allem auch drinnen funktioniert.

• WLAN ist auf dem Gerät deaktiviert. Mit aktiviertem WLAN kann die Funktion Die Standortgenauigkeit. Wenn WLAN deaktiviert ist, erhält Ihre Anwendung möglicherweise keine Geofence-Benachrichtigungen. von verschiedenen Einstellungen wie dem Radius des Geofence, des Gerätemodells Android-Version Ab Android 4.3 (API-Ebene 18) haben wir den Modus „Nur WLAN-Scan“ hinzugefügt. Damit können Nutzer WLAN deaktivieren und trotzdem einen guten Netzwerkstandort erhalten. Es ist empfehlenswert, den Nutzer aufzufordern und ihm eine Tastenkombination zum Aktivieren des WLANs oder des WLAN-Scanmodus zur Verfügung zu stellen, wenn beide deaktiviert sind. verwenden SettingsClient, um sicherzustellen, dass die Systemeinstellungen des Geräts richtig konfiguriert sind. Standorterkennung.

  Hinweis: Wenn Ihre App auf Android 10 (API-Level 29) oder höher ausgerichtet ist, können Sie WifiManager.setEnabled() nur dann direkt aufrufen, wenn es sich um eine System-App oder einen Device Policy Controller (DPC) handelt. Verwenden Sie stattdessen eine Einstellungen.

• Innerhalb Ihres Geofences gibt es keine zuverlässige Netzwerkverbindung. Wenn keine zuverlässige Datenverbindung besteht, werden möglicherweise keine Benachrichtigungen generiert. Das liegt daran, dass der Geofencing-Dienst hängt vom Netzwerkstandortanbieter ab, der wiederum eine Datenverbindung erfordert.
• Benachrichtigungen können sich verzögern. Der Geofence-Dienst fragt nicht ständig nach Standort. Daher ist mit einer gewissen Verzögerung beim Empfang von Benachrichtigungen zu rechnen. Normalerweise liegt die Latenz unter 2 Minuten und sogar noch kürzer, wenn das Gerät in Bewegung ist. Wenn Hintergrund Standortbeschränkungen gelten, beträgt die Latenz im Durchschnitt etwa 2 bis 3 Minuten. Wenn sich das Gerät über einen längeren Zeitraum nicht bewegt hat, kann die Latenz zunehmen (bis zu 6 Minuten).

Weitere Informationen

Weitere Informationen zu Geofencing finden Sie in den folgenden Dokumenten:

Produktproben

Exemplarische App zum Erstellen und Überwachen von Geofences.