Directrices para usar Visits tracking

  • Artículo

Nota:

MapControl y servicios de mapas requieren una clave de autenticación de mapas denominada MapServiceToken. Para obtener más información sobre cómo obtener y establecer una clave de autenticación de mapas, consulta Solicitar una clave de autenticación de mapas.

La característica Visitas simplifica el proceso de seguimiento de ubicación para que sea más eficaz para los propósitos prácticos de muchas aplicaciones. Una visita se define como un área geográfica significativa que el usuario entra y sale. Las visitas son similares a las geovallas en que permiten que la aplicación se notifique solo cuando el usuario entra o sale de determinadas áreas de interés, lo que elimina la necesidad de realizar un seguimiento continuo de la ubicación, lo que puede ser una purga en la duración de la batería. Sin embargo, a diferencia de las geovallas, las áreas de visita se identifican dinámicamente en el nivel de plataforma y no es necesario definir explícitamente mediante aplicaciones individuales. Además, la selección de la que se realizará un seguimiento de Visitas de una aplicación se controla mediante una única configuración de granularidad, en lugar de suscribirse a lugares individuales.

Configuración preliminar

Antes de continuar, asegúrese de que la aplicación sea capaz de acceder a la ubicación del dispositivo. Tendrá que declarar la Location funcionalidad en el manifiesto y llamar al método Geolocator.RequestAccessAsync para asegurarse de que los usuarios conceden permisos de ubicación de la aplicación. Consulte Obtención de la ubicación del usuario para obtener más información sobre cómo hacerlo.

Recuerde agregar el Geolocation espacio de nombres a la clase . Esto será necesario para que todos los fragmentos de código de esta guía funcionen.

using Windows.Devices.Geolocation;

Consulte la última visita

La manera más sencilla de usar la característica de seguimiento de visitas es recuperar el último cambio de estado conocido relacionado con Visit. Un cambio de estado es un evento registrado por la plataforma en el que el usuario entra o sale de una ubicación significativa, hay un movimiento significativo desde el último informe o se pierde la ubicación del usuario (consulte la enumeración VisitStateChange ). Los cambios de estado se representan mediante instancias de Geovisit . Para recuperar la instancia de Geovisit para el último cambio de estado registrado, simplemente use el método designado en la clase GeovisitMonitor .

Nota:

Comprobar la última visita registrada no garantiza que el sistema esté realizando el seguimiento de las visitas. Para realizar un seguimiento de las visitas a medida que se producen, debe supervisarlas en primer plano o registrarse para el seguimiento en segundo plano (consulte las secciones siguientes).

private async void GetLatestStateChange() {
    // retrieve the Geovisit instance
    Geovisit latestVisit = await GeovisitMonitor.GetLastReportAsync();

    // Using the properties of "latestVisit", parse out the time that the state 
    // change was recorded, the device's location when the change was recorded,
    // and the type of state change.
}

Análisis de una instancia de Geovisit (opcional)

El método siguiente convierte toda la información almacenada en una instancia de Geovisit en una cadena fácil de leer. Se puede usar en cualquiera de los escenarios de esta guía para ayudar a proporcionar comentarios sobre las visitas que se notifican.

private string ParseGeovisit(Geovisit visit){
    string visitString = null;

    // Use a DateTimeFormatter object to process the timestamp. The following
    // format configuration will give an intuitive representation of the date/time
    Windows.Globalization.DateTimeFormatting.DateTimeFormatter formatterLongTime;
    
    formatterLongTime = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter(
        "{hour.integer}:{minute.integer(2)}:{second.integer(2)}", new[] { "en-US" }, "US", 
        Windows.Globalization.CalendarIdentifiers.Gregorian, 
        Windows.Globalization.ClockIdentifiers.TwentyFourHour);
    
    // use this formatter to convert the timestamp to a string, and add to "visitString"
    visitString = formatterLongTime.Format(visit.Timestamp);

    // Next, add on the state change type value
    visitString += " " + visit.StateChange.ToString();

    // Next, add the position information (if any is provided; this will be null if 
    // the reported event was "TrackingLost")
    if (visit.Position != null) {
        visitString += " (" +
        visit.Position.Coordinate.Point.Position.Latitude.ToString() + "," +
        visit.Position.Coordinate.Point.Position.Longitude.ToString() + 
        ")";
    }

    return visitString;
}

Supervisar visitas en primer plano

La clase GeovisitMonitor usada en la sección anterior también controla el escenario de escuchar los cambios de estado durante un período de tiempo. Para ello, cree una instancia de esta clase, registre un método de controlador para su evento y llame al Start método .

// this GeovisitMonitor instance will belong to the class scope
GeovisitMonitor monitor;

public void RegisterForVisits() {

    // Create and initialize a new monitor instance.
    monitor = new GeovisitMonitor();
    
    // Attach a handler to receive state change notifications.
    monitor.VisitStateChanged += OnVisitStateChanged;
    
    // Calling the start method will start Visits tracking for a specified scope:
    // For higher granularity such as venue/building level changes, choose Venue.
    // For lower granularity in the range of zipcode level changes, choose City.
    monitor.Start(VisitMonitoringScope.Venue);
}

En este ejemplo, el OnVisitStateChanged método controlará los informes de Visita entrantes. La instancia de Geovisit correspondiente se pasa a través del parámetro de evento.

private void OnVisitStateChanged(GeoVisitWatcher sender, GeoVisitStateChangedEventArgs args) {
    Geovisit visit = args.Visit;
    
    // Using the properties of "visit", parse out the time that the state 
    // change was recorded, the device's location when the change was recorded,
    // and the type of state change.
}

Cuando la aplicación haya terminado de supervisar los cambios de estado relacionados con Visit, debe detener el monitor y anular el registro de los controladores de eventos. Esto también debe hacerse siempre que la aplicación se suspenda o cierra.

public void UnregisterFromVisits() {
    
    // Stop the monitor to stop tracking Visits. Otherwise, tracking will
    // continue until the monitor instance is destroyed.
    monitor.Stop();
    
    // Remove the handler to stop receiving state change events.
    monitor.VisitStateChanged -= OnVisitStateChanged;
}

Supervisar visitas en segundo plano

También puedes implementar la supervisión de Visitas en una tarea en segundo plano para que la actividad relacionada con la visita se pueda controlar en el dispositivo incluso cuando la aplicación no esté abierta. Este es el método recomendado, ya que es más versátil y eficiente para la energía.

Esta guía usará el modelo en Crear y registrar una tarea en segundo plano fuera de proceso, en la que los archivos de aplicación principales residen en un proyecto y el archivo de tareas en segundo plano reside en un proyecto independiente en la misma solución. Si no está familiarizado con la implementación de tareas en segundo plano, se recomienda seguir esa guía principalmente, realizando las sustituciones necesarias a continuación para crear una tarea en segundo plano de control de visitas.

Nota:

En los fragmentos de código siguientes, algunas funcionalidades importantes, como el control de errores y el almacenamiento local, no están presentes por motivos de simplicidad. Para obtener una implementación sólida del control de visitas en segundo plano, consulte la aplicación de ejemplo.

En primer lugar, asegúrese de que la aplicación ha declarado permisos de tareas en segundo plano. En el Application/Extensions elemento del archivo Package.appxmanifest , agregue la siguiente extensión (agregue un Extensions elemento si aún no existe uno).

<Extension Category="windows.backgroundTasks" EntryPoint="Tasks.VisitBackgroundTask">
    <BackgroundTasks>
        <Task Type="location" />
    </BackgroundTasks>
</Extension>

A continuación, en la definición de la clase de tarea en segundo plano, pegue el código siguiente. El Run método de esta tarea en segundo plano simplemente pasará los detalles del desencadenador (que contienen la información de visitas) a un método independiente.

using Windows.ApplicationModel.Background;

namespace Tasks {
    
    public sealed class VisitBackgroundTask : IBackgroundTask {
        
        public void Run(IBackgroundTaskInstance taskInstance) {
            
            // get a deferral
            BackgroundTaskDeferral deferral = taskInstance.GetDeferral();
            
            // this task's trigger will be a Geovisit trigger
            GeovisitTriggerDetails triggerDetails = taskInstance.TriggerDetails as GeovisitTriggerDetails;

            // Handle Visit reports
            GetVisitReports(triggerDetails);         

            finally {
                deferral.Complete();
            }
        }        
    }
}

Defina el GetVisitReports método en algún lugar de esta misma clase.

private void GetVisitReports(GeovisitTriggerDetails triggerDetails) {

    // Read reports from the triggerDetails. This populates the "reports" variable 
    // with all of the Geovisit instances that have been logged since the previous
    // report reading.
    IReadOnlyList<Geovisit> reports = triggerDetails.ReadReports();

    foreach (Geovisit report in reports) {
        // Using the properties of "visit", parse out the time that the state 
        // change was recorded, the device's location when the change was recorded,
        // and the type of state change.
    }

    // Note: depending on the intent of the app, you many wish to store the
    // reports in the app's local storage so they can be retrieved the next time 
    // the app is opened in the foreground.
}

A continuación, en el proyecto principal de la aplicación, deberá realizar el registro de esta tarea en segundo plano. Cree un método de registro al que pueda llamar alguna acción de usuario o se llame cada vez que se active la clase.

// a reference to this registration should be declared at the class level
private IBackgroundTaskRegistration visitTask = null;

// The app must call this method at some point to allow future use of 
// the background task. 
private async void RegisterBackgroundTask(object sender, RoutedEventArgs e) {
    
    string taskName = "MyVisitTask";
    string taskEntryPoint = "Tasks.VisitBackgroundTask";

    // First check whether the task in question is already registered
    foreach (var task in BackgroundTaskRegistration.AllTasks) {
        if (task.Value.Name == taskName) {
            // if a task is found with the name of this app's background task, then
            // return and do not attempt to register this task
            return;
        }
    }
    
    // Attempt to register the background task.
    try {
        // Get permission for a background task from the user. If the user has 
        // already responded once, this does nothing and the user must manually 
        // update their preference via Settings.
        BackgroundAccessStatus backgroundAccessStatus = await BackgroundExecutionManager.RequestAccessAsync();

        switch (backgroundAccessStatus) {
            case BackgroundAccessStatus.AlwaysAllowed:
            case BackgroundAccessStatus.AllowedSubjectToSystemPolicy:
                // BackgroundTask is allowed
                break;

            default:
                // notify user that background tasks are disabled for this app
                //...
                break;
        }

        // Create a new background task builder
        BackgroundTaskBuilder visitTaskBuilder = new BackgroundTaskBuilder();

        visitTaskBuilder.Name = exampleTaskName;
        visitTaskBuilder.TaskEntryPoint = taskEntryPoint;

        // Create a new Visit trigger
        var trigger = new GeovisitTrigger();

        // Set the desired monitoring scope.
        // For higher granularity such as venue/building level changes, choose Venue.
        // For lower granularity in the range of zipcode level changes, choose City. 
        trigger.MonitoringScope = VisitMonitoringScope.Venue; 

        // Associate the trigger with the background task builder
        visitTaskBuilder.SetTrigger(trigger);

        // Register the background task
        visitTask = visitTaskBuilder.Register();      
    }
    catch (Exception ex) {
        // notify user that the task failed to register, using ex.ToString()
    }
}

Esto establece que una clase de tarea en segundo plano llamada VisitBackgroundTask en el espacio de nombres Tasks hará algo con el tipo de location desencadenador.

La aplicación ahora debe ser capaz de registrar la tarea en segundo plano de control de visitas y esta tarea debe activarse cada vez que el dispositivo registra un cambio de estado relacionado con la visita. Tendrá que rellenar la lógica en la clase de tarea en segundo plano para determinar qué hacer con esta información de cambio de estado.