Segnalazione della posizione per Android SDK per Azure Mobile EngagementLocation Reporting for Azure Mobile Engagement Android SDK

Questo argomento descrive come segnalare la posizione per l'applicazione Android.This topic describes how to do location reporting for your Android application.

PrerequisitiPrerequisites

Prima di iniziare questa esercitazione, è necessario completare l'esercitazione introduttiva .Before starting this tutorial, you must first complete the Getting Started tutorial.

Importante

L'API di Android SDK deve essere almeno di livello 10 o superiore (Android 2.3.3 o versioni successive).Your minimum Android SDK API level must be 10 or higher (Android 2.3.3 or higher).

Segnalazione della posizioneLocation reporting

Per fare in modo che le posizioni vengano segnalate, è necessario aggiungere alcune righe di configurazione tra i tag <application> e </application>.If you want locations to be reported, you need to add a few lines of configuration (between the <application> and </application> tags).

Segnalazione differita della posizioneLazy area location reporting

La segnalazione differita della posizione consente di segnalare il paese, l'area geografica e la località associati ai dispositivi.Lazy area location reporting enables reporting the country, region, and locality associated with devices. Questo tipo di segnalazione della posizione usa solo le posizioni di rete, sulla base dell'ID di cella o della connessione Wi-Fi.This type of location reporting only uses network locations (based on Cell ID or WIFI). L'area del dispositivo viene segnalata al massimo una volta per sessione.The device area is reported at most once per session. Il GPS non viene mai usato, per cui l'impatto di questo tipo di segnalazione della posizione sulla batteria è ridotto.The GPS is never used, and thus this type of location report has low impact on the battery.

Le aree segnalate vengono usate per calcolare statistiche geografiche relative a utenti, sessioni, eventi ed errori.Reported areas are used to compute geographic statistics about users, sessions, events, and errors. Possono essere usate anche come criteri nelle campagne Reach.They can also be used as criterion in Reach campaigns.

Si abilita la segnalazione differita della posizione usando la configurazione descritta in precedenza in questa procedura:You enable lazy area location reporting by using the configuration previously mentioned in this procedure:

EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
engagementConfiguration.setLazyAreaLocationReport(true);
EngagementAgent.getInstance(this).init(engagementConfiguration);

È inoltre necessario specificare un'autorizzazione di posizione.You also need to specify a location permission. Questo codice usa l'autorizzazione COARSE :This code uses COARSE permission:

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

Se l'app lo richiede, è possibile usare invece di ACCESS_FINE_LOCATION .If your app requires it, you can use ACCESS_FINE_LOCATION instead.

Segnalazione della posizione in tempo realeReal-time location reporting

La segnalazione della posizione in tempo reale consente di segnalare la latitudine e la longitudine associate ai dispositivi.Real-time location reporting enables reporting the latitude and longitude associated with devices. Questo tipo di segnalazione della posizione usa solo le posizioni di rete, sulla base dell'ID di cella o della connessione Wi-Fi.By default, this type of location reporting only uses network locations, based on Cell ID or WIFI. La segnalazione è attiva solo quando l'applicazione viene eseguita in primo piano, ad esempio durante una sessione.The reporting is only active when the application runs in foreground (for example, during a session).

Le posizioni in tempo reale NON sono usate per calcolare dati statistici.Real-time locations are NOT used to compute statistics. Il loro unico scopo è consentire l'uso del criterio di definizione del recinto virtuale in tempo reale <Reach-Audience-geofencing> nelle campagne Reach.Their only purpose is to allow the use of real-time geo-fencing <Reach-Audience-geofencing> criterion in Reach campaigns.

Per abilitare la segnalazione della posizione in tempo reale, aggiungere una riga di codice dove si è impostata la stringa di connessione di Engagement nell'attività dell'utilità di avvio.To enable real-time location reporting, add a line of code to where you set the Engagement connection string in the launcher activity. Il risultato è simile al seguente:The result looks like the following:

EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
engagementConfiguration.setRealtimeLocationReport(true);
EngagementAgent.getInstance(this).init(engagementConfiguration);

    You also need to specify a location permission. This code uses ``COARSE`` permission:

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

    If your app requires it, you can use ``ACCESS_FINE_LOCATION`` instead.

Segnalazione basata su GPSGPS based reporting

Per impostazione predefinita, la segnalazione della posizione in tempo reale usa solo posizioni di rete.By default, real-time location reporting only uses network-based locations. Per abilitare l'uso di posizioni basate su GPS, che sono molto più precise, usare l'oggetto di configurazione:To enable the use of GPS-based locations, which are far more precise, use the configuration object:

EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
engagementConfiguration.setRealtimeLocationReport(true);
engagementConfiguration.setFineRealtimeLocationReport(true);
EngagementAgent.getInstance(this).init(engagementConfiguration);

È necessario aggiungere anche le autorizzazioni seguenti, se mancanti:You also need to add the following permission if missing:

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

Segnalazione in backgroundBackground reporting

Per impostazione predefinita, la segnalazione della posizione in tempo reale è attiva solo quando l'applicazione viene eseguita in primo piano, ad esempio durante una sessione.By default, real-time location reporting is only active when the application runs in foreground (for example, during a session). Per abilitare la segnalazione anche in background, usare questo oggetto di configurazione:To enable the reporting also in background, use this configuration object:

EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
engagementConfiguration.setRealtimeLocationReport(true);
engagementConfiguration.setBackgroundRealtimeLocationReport(true);
EngagementAgent.getInstance(this).init(engagementConfiguration);

Nota

Quando l'applicazione viene eseguita in background, vengono segnalate solo le posizioni basate sulla rete, anche se è abilitato il GPS.When the application runs in background, only network-based locations are reported, even if you enabled the GPS.

Se l'utente riavvia il dispositivo, viene interrotta la segnalazione della posizione in background.If the user reboots their device, the background location report is stopped. Per fare in modo che venga riavviata automaticamente al riavvio, aggiungere questo codice.To make it automatically restart at boot time, add this code.

<receiver android:name="com.microsoft.azure.engagement.EngagementLocationBootReceiver"
       android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
    </intent-filter>
</receiver>

È necessario aggiungere anche le autorizzazioni seguenti, se mancanti:You also need to add the following permission if missing:

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

Autorizzazioni Android MAndroid M permissions

A partire da Android M, alcune autorizzazioni vengono gestite in fase di esecuzione e richiedono l'approvazione dell'utente.Starting with Android M, some permissions are managed at runtime and need user approval.

Se la destinazione è il livello 23 dell'API Android, le autorizzazioni di runtime verranno disattivate per impostazione predefinita per le installazioni di nuove app.If you target Android API level 23, the runtime permissions are turned off by default for new app installations. In caso contrario vengono attivate per impostazione predefinita.Otherwise they are turned on by default.

È possibile abilitare o disabilitare le autorizzazioni dal menu delle impostazioni del dispositivo.You can enable/disable those permissions from the device settings menu. La disattivazione delle autorizzazioni dal menu di sistema elimina i processi in background dell'applicazione. Si tratta di un comportamento del sistema e non influisce sulla possibilità di ricevere push in background.Turning off permissions from the system menu kills the background processes of the application, which is a system behavior, and has no impact on ability to receive push in background.

Nel contesto della segnalazione della posizione in Mobile Engagement, le autorizzazioni che richiedono l'approvazione in fase di esecuzione sono:In the context of Mobile Engagement location reporting, the permissions that require approval at runtime are:

  • ACCESS_COARSE_LOCATION
  • ACCESS_FINE_LOCATION

Richiedere le autorizzazioni all'utente con una finestra di dialogo di sistema standard.Request permissions from the user using a standard system dialog. Se l'utente approva, specificare EngagementAgent per applicare la modifica in tempo reale.If the user approves, tell EngagementAgent to take that change into account in real-time. In caso contrario la modifica verrà elaborata al successivo avvio dell'applicazione da parte dell'utente.Otherwise the change is processed the next time the user launches the application.

Ecco un esempio di codice da utilizzare in un'attività dell'applicazione per richiedere autorizzazioni e inoltrare il risultato, se positivo, a EngagementAgent:Here is a code sample to use in an activity of your application to request permissions and forward the result if positive to EngagementAgent:

@Override
public void onCreate(Bundle savedInstanceState)
{
  /* Other code... */

  /* Request permissions */
  requestPermissions();
}

@TargetApi(Build.VERSION_CODES.M)
private void requestPermissions()
{
  /* Avoid crashing if not on Android M */
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M)
  {
    /*
     * Request location permission, but this doesn't explain why it is needed to the user.
     * The standard Android documentation explains with more details how to display a rationale activity to explain the user why the permission is needed in your application.
     * Putting COARSE vs FINE has no impact here, they are part of the same group for runtime permission management.
     */
    if (checkSelfPermission(android.Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED)
      requestPermissions(new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION }, 0);

  }
}

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults)
{
  /* Only a positive location permission update requires engagement agent refresh, hence the request code matching from above function */
  if (requestCode == 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED)
    getEngagementAgent().refreshPermissions();
}