🛀🏾 💫 🌪️ بطاقات الولاء. Google Pay API for Passes in ASP.NET 👨🏿‍🔬 😸 🆗

دخلت تطبيقات تخزين البطاقات المصرفية حياتنا بسرعة بفضل Apple Wallet و Google Pay. تتيح لك كلتا المنصتين ، بالإضافة إلى الخدمات المصرفية ، العمل مع أنواع أخرى من البطاقات - بطاقات الولاء ، بطاقات الهدايا ، تذاكر الأحداث ، بطاقات الصعود إلى الطائرة ، إلخ.

أثناء العمل لدى شركة تقدم خدمات شبكة مبيعات كبيرة إلى حد ما ، اضطررت إلى دمج بطاقات الولاء لهذه الشبكة في Apple Wallet و Google Pay. وإذا كنت مضطرًا إلى العبث في Apple Wallet لمجرد أن طبقة التكامل متعددة الوظائف تمامًا ، فمع Google Pay تم بذل معظم الجهد وتم إنفاق الخلايا العصبية في محاولة لمعرفة الوثائق والعثور على الأدوات المناسبة وتطوير الدليل الأول للمفهوم. على الرغم من أن بقية العمل بشكل عام كان أسرع بكثير من Apple Wallet ، فقد قضيت يومًا في اكتشاف كيفية بدء الخدمة ، لذلك لا أمانع إذا كتب شخص ما مقالًا مشابهًا قبلي.

1. العتاد

يتم تمثيل بطاقات الولاء باستخدام كيانين - فئة الولاء وكائن الولاء.

فئة الولاء هي نوع من القوالب لجميع بطاقات الولاء. يحتوي على حقول شائعة في جميع الخرائط ، مثل لون الخط ، وروابط أصول الرمز ، والخلفيات ، وحقول النص ، وما إلى ذلك ، ويمكن الاطلاع على وصف كامل هنا: Loyaltyclass
كائن الولاء - مثيل لـ LoyaltyClass. كما أنه يحتوي على بيانات بطاقة معينة لعميل معين - رقم البطاقة والاسم والحقول النصية الإضافية. الوصف هنا: Loyaltyobject

من أجل الحصول على بطاقة ، يجب على المستخدم اتباع رابط التنسيق
www.android.com/payapp/savetoandroidpay / {JWT} ، حيث JWT هو رمز مميز يحمل JSON مع بيانات LoyaltyClass. ولكن نظرًا لأن طول عنوان URL له قيود ، فمن المستحسن أن تنشئ أولاً فئة ولاء إذا كان هيكلها يحتوي على العديد من الأحرف.

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

2. الأدوات والوثائق

تبين أن المشكلة تكمن في أن جميع الأمثلة الواردة في الوثائق الخاصة بواجهة برمجة تطبيقات Google Pay for Passes كانت مخصصة حصريًا لكل من Java و PHP و Python ، وقد أوصت الوثائق نفسها بشدة "باستخدام مكتبات العملاء لتبسيط عملية" العمل مع API.

باتباع هذه النصيحة ، ذهبت بسرور إلى nuget ، لكن مكتبة Google Pay لم تكن موجودة. قام Glory to Brin ، السطر الأول في Google بـ "google pay for passes dotnet" ، بإرجاع صفحة مكتبات تطبيقات Google Pay API لـ Passes ، التي عثرت على ما أحتاج إليه ، على الرغم من تنسيق أرشيف ZIP ، حيث كان هناك مشروع .net مع فئة تم إنشاؤها ، وهي عبارة عن غلاف لبرنامج Google Pay API - Google Pay API for Passes Client Library .

استنادا إلى وجود ملف Google.Apis.Walletobjects.v1.1.9.2.00.nuspec في المشروع ، كان نشر حزمة nuget لا يزال جزءًا من خطط فريق Google. بعد أن فتحت هذا الملف بحثًا عن الوثائق ، لم أجد أي شيء ملموس ، وتم إرسال بعض الروابط التي كانت موجودة في قسم الوصف إلى صفحات غير موجودة على الإطلاق.

3. الحصول على رمز الوصول

لبدء العمل مباشرة مع Google Pay API for Passes ، تحتاج إلى الحصول على رمز وصول ، لهذا تحتاج:

احصل على حساب Google Merchant ، والذي يمكنك الحصول عليه هنا
أنشئ حساب خدمة ، واحصل على ملف به بيانات اعتماد - مستند json به تفاصيل حساب خدمة ، بما في ذلك المعرف ، والبريد الإلكتروني ، والمفتاح الخاص ، إلخ. كما توصي الوثائق ، تحتاج إلى تخزين هذا الملف في مكان آمن.
ربط حساب التاجر وحساب الخدمة في Google Merchant Center

باستخدام هذا الملف ، يمكنك تسجيل الدخول باستخدام مكتبة Google.Apis.Auth.OAuth2 :

private await Task<string> GetOAuthToken() {         string serviceAccountFile = string.Empty;         serviceAccountFile = ConfigurationManager.AppSettings["GooglePayServiceAccountConfigPath"];        /*              Credential, GoogleCredential              Service Account,   ,      scopes API,             */         var credential = GoogleCredential.FromFile(serviceAccountFile)                            .CreateScoped(WalletobjectsService.Scope.WalletObjectIssuer);        /*        Access token        ,   GetAccessTokenForRequestAsync         ,               */         var token = async credential.UnderlyingCredential.GetAccessTokenForRequestAsync();         return token; }

4. إنشاء خريطة

لإنشاء بطاقة ولاء ، يجب عليك أولاً إنشاء فئة ولاء. يمكن إنشاء فئة الولاء باستخدام واجهة برمجة التطبيقات (API) واستخدام واجهة الويب الخاصة بـ Google Merchant Center. يجب إيلاء الاهتمام لاسم الفئة ، حيث يجب أن يكون هذا الاسم فريدًا في بنية Google Pay الأساسية.

بعد إنشاء فئة الولاء ، يمكنك إنشاء كائن الولاء. للقيام بذلك ، ستحتاج بالفعل إلى المكتبة التي أضفناها إلى المشروع مسبقًا: إنشاء كائن طلب ، وتحديد رمز OAuth ، ونقل كائن LoyaltyObject الذي تم إنشاؤه ، وتنفيذ الطلب:

 public GooglePayApiService() { // ,    Merchant Account IssuerId = ConfigurationManager.AppSettings["GooglePayIssuerId"]; _wobService = new WalletobjectsService(); } private async Task<LoyaltyObject> ConvertLoyaltyObjectFromTemplate(GooglePayPassTemplate template) { string id = $"{IssuerId}.{template.SerialNumber}"; string loyaltyClassName = ConfigurationManager.AppSettings["GooglePayStoreCardClassName"];     var loyaltyClass = await GetLoyaltyClass(loyaltyClassName); var result =  new LoyaltyObject { Id = id, AccountName = template.AccountName,          Barcode = new Barcode          {          AlternateText = template.BarcodeText,               Value = template.SerialNumber,               Type = "pdf417"          },          Kind = "walletObject#loyaltyObject",          ClassId = loyaltyClass.Id,          ClassReference = loyaltyClass,          State = "active"     };     return result; } private async Task<LoyaltyObject> CreateLoyaltyObject(LoyaltyObject loyaltyObject) { var saveRequest = _wobService.Loyaltyobject.Insert(loyaltyObject); saveRequest.OauthToken = await GetOAuthToken(); var savedObject = await saveRequest.ExecuteAsync(); return savedObject; }

GooglePayPassTemplate في هذا المثال هو DTO الذي يخزن قالب خريطة للمستخدم ، والذي يتم إنشاؤه بواسطة خدمة مطورة منفصلة.

5. خريطة التحديث

هنا المبدأ هو نفسه عند إنشاء: نقوم بإنشاء طلب ، ونقل كائن LoyaltyObject المحدث ، وتنفيذ:

 private async Task<LoyaltyObject> UpdateLoyaltyObject(LoyaltyObject loyaltyObject) { var updateRequest = _wobService.Loyaltyobject.Update(loyaltyObject, loyaltyObject.Id);           updateRequest.OauthToken = await GetOAuthToken(); var savedObject = await updateRequest.ExecuteAsync(); return savedObject; }

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

6. جيل JWT

لتثبيت البطاقة ، يجب إعادة توجيه المستخدم إلى الرابط www.android.com/payapp/savetoandroidpay / {JWT} . يمكن العثور على وصف للبنية الرمزية في هذا الرابط .

يتم توقيع الرمز المميز بواسطة RSA-SHA256 مع توقيع يمكن إنشاؤه باستخدام نفس الملف باستخدام بيانات اعتماد حساب الخدمة:

 public static class JwtHelper { public static string CreateJwtForLoyaltyObject(LoyaltyObject loyaltyObject) { /*       credential   ,         */ ServiceAccountCredential credential; var now = DateTime.UtcNow; DateTime unixEpoch = new DateTime(1970, 01, 01); // 1970-01-01 00:00:00 UTC var secondsSinceEpoch = (int)Math.Round((now - unixEpoch).TotalSeconds); string serviceAccountFile = serviceAccountFile = ConfigurationManager.AppSettings["GooglePayServiceAccountConfigPath"]; using (var fs = new FileStream(serviceAccountFile, FileMode.Open, FileAccess.Read, FileShare.Read)) { credential = ServiceAccountCredential.FromServiceAccountData(fs); } /*    JwtPayload,     payload-a  JWT */ var jwtPayload = new JwtPayload { iat = secondsSinceEpoch, iss = credential.Id, payload = new JwtInternalPayload { loyaltyObjects = new[] { new LoyaltyObjectPayload { id = loyaltyObject.Id } } } }; string header = @"{""alg"":""RS256"",""typ"":""JWT""}"; string payload = JsonConverter.SerializeObject(jwtPayload); string base64Header = EscapedBase64(Convert.ToBase64String(Encoding.UTF8.GetBytes(header))); string base64Payload = EscapedBase64(Convert.ToBase64String(Encoding.UTF8.GetBytes(payload))); //        Signature string signature = EscapedBase64(credential.CreateSignature( Encoding.UTF8.GetBytes($"{base64Header}.{base64Payload}") )); var token = $"{base64Header}.{base64Payload}.{signature}"; return token; } private static string EscapedBase64(string base64) { return base64.Replace('+', '-') .Replace('/', '_') .Replace("=", ""); } }

الخاتمة

في هذه المقالة ، استعرضنا أساسيات العمل مع Google Pay API for Passes: إعداد الحسابات ، والاتصال بـ API ، وإنشاء فئة الولاء وكائن الولاء.

إذا كنت تفضل UFO ، فسأخبرك بشكل منفصل عن كيفية العمل مع Apple Wallet (كل شيء أكثر صعوبة فيما يتعلق بالتنفيذ) ، وكيفية تكوين Apple Wallet مع Google Pay في خدمة ويب واحدة وعدم الشعور بالألم.

بطاقات الولاء. Google Pay API for Passes in ASP.NET