Il geofencing combina la consapevolezza della posizione attuale dell'utente con la consapevolezza della vicinanza dell'utente a località che potrebbero essere di suo interesse. Per contrassegnare un luogo di interesse, devi specificarne la latitudine e la longitudine. Per regolare la vicinanza della località, aggiungi un raggio. La latitudine, la longitudine e il raggio definiscono un recinto virtuale, creando un'area circolare o recinto intorno al luogo di interesse.
Puoi avere più recinti virtuali attivi, con un limite di 100 per app e per utente del dispositivo. Per ogni recinto virtuale, puoi chiedere ai Servizi di geolocalizzazione di inviarti eventi di ingresso e uscita oppure puoi specificare una durata di attesa (dwell) all'interno dell'area del recinto virtuale prima di attivare un evento. Puoi limitare la durata di qualsiasi recinto virtuale specificando una durata in millisecondi. Alla scadenza del recinto virtuale, i servizi di geolocalizzazione lo rimuoveranno automaticamente.
Questa lezione ti mostra come aggiungere e rimuovere recinti virtuali e poi ascoltare le transizioni del recinto virtuale utilizzando un BroadcastReceiver.
Configura per il monitoraggio del recinto virtuale
Il primo passaggio per richiedere il monitoraggio del recinto virtuale è richiedere le autorizzazioni necessarie. Per utilizzare il geofencing, la tua app deve richiedere quanto segue:
-
ACCESS_FINE_LOCATION -
ACCESS_BACKGROUND_LOCATIONse la tua app ha come target Android 10 (livello API 29) o versioni successive
Per scoprire di più, consulta la guida su come richiedere le autorizzazioni di accesso alla posizione.
Se vuoi utilizzare BroadcastReceiver per ascoltare le transizioni del recinto virtuale, aggiungi un elemento che specifichi il nome del servizio. Questo elemento deve essere
un elemento secondario dell'elemento
<application>:
<application android:allowBackup="true"> ... <receiver android:name=".GeofenceBroadcastReceiver"/> <application/>
Per accedere alle API di località, devi creare un'istanza del client Geofencing. Per scoprire come collegare il tuo client:
Kotlin
lateinit var geofencingClient: GeofencingClient
override fun onCreate(savedInstanceState: Bundle?) {
// ...
geofencingClient = LocationServices.getGeofencingClient(this)
}
Java
private GeofencingClient geofencingClient;
@Override
public void onCreate(Bundle savedInstanceState) {
// ...
geofencingClient = LocationServices.getGeofencingClient(this);
}
Crea e aggiungi recinti virtuali
L'app deve creare e aggiungere recinti virtuali utilizzando la classe del builder dell'API di posizione per
creare oggetti per recinto virtuale e la classe di convenienza per aggiungerli. Inoltre, per gestire gli intent inviati dai Servizi di geolocalizzazione quando si verificano transizioni con recinto virtuale, puoi definire un valore PendingIntent come mostrato in questa sezione.
Nota:sui dispositivi di un singolo utente, esiste un limite di 100 recinti virtuali per app. Per i dispositivi multiutente, il limite è di 100 recinti virtuali per app per utente di dispositivo.
Crea oggetti del recinto virtuale
Innanzitutto, utilizza
Geofence.Builder per creare un recinto virtuale, impostando il raggio, la durata e i tipi di transizione desiderati per il recinto virtuale. Ad esempio, per compilare un oggetto elenco:
Kotlin
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())
Java
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());
Questo esempio estrae i dati da un file di costanti. In pratica, le app potrebbero creare recinti virtuali in modo dinamico in base alla posizione dell'utente.
Specifica i recinti virtuali e i trigger iniziali
Lo snippet seguente utilizza la classe
GeofencingRequest e la relativa classe
GeofencingRequestBuilder nidificata per specificare i recinti virtuali da monitorare e per impostare la modalità di attivazione degli eventi del recinto virtuale:
Kotlin
private fun getGeofencingRequest(): GeofencingRequest {
return GeofencingRequest.Builder().apply {
setInitialTrigger(GeofencingRequest.INITIAL_TRIGGER_ENTER)
addGeofences(geofenceList)
}.build()
}
Java
private GeofencingRequest getGeofencingRequest() {
GeofencingRequest.Builder builder = new GeofencingRequest.Builder();
builder.setInitialTrigger(GeofencingRequest.INITIAL_TRIGGER_ENTER);
builder.addGeofences(geofenceList);
return builder.build();
}
Questo esempio mostra l'uso di due trigger per il recinto virtuale. La transizione
GEOFENCE_TRANSITION_ENTER
si attiva quando un dispositivo entra in un recinto virtuale, mentre la transizione
GEOFENCE_TRANSITION_EXIT
si attiva quando il dispositivo esce dal recinto virtuale. Se specifichi
INITIAL_TRIGGER_ENTER, ai servizi di geolocalizzazione viene comunicato che
GEOFENCE_TRANSITION_ENTER
deve essere attivato se il dispositivo si trova già all'interno del recinto virtuale.
In molti casi, potrebbe essere preferibile utilizzare
INITIAL_TRIGGER_DWELL, che attiva gli eventi solo quando l'utente si ferma per un periodo di tempo definito all'interno di un recinto virtuale.
Questo approccio consente di ridurre gli avvisi di spam causati da grandi quantità di notifiche quando un dispositivo entra ed esce per breve tempo da recinti virtuali. Un'altra strategia per ottenere i migliori risultati dai tuoi recinti geografici è impostare un raggio minimo di 100 metri. Ciò consente di tenere conto della precisione della geolocalizzazione
delle reti Wi-Fi tipiche e di ridurre il consumo energetico del dispositivo.
Definisci un broadcast receiver per le transizioni del recinto virtuale
Un elemento Intent inviato dai Servizi di geolocalizzazione può attivare varie azioni
nella tua app, ma non dovresti avviare un'attività o un frammento, perché i componenti
devono diventare visibili solo in risposta a un'azione utente. In molti casi, un BroadcastReceiver è un buon modo per gestire una transizione del recinto virtuale. Un BroadcastReceiver riceve aggiornamenti quando si verifica un evento, come una transizione all'interno o all'esterno di un recinto virtuale, e può avviare operazioni in background a lunga esecuzione.
Il seguente snippet mostra come definire un PendingIntent che avvia un BroadcastReceiver:
Kotlin
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)
}
}
Java
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;
}
Aggiungi recinti virtuali
Per aggiungere recinti virtuali, utilizza il metodo
.
Fornisci l'oggetto GeofencingClient.addGeofences()
GeofencingRequest e il PendingIntent.
Lo snippet seguente mostra l'elaborazione dei risultati:
Kotlin
geofencingClient?.addGeofences(getGeofencingRequest(), geofencePendingIntent)?.run {
addOnSuccessListener {
// Geofences added
// ...
}
addOnFailureListener {
// Failed to add geofences
// ...
}
}
Java
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
// ...
}
});
Gestire le transizioni del recinto virtuale
Quando i Servizi di geolocalizzazione rilevano che l'utente è entrato o uscito da un recinto virtuale, invia Intent contenuto nel PendingIntent
che hai incluso nella richiesta di aggiunta di recinti virtuali. Un broadcast receiver come GeofenceBroadcastReceiver nota che è stato richiamato Intent e può quindi ottenere l'evento di geofencing dall'intent, determinare il tipo di transizione o le transizioni del recinto virtuale e determinare quale dei recinti virtuali definiti è stato attivato. Il broadcast
receiver può indirizzare un'app in modo che possa iniziare a eseguire lavori in background o, se
lo desideri, inviare una notifica come output.
Nota: su Android 8.0 (livello API 26) e versioni successive, se un'app è in esecuzione in background durante il monitoraggio di un recinto virtuale, il dispositivo risponde agli eventi di geofencing ogni paio di minuti. Per informazioni su come adattare la tua app a questi limiti di risposta, vedi Limiti di posizione in background.
Lo snippet seguente mostra come definire un BroadcastReceiver che pubblichi una notifica quando si verifica una transizione del recinto virtuale. Quando l'utente
fa clic sulla notifica, viene visualizzata l'attività principale dell'app:
Kotlin
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))
}
}
}
Java
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));
}
}
}
Dopo aver rilevato l'evento di transizione tramite PendingIntent,
BroadcastReceiver ottiene il tipo di transizione del recinto virtuale e
verifica se si tratta di uno degli eventi utilizzati dall'app per attivare
le notifiche:
GEOFENCE_TRANSITION_ENTER
o GEOFENCE_TRANSITION_EXIT
in questo caso. Il servizio invia quindi una notifica e registra i dettagli della transizione.
Interrompi il monitoraggio del recinto virtuale
L'interruzione del monitoraggio del recinto virtuale quando non è più necessario o desiderato può aiutare a risparmiare batteria
e cicli della CPU sul dispositivo. Puoi interrompere il monitoraggio del recinto virtuale nell'attività principale utilizzata per aggiungere e rimuovere il recinto virtuale; se ne rimuovi uno, il recinto virtuale viene interrotto immediatamente. L'API fornisce metodi per
rimuovere i recinti virtuali tramite ID richiesta o rimuovendo i recinti virtuali associati a un determinato
PendingIntent.
Il seguente snippet rimuove i recinti virtuali di PendingIntent, interrompendo tutte
le ulteriori notifiche quando il dispositivo entra o esce da recinti virtuali aggiunti in precedenza:
Kotlin
geofencingClient?.removeGeofences(geofencePendingIntent)?.run {
addOnSuccessListener {
// Geofences removed
// ...
}
addOnFailureListener {
// Failed to remove geofences
// ...
}
}
Java
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
// ...
}
});
Puoi combinare il geofencing con altre funzionalità sensibili alla posizione, ad esempio gli aggiornamenti periodici della posizione. Per ulteriori informazioni, vedi le altre lezioni di questo corso.
Utilizza le best practice per il geofencing
Questa sezione fornisce suggerimenti per l'utilizzo del geofencing con le API di posizione per Android.
Riduci il consumo di corrente
Puoi usare le seguenti tecniche per ottimizzare il consumo energetico nelle app che usano il geofencing:
Imposta il valore di reattività delle notifiche su un valore più alto. In questo modo si migliora il consumo aumentando la latenza degli avvisi per recinto virtuale. Ad esempio, se imposti un valore di reattività di cinque minuti, la tua app verifica la presenza di un avviso di ingresso o uscita solo una volta ogni cinque minuti. L'impostazione di valori più bassi non significa necessariamente che gli utenti ricevano una notifica entro questo periodo di tempo (ad esempio, se imposti un valore di 5 secondi, la ricezione dell'avviso potrebbe richiedere un po' più di tempo).
Utilizza un raggio del recinto virtuale più ampio per i luoghi in cui un utente trascorre una quantità di tempo significativa, ad esempio casa o lavoro. Anche se un raggio più ampio non riduce direttamente il consumo energetico, riduce la frequenza con cui l'app controlla l'ingresso o l'uscita, riducendo di fatto il consumo energetico complessivo.
Scegli il raggio ottimale per il tuo recinto virtuale
Per ottenere risultati ottimali, il raggio minimo del recinto virtuale deve essere impostato tra 100 e 150 metri. Quando è disponibile il Wi-Fi, la precisione della posizione è compresa tra 20 e 50 metri. Quando è disponibile la posizione in ambienti interni, il campo di precisione può essere di massimo 5 metri. Se non sai che la posizione al chiuso è disponibile all'interno del recinto virtuale, supponiamo che la precisione della geolocalizzazione del Wi-Fi sia di circa 50 metri.
Quando la posizione della rete Wi-Fi non è disponibile (ad esempio, quando guidi in zone rurali), la precisione della posizione si riduce. Il raggio di precisione può variare da diverse centinaia di metri a diversi chilometri. In casi come questo, devi creare recinti virtuali utilizzando un raggio più ampio.
Spiegare agli utenti perché la tua app utilizza il geofencing
Poiché la tua app accede alla posizione in background quando utilizzi il geofencing, valuta i vantaggi dell'app per gli utenti. Spiega chiaramente perché la tua app ha bisogno di questo accesso per migliorare la comprensione e la trasparenza degli utenti.
Per ulteriori informazioni sulle best practice relative all'accesso alla posizione, incluso il geofencing, consulta la pagina sulle best practice per la privacy.
Utilizzare il tipo di transizione di attesa per ridurre lo spam di avvisi
Se ricevi un numero elevato di avvisi mentre guidi per brevi intervalli lungo un recinto virtuale, il modo migliore per ridurli è utilizzare un tipo di transizione
GEOFENCE_TRANSITION_DWELL anziché
GEOFENCE_TRANSITION_ENTER. In questo modo, l'avviso relativo alle abitazioni viene inviato solo quando l'utente si ferma all'interno di un recinto virtuale per un determinato periodo di tempo. Puoi scegliere la durata impostando un
ritardo di ascolto.
Registra di nuovo i recinti geografici solo quando necessario
I recinti virtuali registrati vengono conservati nel processo com.google.process.location di proprietà del
pacchetto com.google.android.gms.
L'app non deve fare nulla per gestire i seguenti eventi perché il sistema
ripristina i recinti virtuali dopo questi eventi:
- È stato eseguito l'upgrade di Google Play Services.
- Google Play Services viene interrotto e riavviato dal sistema a causa della limitazione delle risorse.
- La procedura di localizzazione ha un arresto anomalo.
L'app deve registrare nuovamente i recinti geografici se sono ancora necessari dopo gli eventi indicati di seguito, poiché il sistema non può recuperare tali recinti virtuali nei seguenti casi:
- Il dispositivo è stato riavviato. L'app dovrebbe ascoltare l'azione completata di avvio del dispositivo e poi registrare nuovamente i recinti virtuali richiesti.
- L'app viene disinstallata e reinstallata.
- I dati dell'app sono stati cancellati.
- I dati di Google Play Services sono stati cancellati.
- L'app ha ricevuto un avviso
GEOFENCE_NOT_AVAILABLE. In genere questo accade dopo la disattivazione della funzione NLP (Network Location Provider, provider di posizione di rete di Android).
Risolvere i problemi relativi all'evento di ingresso del recinto virtuale
Se i recinti virtuali non vengono attivati quando il dispositivo entra in un recinto virtuale (l'avviso
GEOFENCE_TRANSITION_ENTER non viene attivato), assicurati innanzitutto che questi siano registrati correttamente come descritto in questa guida.
Ecco alcuni possibili motivi per cui gli avvisi non funzionano come previsto:
- La posizione esatta non è disponibile all'interno del tuo recinto virtuale o quest'ultimo è troppo piccolo. Sulla maggior parte dei dispositivi, il servizio di recinto virtuale utilizza solo la posizione della rete per l'attivazione del recinto virtuale. Il servizio utilizza questo approccio perché la posizione della rete consuma molta meno energia, richiede meno tempo per ottenere posizioni discrete e, soprattutto, è disponibile al chiuso.
Il Wi-Fi sia disattivato sul dispositivo. L'attivazione del Wi-Fi può migliorare notevolmente la precisione della geolocalizzazione, quindi se il Wi-Fi è disattivato, l'applicazione potrebbe non ricevere mai avvisi di recinto virtuale, a seconda di diverse impostazioni, tra cui il raggio del recinto virtuale, il modello del dispositivo o la versione di Android. A partire da Android 4.3 (livello API 18), abbiamo aggiunto la funzionalità "modalità Solo ricerca Wi-Fi", che consente agli utenti di disattivare il Wi-Fi ma continuare a ottenere una buona posizione della rete. È buona prassi richiedere all'utente di fornire una scorciatoia per attivare la modalità di solo ricerca di reti Wi-Fi o Wi-Fi se entrambe sono disattivate. Utilizza SettingsClient per assicurarti che le impostazioni di sistema del dispositivo siano configurate correttamente per un rilevamento della posizione ottimale.
Nota : se la tua app ha come target Android 10 (livello API 29) o versioni successive, non puoi chiamare direttamente
WifiManager.setEnabled(), a meno che la tua app non sia un'app di sistema o un controller dei criteri dei dispositivi (DPC). Utilizza invece un riquadro delle impostazioni.- Non è disponibile una connettività di rete affidabile all'interno del recinto virtuale. In assenza di una connessione dati affidabile, gli avvisi potrebbero non essere generati. Questo perché il servizio di recinto virtuale dipende dal fornitore di servizi di localizzazione della rete, che a sua volta richiede una connessione dati.
- Gli avvisi possono arrivare in ritardo. Il servizio di recinto virtuale non esegue continuamente query per la posizione, quindi è prevista una certa latenza quando ricevi gli avvisi. Di solito la latenza è inferiore a 2 minuti, anche meno quando il dispositivo è in movimento. Se i limiti di posizione in background sono attivi, la latenza è in media di circa 2-3 minuti. Se il dispositivo è rimasto fermo per un periodo di tempo significativo, la latenza potrebbe aumentare (fino a 6 minuti).
Risorse aggiuntive
Per scoprire di più sul geofencing, consulta il seguente materiale:
Campioni
App di esempio per creare e monitorare recinti geografici.