Share via

Panduan untuk menggunakan pelacakan Kunjungan

  • Artikel

Catatan

Layanan MapControl dan peta memerlukan kunci autentikasi peta yang disebut MapServiceToken. Untuk informasi selengkapnya tentang mendapatkan dan mengatur kunci autentikasi peta, lihat Meminta kunci autentikasi peta.

Fitur Visits menyederhanakan proses pelacakan lokasi untuk membuatnya lebih efisien untuk tujuan praktis banyak aplikasi. Kunjungan didefinisikan sebagai area geografis signifikan yang dimasukkan dan keluar pengguna. Kunjungan mirip dengan geofence karena mereka memungkinkan aplikasi untuk diberi tahu hanya ketika pengguna memasuki atau keluar dari area tertentu yang menarik, menghilangkan kebutuhan akan pelacakan lokasi berkelanjutan yang dapat menjadi pengosongan pada masa pakai baterai. Namun, tidak seperti geofence, area Visit diidentifikasi secara dinamis di tingkat platform dan tidak perlu didefinisikan secara eksplisit oleh aplikasi individual. Selain itu, pilihan kunjungan yang akan dilacak aplikasi ditangani oleh satu pengaturan granularitas, daripada dengan berlangganan ke tempat-tempat individual.

Penyiapan awal

Sebelum melaju lebih jauh, pastikan aplikasi Anda mampu mengakses lokasi perangkat. Anda harus mendeklarasikan Location kemampuan dalam manifes dan memanggil metode Geolocator.RequestAccessAsync untuk memastikan bahwa pengguna memberikan izin lokasi aplikasi. Lihat Mendapatkan lokasi pengguna untuk informasi selengkapnya tentang cara melakukannya.

Ingatlah untuk menambahkan namespace ke Geolocation kelas Anda. Ini akan diperlukan agar semua cuplikan kode dalam panduan ini berfungsi.

using Windows.Devices.Geolocation;

Periksa Kunjungan terbaru

Cara paling sederhana untuk menggunakan fitur pelacakan Kunjungan adalah dengan mengambil perubahan status terkait Kunjungan terakhir yang diketahui. Perubahan status adalah peristiwa yang dicatat platform di mana pengguna memasuki/keluar dari lokasi signifikansi, ada pergerakan signifikan sejak laporan terakhir, atau lokasi pengguna hilang (lihat enum VisitStateChange ). Perubahan status diwakili oleh instans Geovisit . Untuk mengambil instans Geovisit untuk perubahan status terakhir yang direkam, cukup gunakan metode yang ditunjuk di kelas GeovisitMonitor .

Catatan

Memeriksa Kunjungan terakhir yang dicatat tidak menjamin bahwa Kunjungan saat ini sedang dilacak oleh sistem. Untuk melacak Kunjungan saat itu terjadi, Anda harus memantaunya di latar depan atau mendaftar untuk pelacakan latar belakang (lihat bagian di bawah).

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

Mengurai instans Geovisit (opsional)

Metode berikut mengonversi semua informasi yang disimpan dalam instans Geovisit menjadi string yang mudah dibaca. Ini dapat digunakan dalam salah satu skenario dalam panduan ini untuk membantu memberikan umpan balik untuk Kunjungan yang dilaporkan.

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

Memantau Kunjungan di latar depan

Kelas GeovisitMonitor yang digunakan di bagian sebelumnya juga menangani skenario mendengarkan perubahan status selama periode waktu tertentu. Anda dapat melakukan ini dengan membuat instans kelas ini, mendaftarkan metode handler untuk peristiwanya, dan memanggil Start metode .

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

Dalam contoh ini, OnVisitStateChanged metode akan menangani laporan Kunjungan masuk. Instans Geovisit yang sesuai diteruskan melalui parameter peristiwa.

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

Setelah aplikasi selesai memantau perubahan status terkait Kunjungan, aplikasi harus menghentikan pemantauan dan membatalkan pendaftaran penanganan aktivitas. Ini juga harus dilakukan setiap kali aplikasi ditangguhkan atau ditutup.

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

Pantau Kunjungan di latar belakang

Anda juga dapat menerapkan pemantauan Kunjungi di tugas latar belakang, sehingga aktivitas terkait Kunjungan dapat ditangani di perangkat bahkan saat aplikasi Anda tidak terbuka. Ini adalah metode yang direkomendasikan, karena lebih serbaguna dan hemat energi.

Panduan ini akan menggunakan model dalam Membuat dan mendaftarkan tugas latar belakang di luar proses, di mana file aplikasi utama tinggal dalam satu proyek dan file tugas latar belakang berada dalam proyek terpisah dalam solusi yang sama. Jika Anda baru menerapkan tugas latar belakang, disarankan agar Anda mengikuti panduan tersebut terutama, membuat substitusi yang diperlukan di bawah ini untuk membuat tugas latar belakang penanganan Kunjungan.

Catatan

Dalam cuplikan berikut, beberapa fungsi penting seperti penanganan kesalahan dan penyimpanan lokal tidak ada demi kesederhanaan. Untuk implementasi penanganan Kunjungan latar belakang yang kuat, lihat aplikasi sampel.

Pertama, pastikan aplikasi Anda telah mendeklarasikan izin tugas latar belakang. Application/Extensions Dalam elemen file Package.appxmanifest Anda, tambahkan ekstensi berikut (tambahkan Extensions elemen jika belum ada).

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

Selanjutnya, dalam definisi kelas tugas latar belakang, tempelkan kode berikut. Metode Run tugas latar belakang ini hanya akan meneruskan detail pemicu (yang berisi informasi Kunjungan) ke dalam metode terpisah.

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

Tentukan metode di GetVisitReports suatu tempat di kelas yang sama ini.

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

Selanjutnya, dalam proyek utama aplikasi, Anda harus melakukan pendaftaran tugas latar belakang ini. Buat metode pendaftaran yang dapat dipanggil oleh beberapa tindakan pengguna atau dipanggil setiap kali kelas diaktifkan.

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

Ini menetapkan bahwa kelas tugas latar belakang yang disebut VisitBackgroundTask di namespace Tasks akan melakukan sesuatu dengan location jenis pemicu.

Aplikasi Anda sekarang harus mampu mendaftarkan tugas latar belakang penanganan Kunjungan, dan tugas ini harus diaktifkan setiap kali perangkat mencatat perubahan status terkait Kunjungan. Anda harus mengisi logika di kelas tugas latar belakang Anda untuk menentukan apa yang harus dilakukan dengan informasi perubahan status ini.