Richtlinien für die Verwendung von Visits Tracking

  • Artikel

Hinweis

MapControl und Kartendienste erfordern einen Karten-Authentifizierungsschlüssel namens MapServiceToken. Weitere Informationen zum Abrufen und Festlegen eines Kartenauthentifizierungsschlüssels finden Sie unter Anfordern eines Kartenauthentifizierungsschlüssels.

Das Feature Visits optimiert den Prozess der Standortnachverfolgung, um es für die praktischen Zwecke vieler Apps effizienter zu machen. Ein Besuch ist als ein wichtiger geografischer Bereich definiert, den der Benutzer ein- und verlässt. Besuche ähneln geofences insofern, als die App nur benachrichtigt werden kann, wenn der Benutzer bestimmte Bereiche von Interesse betritt oder verlässt, sodass keine kontinuierliche Standortnachverfolgung erforderlich ist, was zu einer Belastung der Akkulaufzeit führen kann. Im Gegensatz zu Geofences werden Besuchsbereiche jedoch dynamisch auf Plattformebene identifiziert und müssen nicht explizit von einzelnen Apps definiert werden. Außerdem wird die Auswahl, deren Besuche eine App nachverfolgt, durch eine einzelne Granularitätseinstellung und nicht durch das Abonnieren einzelner Orte verarbeitet.

Vorläufige Einrichtung

Bevor Sie fortfahren, stellen Sie sicher, dass Ihre App auf den Standort des Geräts zugreifen kann. Sie müssen die Location Funktion im Manifest deklarieren und die Geolocator.RequestAccessAsync-Methode aufrufen, um sicherzustellen, dass Benutzer der App-Standortberechtigungen erteilen. Weitere Informationen dazu finden Sie unter Abrufen des Speicherorts des Benutzers .

Denken Sie daran, den Geolocation Namespace Ihrer Klasse hinzuzufügen. Dies ist erforderlich, damit alle Codeausschnitte in diesem Leitfaden funktionieren.

using Windows.Devices.Geolocation;

Überprüfen Sie den neuesten Besuch

Die einfachste Möglichkeit, das Feature zur Nachverfolgung von Besuchen zu verwenden, besteht darin, die letzte bekannte Statusänderung im Zusammenhang mit dem Besuch abzurufen. Eine Zustandsänderung ist ein plattformprotokolliertes Ereignis, bei dem entweder der Benutzer einen wichtigen Speicherort ein-/ausgibt, es seit dem letzten Bericht zu einer erheblichen Bewegung kommt oder der Standort des Benutzers verloren geht (siehe VisitStateChange-Enume ). Zustandsänderungen werden durch Geovisit-Instanzen dargestellt. Um die Geovisit-instance für die letzte aufgezeichnete Zustandsänderung abzurufen, verwenden Sie einfach die angegebene Methode in der GeovisitMonitor-Klasse.

Hinweis

Die Überprüfung des letzten protokollierten Besuchs garantiert nicht, dass Besuche derzeit vom System nachverfolgt werden. Um Besuche nachzuverfolgen, müssen Sie sie entweder im Vordergrund überwachen oder sich für die Hintergrundnachverfolgung registrieren (siehe Abschnitte unten).

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.
}

Analysieren eines Geovisit-instance (optional)

Die folgende Methode konvertiert alle in einem Geovisit-instance gespeicherten Informationen in eine leicht lesbare Zeichenfolge. Es kann in jedem der Szenarien in diesem Leitfaden verwendet werden, um Feedback für die gemeldeten Besuche zu geben.

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;
}

Überwachen von Besuchen im Vordergrund

Die im vorherigen Abschnitt verwendete GeovisitMonitor-Klasse behandelt auch das Szenario der Überwachung auf Zustandsänderungen über einen bestimmten Zeitraum. Dazu können Sie diese Klasse instanziieren, eine Handlermethode für ihr Ereignis registrieren und die Start -Methode aufrufen.

// 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);
}

In diesem Beispiel verarbeitet die OnVisitStateChanged Methode eingehende Visit-Berichte. Die entsprechende Geovisit-instance wird über den Ereignisparameter übergeben.

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.
}

Wenn die App die Überwachung auf Besuchsbezogene Statusänderungen abgeschlossen hat, sollte sie den Monitor beenden und die Registrierung der Ereignishandler aufheben. Dies sollte auch immer dann erfolgen, wenn die App angehalten oder geschlossen wird.

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;
}

Überwachen von Besuchen im Hintergrund

Sie können die Besuchsüberwachung auch in einer Hintergrundaufgabe implementieren, sodass besuchsbezogene Aktivitäten auf dem Gerät verarbeitet werden können, auch wenn Ihre App nicht geöffnet ist. Dies ist die empfohlene Methode, da sie vielseitiger und energieeffizienter ist.

In diesem Leitfaden wird das Modell unter Erstellen und Registrieren einer Hintergrundaufgabe außerhalb des Prozesses verwendet, bei der die Standard Anwendungsdateien in einem Projekt und die Hintergrundaufgabendatei in einem separaten Projekt in derselben Projektmappe gespeichert wird. Wenn Sie noch nicht mit der Implementierung von Hintergrundaufgaben arbeiten, empfiehlt es sich, diese Anleitung in erster Linie zu befolgen, um die unten erforderlichen Ersetzungen vorzunehmen, um eine Hintergrundaufgabe für die Besuchsbehandlung zu erstellen.

Hinweis

In den folgenden Codeausschnitten fehlen der Einfachheit halber wichtige Funktionen wie Fehlerbehandlung und lokaler Speicher. Eine robuste Implementierung der Hintergrundbehandlung für Besuche finden Sie in der Beispiel-App.

Stellen Sie zunächst sicher, dass Ihre App Berechtigungen für Hintergrundaufgaben deklariert hat. Fügen Sie im Application/Extensions Element Der Datei Package.appxmanifest die folgende Erweiterung hinzu (fügen Sie ein Extensions Element hinzu, falls noch kein Element vorhanden ist).

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

Fügen Sie als Nächstes in der Definition der Hintergrundaufgabenklasse den folgenden Code ein. Die Run Methode dieser Hintergrundaufgabe übergibt einfach die Triggerdetails (die die Visits-Informationen enthalten) an eine separate Methode.

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();
            }
        }        
    }
}

Definieren Sie die GetVisitReports Methode irgendwo in derselben Klasse.

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.
}

Als Nächstes müssen Sie im Standard Projekt Ihrer App die Registrierung dieser Hintergrundaufgabe durchführen. Erstellen Sie eine Registrierungsmethode, die von einer Benutzeraktion aufgerufen werden kann oder jedes Mal aufgerufen wird, wenn die Klasse aktiviert wird.

// 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()
    }
}

Dadurch wird festgelegt, dass eine im Namespace Tasks aufgerufene VisitBackgroundTask Hintergrundtaskklasse etwas mit dem location Triggertyp macht.

Ihre App sollte jetzt in der Lage sein, die Hintergrundaufgabe Besuchsbehandlung zu registrieren, und diese Aufgabe sollte aktiviert werden, wenn das Gerät eine Änderung des Besuchsstatus protokolliert. Sie müssen die Logik in Ihrer Hintergrundaufgabenklasse ausfüllen, um zu bestimmen, was mit diesen Zustandsänderungsinformationen zu tun ist.