مشاركة عبر

البرنامج التعليمي: إرسال إشعارات الدفع المستندة إلى الموقع باستخدام لوحات وصل الإشعارات والبيانات المكانية Bing

  • مقالة

في هذا البرنامج التعليمي، يمكنك التعرف على كيفية تقديم إشعارات الدفع المستندة إلى الموقع باستخدام لوحات الوصل الخاصة بالإشعار Azure والبيانات المكانية Bing.

في هذا البرنامج التعليمي، نُفذت الخطوات التالية:

  • إعداد مصدر البيانات
  • إعداد تطبيق UWP
  • إعداد الواجهة الخلفية
  • اختبار إشعارات الدفع في تطبيق النظام الأساسي Windows العالمي (UWP)

المتطلبات الأساسية

إعداد مصدر البيانات

  1. تسجيل الدخول إلى Bing Maps Dev Center.

  2. في شريط التنقل العلوي،‏ حدد مصادر البيانات،‏ وحدد إدارة مصادر البيانات.

    Screenshot of Bing Maps Dev Center on the Manage Data Sources page with the Upload data as a data source option outlined in red.

  3. إذا لم يكن لديك مصدر بيانات موجود، يمكنك رؤية ارتباط لإنشاء مصدر بيانات. حدد Upload data as a data source. يمكنك أيضاً استخدام قائمة Data sources>Upload data.

    Screenshot of the Upload a data source dialog box.

  4. إنشاء ملف NotificationHubsGeofence.pipe على القرص الصلب مع المحتوى التالي: يمكنك استخدام ملف أنبوب عينة يؤطر،‏ في هذا البرنامج التعليمي،‏ منطقة من الواجهة البحرية لسان فرانسيسكو:

    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))

    يمثل ملف توجيه الإخراج هذا الكيان:

    Screenshot of a map of the San Francisco waterfront with a red polygon outlining an area of the piers.

  5. في الصفحة تحميل مصدر بيانات،‏ قم بالإجراءات التالية:

    1. حدد توجيه لـ الإخراج لتنسيق البيانات.

    2. استعرض وحدد الملف NotificationHubGeofence.pipe الذي قمت بإنشائه في الخطوة السابقة.

    3. حدد زر تحميل.

      ملاحظة

      قد تجري مطالبتك بتحديد مفتاح جديد مفتاح رئيسي يختلف عن مفتاح الاستعلام. ببساطة قم بإنشاء مفتاح جديد من خلال لوحة المعلومات وتحديث صفحة تحميل مصدر البيانات.

  6. بمجرد تحميل ملف البيانات، يجب التأكد من نشر مصدر البيانات. حدد Data sources ->Manage Data Sources كما فعلت من قبل.

  7. حدد مصدر البيانات في القائمة،‏ واختر نشر في عمود الإجراءات.

    Screenshot of Bing Maps Dev Center on the Manage Data Sources page with the Geocoded Data tab selected and the Publish option outlined in red.

  8. قم بالتبديل إلى علامة التبويب مصادر البيانات المنشورة،‏ وتأكد من رؤية مصدر البيانات في القائمة.

    Screenshot of Bing Maps Dev Center on the Manage Data Sources page with the Published Data Sources tab selected.

  9. حدد "Edit". ترى (في لمحة) المواقع التي أدخلتها في البيانات.

    Screenshot of the Edit entity data page showing a map of the western united states and a magenta dot over the San Francisco waterfront.

    في هذه المرحلة،‏ لا تظهر لك البوابة حدود الجيوفينس التي أنشأتها - كل ما تحتاجه هو التأكيد على أن الموقع المحدد في المنطقة المجاورة الصحيحة.

  10. الآن لديك كل المتطلبات لمصدر البيانات. للحصول على التفاصيل على عنوان URL للطلب الخاص بمكالمة API،‏ في Bing Maps Dev Center،‏ اختر مصادر البيانات وحدد معلومات مصدر البيانات.

    Screenshot of Bing Maps Dev Center on the Data source information page.

    عنوان Query URL هو نقطة النهاية التي يمكنك من خلالها تنفيذ الاستعلامات للتحقق مما إذا كان الجهاز حاليّاً ضمن حدود موقع أم لا. لتنفيذ هذا الاختيار، يمكنك تنفيذ طلب GET على الاستعلام URL مع المعلمات التالية الملحقة:

    ?spatialFilter=intersects(%27POINT%20LONGITUDE%20LATITUDE)%27)&$format=json&key=QUERY_KEY

    يقوم Bing Maps تلقائيّاً بإجراء العمليات الحسابية لمعرفة ما إذا كان الجهاز داخل الجيوفينس. بمجرد تنفيذ الطلب من خلال مستعرض (أو cURL)، ستحصل على استجابة JSON قياسية:

    Screenshot of the standard JSON response.

    يحدث هذا الرد فقط عندما تكون النقطة في الواقع داخل الحدود المعينة. إذا لم يكن كذلك،‏ يمكنك الحصول على دلو نتائج فارغ:

    Screenshot of a JSON response with an empty results bucket.

إعداد تطبيق UWP

  1. في Visual Studio،‏ بدء مشروع جديد من نوع Blank App (Windows العالمي).

    Screenshot of a Visual Studio New Project dialog box with the Blank App (Universal Windows Visual C# option highlighted.

    بمجرد اكتمال إنشاء المشروع، يجب أن يكون لديك تسخير للتطبيق نفسه. الآن دعونا نقيم كل شيء للبنية الأساسية الجغرافية المبارزة. نظراً لأنك ستستخدم خدمات Bing لهذا الحل، توجد نقطة نهاية REST API عامة تسمح لك بالاستعلام عن إطارات مواقع محددة:

    http://spatial.virtualearth.net/REST/v1/data/

    حدد المعلمات التالية للعمل:

    • معرف مصدر البيانات واسم مصدر البيانات – في Bing Maps API،‏ تحتوي مصادر البيانات على بيانات تعريفية مختلفة،‏ مثل المواقع وساعات العمل.

    • اسم الكيان – الكيان الذي تريد استخدامه كنقطة مرجعية للإخطار.

    • Bing Maps API Key – المفتاح الذي حصلت عليه سابقاً عند إنشاء حساب Bing Dev Center.

      الآن بعد أن أصبح لديك مصدر البيانات جاهزاً، يمكنك بدء العمل على تطبيق UWP.

  2. تمكين خدمات الموقع للتطبيق الخاص بك. افتح ملف Package.appxmanifest في Solution Explorer.

    Screenshot of Solution Explorer with the Package.appxmanifest file highlighted.

  3. في علامة تبويب خصائص الحزمة التي فتحت للتو،‏ قم بالتبديل إلى علامة التبويب القدرات،‏ وحدد الموقع.

    Screenshot of the Package Properties dialog box showing the Capabilities tab with the Location option highlighted.

  4. إنشاء مجلد جديد في الحل المسمى Core،‏ وإضافة ملف جديد داخله،‏ يسمى LocationHelper.cs:

    Screenshot of Solution Explorer with the new Core folder highlighted.

    الفئة LocationHelper لديها تعليمات برمجية للحصول على موقع المستخدم من خلال API النظام:

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

    }
}

    لمعرفة المزيد عن الحصول على موقع المستخدم في تطبيقات UWP،‏ راجع الحصول على موقع المستخدم.

  5. للتحقق من أن عملية الاستحواذ على الموقع تعمل بالفعل،‏ افتح جانب التعليمة البرمجية للصفحة الرئيسية (MainPage.xaml.cs). إنشاء معالج حدث جديد للحدث Loaded في المنشئ MainPage.

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

    تنفيذ معالج الأحداث كما يلي:

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

  6. تشغيل التطبيق والسماح له بالوصول إلى موقعك.

    Screenshot of the Let Notification Hubs Geo Fence access your location dialog box.

  7. بمجرد تشغيل التطبيق،‏ يجب أن تكون قادراً على رؤية الإحداثيات في إطار الإخراج:

    Screenshot of the output window displaying the coordinates.

    الآن أنت تعرف أن استحواذ الموقع يعمل، يمكنك إزالة معالج الحدث المحمل إذا أردت لأنك لن تستخدمه بعد الآن.

  8. الخطوة التالية هي التقاط تغييرات الموقع. في الفئة LocationHelper،‏ قم بإضافة معالج الأحداث لـ PositionChanged:

    geolocator.PositionChanged += Geolocator_PositionChanged;

    يظهر التطبيق إحداثيات الموقع في إطار الإخراج:

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

إعداد الواجهة الخلفية

  1. تحميل .NET Backend Sample from GitHub.

  2. بمجرد اكتمال التنزيل،‏ افتح المجلد NotifyUsers،‏ ثم افتح الملف NotifyUsers.sln في Visual Studio.

  3. تعيين المشروع AppBackend كـ مشروع StartUp ثم قم بتشغيله.

    Screenshot of the Solution right-click menu with the Set as StartUp Project option highlighted.

    تم تكوين المشروع بالفعل لإرسال إشعارات الدفع إلى الأجهزة المستهدفة،‏ لذلك تحتاج إلى القيام بأمرين فقط - تحديد سلسلة الاتصال الصحيحة لمركز الإعلام وإضافة تعريف الحدود لإرسال الإشعار فقط عندما يكون المستخدم داخل الجيوفينس.

  4. لتكوين سلسلة الاتصال،‏ في المجلد Models افتح Notifications.cs. يجب أن تحتوي الدالة NotificationHubClient.CreateClientFromConnectionString على معلومات عن مركز الإعلامات الذي يمكنك الحصول عليه في مدخل Microsoft Azure (ابحث داخل صفحة نُهج الوصول في الإعدادات). حفظ ملف التكوين المحدث.

  5. إنشاء نموذج لنتيجة API خرائط Bing. أسهل طريقة للقيام بذلك هي فتح المجلد Models واختيار إضافة>فئة. سمّه GeofenceBoundary.cs. بمجرد الانتهاء، نسخ JSON من استجابة API التي حصلت عليها في القسم الأول. في Visual Studio،‏ استخدم تحرير>لصق خاص>لصق JSON كفئات.

    بهذه الطريقة تأكد من أن الكائن تم فك تسلسله تماماً كما كان المقصود. يجب أن تشبه مجموعة الفئات الناتجة الفئة التالية:

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

  6. بعد ذلك،‏ افتح Controllers>NotificationsController.cs. تحديث طلب Post لحساب خط الطول وخط العرض الهدف. للقيام بذلك،‏ إضافة سلسلتين إلى توقيع الدالة latitude - وlongitude.

    public async Task<HttpResponseMessage> Post(string pns, [FromBody]string message, string to_tag, string latitude, string longitude)

  7. إنشاء فئة جديدة داخل المشروع تسمى ApiHelper.cs - يمكنك استخدامها للاتصال بـ Bing للتحقق من تقاطعات حدود النقطة. تنفيذ دالة IsPointWithinBounds كما هو موضح في التعليمة البرمجية التالية:

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

    هام

    تأكد من استبدال نقطة نهاية API بعنوان URL الاستعلام الذي حصلت عليه سابقاً من Bing Dev Center (ينطبق نفس الأمر على مفتاح API).

    إذا كان هناك نتائج عن الاستعلام،‏ فهذا يعني أن النقطة المحددة تقع ضمن حدود الجيوفينس،‏ وبالتالي ترجع الدالة true. إذا لم تكن هناك نتائج،‏ Bing يخبرك أن النقطة خارج إطار البحث،‏ وبالتالي ترجع الدالة false.

  8. في NotificationsController.cs، إنشاء تحقق مباشرة قبل عبارة التبديل:

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

اختبار إشعارات الدفع في تطبيق UWP

  1. في تطبيق UWP، يجب أن تكون قادراً الآن على اختبار الإشعارات. ضمن الفئة LocationHelper،‏ قم بإنشاء دالة جديدة -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);
        }
    }
}

    ملاحظة

    تعيين POST_URL إلى موقع تطبيق الويب المنشور. في الوقت الحالي، لا بأس من تشغيله محليّاً، ولكن أثناء العمل على نشر إصدار عام، تحتاج إلى استضافته مع مزود خارجي.

  2. تسجيل التطبيق UWP لدفع الإشعارات. في Visual Studio،‏ اختر تطبيق Project>Store>المنتسب مع المتجر.

    Screenshot of the Solution right-click menu with the Store and Associate App with the Store options highlighted.

  3. بمجرد تسجيل الدخول إلى حساب المطور، تأكد من تحديد تطبيق موجود أو إنشاء تطبيق جديد وربط الحزمة به.

  4. انتقل إلى مركز التطوير وافتح التطبيق الذي أنشأته. اختر Services>Push Notifications>Live Services site.

    Screenshot of Windows Dev Center displaying the Push notifications page with Live Services site highlighted.

  5. على الموقع،‏ لاحظ Application Secret وPackage SID. تحتاج إلى كليهما في مدخل Microsoft Azure - افتح مركز الإعلام،‏ واختر الإعدادات>خدمات الإشعارات>Windows (WNS) وأدخل المعلومات في الحقول المطلوبة.

    Screenshot showing the Settings page with the Notification Services and Windows (WNS) options highlighted and the Package SID and Security Key values filled in.

  6. اختر حفظ.

  7. افتح المراجع في مستكشف الحلول وحدد إدارة حزم NuGet. إضافة مرجع إلى المكتبة المدارة "Microsoft Azure Service Bus" - ببساطة البحث عن WindowsAzure.Messaging.Managed وإضافته إلى المشروع الخاص بك.

    Screenshot of the Manage Nuget Packages dialog box with the WindowsAzure.Messaging.Managed package highlighted.

  8. لأغراض الاختبار،‏ قم بإنشاء معالج الحدث MainPage_Loaded مرة أخرى،‏ وأضف إليه قصاصة برمجية التعليمة البرمجية هذا:

    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.");
}

    يسجل الرمز التطبيق مع مركز الإشعارات. تمام!

  9. في LocationHelper، داخل المعالج Geolocator_PositionChanged،‏ يمكنك إضافة جزء من رمز الاختبار الذي يضع الموقع داخل الجيوفينس بقوة:

    await LocationHelper.SendLocationToBackend("wns", "TEST_USER", "TEST", "37.7746", "-122.3858");

  10. نظراً لعدم تمرير الإحداثيات الحقيقية (التي قد لا تكون ضمن الحدود في الوقت الحالي) واستخدام قيم اختبار معرفة مسبقاً، سترى إعلاماً يظهر عند التحديث:

    Screenshot of a Windows desktop displaying the TEST message.

الخطوات التالية

هناك بضع خطوات قد تحتاج إلى اتباعها لجعل الحل جاهزاً للإنتاج.

  1. أولاً، تحتاج إلى التأكد من أن الجيوفينس ديناميكية. تتطلب بعض العمل الإضافي مع API Bing لتكون قادرة على تحميل حدود جديدة داخل مصدر البيانات الموجودة. لمزيد من المعلومات،‏ راجع وثائق API لخدمات البيانات المكانية Bing.
  2. ثانياً،‏ بما أنك تعمل على ضمان أن يجري التسليم للمشاركين المناسبين،‏ فقد ترغب في استهدافهم عن طريق وضع العلامات.

يصف الحل الموضح في هذا البرنامج التعليمي سيناريو قد يكون لديك فيه مجموعة واسعة من المنصات المستهدفة، لذلك لا يحد من الجيوفينسية إلى قدرات خاصة بالنظام. ومع ذلك،‏ فإن نظام Windows العالمي يوفر قدرات الكشف عن الإيقاعات الجغرافية خارج الصندوق.