Richtlinien für die Verwendung von Visits Tracking

Das Feature "Besuche" optimiert den Prozess der Standortverfolgung, um es für die praktischen Zwecke vieler Apps effizienter zu gestalten. Ein Besuch wird als ein bedeutender geografischer Bereich definiert, den der Benutzer ein- und verlässt. Besuche ähneln Geofences darin, dass sie zulassen, dass die App nur benachrichtigt wird, wenn der Benutzer bestimmte interessante Bereiche eingibt oder verlässt, wodurch die Notwendigkeit einer kontinuierlichen Standortnachverfolgung beseitigt wird, die eine Belastung der Akkulaufzeit sein 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, nach der eine App besucht wird, von einer einzelnen Granularitätseinstellung behandelt, anstatt einzelne Orte zu abonnieren.

Vorläufige Einstellungen

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

Denken Sie daran, den Geolocation Namespace zu Ihrer Klasse hinzuzufügen. Dies wird benötigt, damit alle Codeausschnitte in diesem Handbuch funktionieren.

using Windows.Devices.Geolocation;

Überprüfen Des neuesten Besuchs

Die einfachste Möglichkeit zum Verwenden der Funktion "Besuchsnachverfolgung" besteht darin, die letzte bekannte Änderung des statusbezogenen Status abzurufen. Eine Zustandsänderung ist ein plattformprotokolliertes Ereignis, bei dem der Benutzer entweder einen Ort der Bedeutung eingibt/verlässt, es seit dem letzten Bericht erhebliche Bewegungen gibt oder der Standort des Benutzers verloren geht (siehe VisitStateChange-Enumeration). Zustandsänderungen werden durch Geovisit-Instanzen dargestellt. Um die Geovisit-Instanz für die letzte aufgezeichnete Zustandsänderung abzurufen, verwenden Sie einfach die angegebene Methode in der GeovisitMonitor-Klasse.

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 einer Geovisit-Instanz (optional)

Mit der folgenden Methode werden alle in einer Geovisit-Instanz gespeicherten Informationen in eine leicht lesbare Zeichenfolge konvertiert. 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 des Überwachens von Zustandsänderungen über einen bestimmten Zeitraum. Sie können dies tun, indem Sie diese Klasse instanziieren, eine Handlermethode für das 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 behandelt die OnVisitStateChanged Methode eingehende Visit-Berichte. Die entsprechende Geovisit-Instanz 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 für Änderungen des besuchsbezogenen Zustands abgeschlossen hat, sollte sie den Monitor beenden und die Registrierung der Ereignishandler aufheben. Dies sollte auch 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 Visit Monitoring auch in einer Hintergrundaufgabe implementieren, sodass visit-related activity auch dann auf dem Gerät verarbeitet werden kann, wenn Ihre App nicht geöffnet ist. Dies ist die empfohlene Methode, da sie vielseitiger und energieeffizienter ist.

In diesem Leitfaden wird das Modell in create and register an out-of-process background task, in which the main application files live in one project and the background task file lives in a separate project in the same solution. Wenn Sie mit der Implementierung von Hintergrundaufgaben noch nicht vertraut sind, empfiehlt es sich, diese Anleitung in erster Linie zu befolgen und die erforderlichen Ersetzungen unten vorzunehmen, um eine Hintergrundaufgabe für die Behandlung von Besuchen zu erstellen.

Stellen Sie zunächst sicher, dass Ihre App Hintergrundaufgabenberechtigungen deklariert hat. Fügen Sie im Application/Extensions Element der Datei "Package.appxmanifest " die folgende Erweiterung hinzu (fügen Sie ein Extensions Element hinzu, wenn 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 Besuchsinformationen 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 an einer beliebigen Stelle 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 Hauptprojekt Ihrer App die Registrierung dieser Hintergrundaufgabe ausfü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 Hintergrundaufgabenklasse etwas mit dem location Triggertyp ausführt.

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 Der Hintergrundaufgabenklasse ausfüllen, um zu bestimmen, was mit diesen Statusänderungsinformationen zu tun ist.

Zugehörige Themen

• Erstellen und Registrieren einer Hintergrundaufgabe außerhalb von Prozessen
• Abrufen der Position eines Benutzers
• Windows.Devices.Geolocation-Namespace