Samouczek: wysyłanie powiadomień wypychanych opartych na lokalizacji przy użyciu usługi Notification Hubs i danych przestrzennych Bing

Artykuł
06/01/2023

Korzystając z tego samouczka, dowiesz się, jak dostarczać powiadomienia push oparte na lokalizacji przy użyciu usługi Azure Notification Hubs i danych przestrzennych usługi Bing.

W tym samouczku wykonasz następujące kroki:

Konfigurowanie źródła danych
Konfigurowanie aplikacji platformy uniwersalnej systemu Windows
Konfigurowanie zaplecza
Testowanie powiadomień push w aplikacji platformy uniwersalnej systemu Windows

Wymagania wstępne

Subskrypcja platformy Azure. Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto platformy Azure.
Program Visual Studio 2015 Update 1 lub nowszy (Community Edition).
Najnowsza wersja zestawu Azure SDK.
Konto Centrum deweloperów Map Bing (można utworzyć je bezpłatnie i skojarzyć z kontem Microsoft).

Konfigurowanie źródła danych

Zaloguj się do Centrum deweloperów Map Bing.
Wybierz pozycję Źródła danych na górnym pasku nawigacyjnym, a następnie wybierz pozycję Zarządzaj źródłami danych.
Jeśli nie masz źródła danych, możesz je utworzyć za pomocą widocznego linku. Wybierz pozycję Upload data as a data source (Przekaż dane jako źródło danych). Możesz również użyć menu Data sources>Upload data (Źródła danych > Przekaż dane).

Utwórz plik NotificationHubsGeofence.pipe na dysku twardym z następującą zawartością: W tym samouczku użyjesz przykładowego pliku opartego na potoku, który ramki obszaru nabrzeża San Francisco:

Bing Spatial Data Services, 1.0, TestBoundaries
EntityID(Edm.String,primaryKey)|Name(Edm.String)|Longitude(Edm.Double)|Latitude(Edm.Double)|Boundary(Edm.Geography)
1|SanFranciscoPier|||POLYGON ((-122.389825 37.776598,-122.389438 37.773087,-122.381885 37.771849,-122.382186 37.777022,-122.389825 37.776598))

Plik potoku reprezentuje następującą jednostkę:

Zrzut ekranu przedstawiający mapę nabrzeża San Francisco z czerwonym wielokątem przedstawiającym obszar molo.

Na stronie Upload a data source (Przekazywanie źródła danych) wykonaj następujące czynności:
1. Wybierz pozycję Pipe (Potok) w polu Data format (Format danych).
2. Wyszukaj i wybierz plik NotificationHubGeofence.pipe utworzony w poprzednim kroku.
3. Wybierz przycisk Upload (Przekaż).
  
  Uwaga
  
  Może zostać wyświetlony monit o określenie nowego klucza dla właściwości Klucz główny, który różni się od właściwości Klucz zapytania. Po prostu utwórz nowy klucz przy użyciu pulpitu nawigacyjnego i odśwież stronę przekazywania źródła danych.
Po przekazaniu pliku danych opublikuj źródło danych. Wybierz pozycję Źródła danych —> zarządzaj źródłami danych, tak jak wcześniej.
Wybierz źródło danych na liście, a następnie wybierz pozycję Publish (Publikuj) w kolumnie Actions (Akcje).
Otwórz kartę Published Data Sources (Opublikowane źródła danych) i upewnij się, że źródło danych jest widoczne na liście.
Zaznacz Edytuj. Od razu zobaczysz lokalizacje wprowadzone w danych.

W tym momencie w portalu nie są wyświetlane granice utworzonego wirtualnego ogrodzenia — potrzebne jest jedynie potwierdzenie, że określona lokalizacja znajduje się w odpowiedniej okolicy.
Teraz wszystkie wymagania dotyczące źródła danych zostały spełnione. Aby uzyskać szczegółowe informacje dotyczące adresu URL żądania dla wywołania interfejsu API, w Centrum deweloperów Map Bing wybierz pozycję Źródła danych i wybierz pozycję Informacje o źródle danych.

Adres URL zapytania to punkt końcowy, względem którego możemy wykonywać zapytania, aby sprawdzić, czy urządzenie znajduje się obecnie w granicach lokalizacji, czy nie. Aby to sprawdzić, wykonujemy wywołanie GET dla adresu URL zapytania z dołączonymi następującymi parametrami:
```
?spatialFilter=intersects(%27POINT%20LONGITUDE%20LATITUDE)%27)&$format=json&key=QUERY_KEY
```
Mapy Bing automatycznie wykonają obliczenia w celu sprawdzenia, czy urządzenie znajduje się w wirtualnym ogrodzeniu. Po wykonaniu żądania przy użyciu przeglądarki (lub programu cURL) uzyskasz standardową odpowiedź w formacie JSON:

Ta odpowiedź jest wysyłana tylko wtedy, gdy punkt rzeczywiście znajduje się w wyznaczonych granicach. W przeciwnym razie otrzymasz pusty zasobnik results:

Konfigurowanie aplikacji platformy uniwersalnej systemu Windows

W programie Visual Studio utwórz nowy projekt typu Pusta aplikacja (uniwersalna aplikacja systemu Windows).

Po zakończeniu tworzenia projektu uzyskasz dostęp do aplikacji. Teraz skonfigurujmy wszystko dla infrastruktury ogrodzenia geograficznego. Ponieważ w tym celu użyjemy usług Bing, możemy skorzystać z publicznego punktu końcowego interfejsu API REST, umożliwiającego wykonywanie zapytań dotyczących określonego zakresu lokalizacji:
```
http://spatial.virtualearth.net/REST/v1/data/
```
Aby przygotować go do pracy, określ następujące parametry:
- Identyfikator źródła danych i Nazwa źródła danych — w interfejsie API Map Bing źródła danych zawierają różne metadane w zasobnikach, takie jak lokalizacje i godziny pracy.
- Nazwa jednostki — jednostka, która ma być używana jako punkt odniesienia dla powiadomienia.
- Klucz interfejsu API Map Bing — klucz uzyskany wcześniej podczas tworzenia konta Centrum deweloperów Bing.
  
  Po przygotowaniu źródła danych możemy rozpocząć pracę nad aplikacją platformy uniwersalnej systemu Windows.
Włącz usługi lokalizacji dla aplikacji. Otwórz plik Package.appxmanifest w Eksploratorze rozwiązań.
Na karcie właściwości pakietu, która została otwarta, wybierz pozycję Możliwości, a następnie pozycję Lokalizacja.

W rozwiązaniu utwórz nowy folder o nazwie Core i dodaj do niego nowy plik o nazwie LocationHelper.cs:

Zrzut ekranu przedstawiający Eksplorator rozwiązań z wyróżnionym nowym folderem Core.

Klasa LocationHelper zawiera kod umożliwiający uzyskiwanie lokalizacji użytkownika przy użyciu interfejsu API systemu:

using System;
using System.Threading.Tasks;
using Windows.Devices.Geolocation;

namespace NotificationHubs.Geofence.Core
{
    public class LocationHelper
    {
        private static readonly uint AppDesiredAccuracyInMeters = 10;

        public async static Task<Geoposition> GetCurrentLocation()
        {
            var accessStatus = await Geolocator.RequestAccessAsync();
            switch (accessStatus)
            {
                case GeolocationAccessStatus.Allowed:
                    {
                        Geolocator geolocator = new Geolocator { DesiredAccuracyInMeters = AppDesiredAccuracyInMeters };

                        return await geolocator.GetGeopositionAsync();
                    }
                default:
                    {
                        return null;
                    }
            }
        }

    }
}

Aby dowiedzieć się więcej na temat uzyskiwania lokalizacji użytkownika w aplikacjach platformy UWP, zobacz Pobieranie lokalizacji użytkownika.

Aby sprawdzić, czy uzyskiwanie lokalizacji rzeczywiście działa, otwórz stronę kodu strony głównej (MainPage.xaml.cs). Utwórz nowy program obsługi zdarzeń dla zdarzenia Loaded w konstruktorze MainPage.

public MainPage()
{
    this.InitializeComponent();
    this.Loaded += MainPage_Loaded;
}

Implementacja programu obsługi zdarzeń wygląda następująco:

private async void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    var location = await LocationHelper.GetCurrentLocation();

    if (location != null)
    {
        Debug.WriteLine(string.Concat(location.Coordinate.Longitude,
            " ", location.Coordinate.Latitude));
    }
}

Uruchom aplikację i zezwól jej na dostęp do Twojej lokalizacji.
Po uruchomieniu aplikacji współrzędne powinny być widoczne w oknie Dane wyjściowe:

Teraz wiesz, że pozyskiwanie lokalizacji działa, możesz usunąć procedurę obsługi zdarzeń załadowanych, jeśli chcesz, ponieważ nie będzie już jej używać.

Następnym krokiem jest przechwytywanie zmian lokalizacji. W klasie LocationHelper dodaj program obsługi zdarzeń dla zdarzenia PositionChanged:

geolocator.PositionChanged += Geolocator_PositionChanged;

Implementacja umożliwia wyświetlenie współrzędnych lokalizacji w oknie Dane wyjściowe:

private static async void Geolocator_PositionChanged(Geolocator sender, PositionChangedEventArgs args)
{
    await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        Debug.WriteLine(string.Concat(args.Position.Coordinate.Longitude, " ", args.Position.Coordinate.Latitude));
    });
}

Konfigurowanie zaplecza

Pobierz przykład zaplecza programu .NET z usługi GitHub.
Po zakończeniu pobierania otwórz folder NotifyUsers, a następnie otwórz plik NotifyUsers.sln w programie Visual Studio.
Ustaw projekt AppBackend jako Projekt startowy, a następnie uruchom go.

Projekt jest już skonfigurowany do wysyłania powiadomień push do urządzeń docelowych, dlatego musimy wykonać tylko dwie czynności — podać odpowiednie parametry połączenia dla centrum powiadomień i dodać identyfikację granic, aby powiadomienie było wysyłane tylko wtedy, gdy użytkownik znajduje się w wirtualnym ogrodzeniu.
Aby skonfigurować parametry połączenia, w folderze Models otwórz plik Notifications.cs. Funkcja NotificationHubClient.CreateClientFromConnectionString powinna zawierać informacje o centrum powiadomień uzyskane w witrynie Azure Portal (na stronie Zasady dostępu w obszarze Ustawienia). Zapisz zaktualizowany plik konfiguracji.

Utwórz model dla wyniku interfejsu API Map Bing. W tym celu najłatwiej otworzyć folder Models, a następnie wybrać polecenie Dodaj>Klasa. Nazwij go GeofenceBoundary.cs. Następnie skopiuj kod JSON z odpowiedzi interfejsu API uzyskanej w pierwszej sekcji. W programie Visual Studio wybierz pozycję Edytuj>Wklej specjalnie>Wklej dane JSON jako klasy.

W ten sposób upewniamy się, że obiekt zostanie zdeserializowany dokładnie w zamierzony sposób. Wynikowy zestaw klas powinien wyglądać następująco:

namespace AppBackend.Models
{
    public class Rootobject
    {
        public D d { get; set; }
    }

    public class D
    {
        public string __copyright { get; set; }
        public Result[] results { get; set; }
    }

    public class Result
    {
        public __Metadata __metadata { get; set; }
        public string EntityID { get; set; }
        public string Name { get; set; }
        public float Longitude { get; set; }
        public float Latitude { get; set; }
        public string Boundary { get; set; }
        public string Confidence { get; set; }
        public string Locality { get; set; }
        public string AddressLine { get; set; }
        public string AdminDistrict { get; set; }
        public string CountryRegion { get; set; }
        public string PostalCode { get; set; }
    }

    public class __Metadata
    {
        public string uri { get; set; }
    }
}

Następnie otwórz plik Controllers>NotificationsController.cs. Zaktualizuj wywołanie metody POST, aby uwzględnić docelową długość i szerokość geograficzną. W tym celu po prostu dodaj dwa ciągi do sygnatury funkcji — latitude i longitude.
```
public async Task<HttpResponseMessage> Post(string pns, [FromBody]string message, string to_tag, string latitude, string longitude)
```

Utwórz nową klasę w projekcie o nazwie ApiHelper.cs. Zostanie ona użyta do połączenia z usługą Bing w celu sprawdzenia puntów przecięcia granic. Zaimplementuj funkcję IsPointWithinBounds zgodnie z poniższym kodem:

public class ApiHelper
{
    public static readonly string ApiEndpoint = "{YOUR_QUERY_ENDPOINT}?spatialFilter=intersects(%27POINT%20({0}%20{1})%27)&$format=json&key={2}";
    public static readonly string ApiKey = "{YOUR_API_KEY}";

    public static bool IsPointWithinBounds(string longitude,string latitude)
    {
        var json = new WebClient().DownloadString(string.Format(ApiEndpoint, longitude, latitude, ApiKey));
        var result = JsonConvert.DeserializeObject<Rootobject>(json);
        if (result.d.results != null && result.d.results.Count() > 0)
        {
            return true;
        }
        else
        {
            return false;
        }
    }
}

Ważne

Zastąp punkt końcowy interfejsu API adresem URL zapytania uzyskanym wcześniej z Centrum deweloperów Bing (to samo dotyczy klucza interfejsu API).

Jeśli uzyskano wyniki zapytania, oznacza to, że określony punkt znajduje się w granicach wirtualnego ogrodzenia, dlatego funkcja zwraca wartość true. Jeśli nie ma wyników, usługa Bing informuje nas, że punkt znajduje się poza obszarem wyszukiwania, dlatego funkcja zwraca wartość false.

W pliku NotificationsController.cs utwórz operację sprawdzania przed instrukcją switch:

if (ApiHelper.IsPointWithinBounds(longitude, latitude))
{
    switch (pns.ToLower())
    {
        case "wns":
            //// Windows 8.1 / Windows Phone 8.1
            var toast = @"<toast><visual><binding template=""ToastText01""><text id=""1"">" +
                        "From " + user + ": " + message + "</text></binding></visual></toast>";
            outcome = await Notifications.Instance.Hub.SendWindowsNativeNotificationAsync(toast, userTag);

            // Windows 10 specific Action Center support
            toast = @"<toast><visual><binding template=""ToastGeneric""><text id=""1"">" +
                        "From " + user + ": " + message + "</text></binding></visual></toast>";
            outcome = await Notifications.Instance.Hub.SendWindowsNativeNotificationAsync(toast, userTag);

            break;
    }
}

Testowanie powiadomień push w aplikacji platformy uniwersalnej systemu Windows

Teraz powinno być możliwe przetestowanie powiadomień w aplikacji platformy uniwersalnej systemu Windows. W klasie LocationHelper utwórz nową funkcję o nazwie SendLocationToBackend:

public static async Task SendLocationToBackend(string pns, string userTag, string message, string latitude, string longitude)
{
    var POST_URL = "http://localhost:8741/api/notifications?pns=" +
        pns + "&to_tag=" + userTag + "&latitude=" + latitude + "&longitude=" + longitude;

    using (var httpClient = new HttpClient())
    {
        try
        {
            await httpClient.PostAsync(POST_URL, new StringContent("\"" + message + "\"",
                System.Text.Encoding.UTF8, "application/json"));
        }
        catch (Exception ex)
        {
            Debug.WriteLine(ex.Message);
        }
    }
}

Uwaga

Ustaw zmienną POST_URL na wartość lokalizacji wdrożonej aplikacji internetowej. Na razie możesz uruchomić go lokalnie, ale podczas wdrażania wersji publicznej należy go hostować za pomocą zewnętrznego dostawcy.

Zarejestruj aplikację platformy uniwersalnej systemu Windows dla usługi powiadomień push. W programie Visual Studio wybierz pozycję Projekt>Magazyn>Skojarz aplikację z magazynem.
Po zalogowaniu się do konta dewelopera wybierz istniejącą aplikację lub utwórz nową i skojarz z nią pakiet.
Przejdź do Centrum deweloperów i otwórz utworzoną aplikację. Wybierz pozycję Usługi>Powiadomienia wypychane>Witryna usług Live.
W witrynie zanotuj Klucz tajny aplikacji i Identyfikator SID pakietu. Obie wartości będą potrzebne w witrynie Azure Portal. Otwórz centrum powiadomień, wybierz pozycję Ustawienia>Usługi powiadomień>Windows (WNS) i wprowadź informacje w wymaganych polach.
Wybierz pozycję Zapisz.
Otwórz obszar Odwołania w Eksploratorze rozwiązań i wybierz pozycję Zarządzaj pakietami NuGet. Dodaj odwołanie do biblioteki zarządzanej usługi Microsoft Azure Service Bus. Wyszukaj pakiet WindowsAzure.Messaging.Managed i dodaj go do projektu.

W celach testowych możemy ponownie utworzyć program obsługi zdarzeń MainPage_Loaded i dodać do niego następujący fragment kodu:

var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();

var hub = new NotificationHub("HUB_NAME", "HUB_LISTEN_CONNECTION_STRING");
var result = await hub.RegisterNativeAsync(channel.Uri);

// Displays the registration ID so you know it was successful
if (result.RegistrationId != null)
{
    Debug.WriteLine("Reg successful.");
}

Powyższy kod rejestruje aplikację w centrum powiadomień. Gotowe!

W elemencie LocationHelper w programie obsługi Geolocator_PositionChanged możesz dodać fragment kodu, który będzie wymuszać umieszczanie lokalizacji w wirtualnym ogrodzeniu:
```
await LocationHelper.SendLocationToBackend("wns", "TEST_USER", "TEST", "37.7746", "-122.3858");
```
Ponieważ nie są używane rzeczywiste współrzędne (które mogą obecnie znajdować się poza granicami), lecz wstępnie zdefiniowane wartości testowe, po aktualizacji zostanie wyświetlone powiadomienie:

Następne kroki

Jest kilka kroków, których wykonanie może być konieczne, aby mieć pewność, że rozwiązanie jest gotowe do zastosowania w środowisku produkcyjnym.

Najpierw musisz upewnić się, że wirtualne ogrodzenia są dynamiczne. To wymaga dodatkowej pracy z interfejsem API Bing w celu umożliwienia przekazywania nowych granic w ramach istniejącego źródła danych. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją interfejsu API usług Bing Spatial Data Services.
Upewniając się, że powiadomienia są dostarczane do odpowiednich uczestników, warto adresować je przy użyciu tagów.

W tym samouczku opisano scenariusz, w którym może występować wiele różnych platform docelowych, dlatego nie ograniczono wirtualnego grodzenia do możliwości specyficznych dla określonego systemu. Jednak platforma uniwersalna systemu Windows oferuje wbudowane możliwości wykrywania wirtualnych ogrodzeń.

Udostępnij za pośrednictwem