تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إنشاء البطاقات على أجهزة Android باستخدام Google Wallet API

1. مقدمة

نظرة عامة

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

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

بطاقات ركن السيارات
بطاقات عضوية المكتبة
قسائم القيمة المخزّنة
بطاقات العضوية في الصالات الرياضية
الحجوزات

يمكنك استخدام بطاقات عامة لأي حالة استخدام يمكن عرضها باستخدام:

ما يصل إلى ثلاثة صفوف من المعلومات
(اختياري) رسم الرمز الشريطي
(اختياري) قسم التفاصيل

جهاز يعمل بنظام التشغيل Android يعرض عملية الإعداد "إضافة إلى محفظة Google"

لمزيد من المعلومات حول Google Wallet API أو إضافة زر الإضافة إلى "محفظة Google" إلى أحد تطبيقات Android، يُرجى الاطّلاع على مستندات مطوّري Google Wallet.

تمرير الفئات والكائنات

تعرض Google Wallet API طرقًا لإنشاء ما يلي:

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

لمحة عن هذا الدرس التطبيقي حول الترميز

في هذا الدرس التطبيقي، ستكمل المهام التالية.

إنشاء حساب جهة إصدار جديد في الوضع التجريبي
إنشاء حساب خدمة لإصدار البطاقات
إنشاء فئة جديدة من البطاقات العامة
إنشاء عنصر بطاقة جديد
إنشاء زر الإضافة إلى "محفظة Google" لحفظ بطاقة
عرض الزر في تطبيق Android
التعامل مع نتيجة حفظ البطاقة

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

استوديو Android
Git
حساب Google لديه إذن الوصول إلى وحدة تحكّم Google Cloud
الإصدار 10 أو إصدار أحدث من Node.js

الأهداف

بعد إكمال هذا الدرس التطبيقي، ستتمكّن من تنفيذ ما يلي:

إضافة حزمة تطوير البرامج (SDK) الخاصة بـ "محفظة Google" إلى تطبيق Android
التحقّق من توفّر Google Wallet API على جهاز يعمل بنظام التشغيل Android
إنشاء زر الإضافة إلى "محفظة Google"

الدعم

إذا واجهتك أي مشكلة في أي مرحلة من مراحل هذا الدرس العملي، يحتوي مستودع google-pay/wallet-android-codelab على GitHub على حلّ كامل يمكنك الرجوع إليه.

2. الإعداد

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

يجب توفّر حساب "جهة إصدار" لإنشاء بطاقات ومشاركتها في Google Wallet. يمكنك الاشتراك باستخدام Google Pay & Wallet Console. في البداية، سيكون بإمكانك إنشاء بطاقات في الوضع التجريبي. وهذا يعني أنّ مستخدمي الاختبار المحدّدين فقط سيتمكّنون من إضافة البطاقات التي تنشئها. يمكن إدارة المستخدمين التجريبيين في Google Pay & Wallet Console.

لمزيد من المعلومات حول الوضع التجريبي، اطّلِع على المتطلبات الأساسية لبطاقة المرور العامة.

افتح Google Pay & Wallet Console
اتّبِع التعليمات الظاهرة على الشاشة لإنشاء حساب "جهة إصدار".
اختَر Google Wallet API.
تأكيد فهمك لبنود الخدمة وسياسة الخصوصية
انسخ قيمة رقم تعريف جهة الإصدار إلى محرر نصوص أو موقع آخر.
ضمن علامة التبويب إدارة، انقر على إعداد حسابات اختبارية.
أضِف أي عناوين بريد إلكتروني ستستخدمها في هذا الدرس العملي.

تفعيل Google Wallet API

سجِّل الدخول إلى وحدة تحكّم Google Cloud.
إذا لم يكن لديك مشروع على Google Cloud، أنشِئ مشروعًا الآن (راجِع مقالة إنشاء المشاريع وإدارتها لمزيد من المعلومات).
فعِّل Google Wallet API (المعروف أيضًا باسم Google Pay for Passes API) لمشروعك

إنشاء حساب خدمة ومفتاح

يجب توفّر حساب خدمة ومفتاح حساب خدمة لاستدعاء Google Wallet API. حساب الخدمة هو الهوية التي تستدعي Google Wallet API. يحتوي مفتاح حساب الخدمة على مفتاح خاص يعرّف تطبيقك على أنّه حساب الخدمة. هذا المفتاح حسّاس، لذا يجب الحفاظ على سريته.

إنشاء حساب خدمة

في Google Cloud Console، افتح حسابات الخدمة.
أدخِل اسمًا ورقم تعريف ووصفًا لحساب الخدمة
انقر على إنشاء ومتابعة.
انقر على تم.

إنشاء مفتاح حساب خدمة

اختيار حساب الخدمة
انقر على قائمة المفاتيح
انقر على إضافة مفتاح، ثم على إنشاء مفتاح جديد.
اختَر نوع المفتاح JSON
انقر على إنشاء.

سيُطلب منك حفظ ملف المفتاح في محطة العمل المحلية. احرص على تذكُّر موقعه الجغرافي.

ضبط متغيّر البيئة `GOOGLE_APPLICATION_CREDENTIALS`

يتم استخدام متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS من خلال حِزم تطوير البرامج (SDK) من Google للمصادقة كحساب خدمة والوصول إلى واجهات برمجة تطبيقات مختلفة لأحد المشاريع على Google Cloud.

اتّبِع التعليمات الواردة في مستندات مفاتيح حسابات الخدمة في Google Cloud لضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS.
تأكَّد من ضبط متغيّر البيئة في جلسة جديدة من الوحدة الطرفية (نظام التشغيل MacOS أو Linux) أو سطر الأوامر (نظام التشغيل Windows) (قد تحتاج إلى بدء جلسة جديدة إذا كانت لديك جلسة مفتوحة حاليًا).
```
echo $GOOGLE_APPLICATION_CREDENTIALS
```

تفويض حساب الخدمة

أخيرًا، عليك منح حساب الخدمة الإذن بإدارة بطاقات Google Wallet.

افتح Google Pay & Wallet Console
اختَر المستخدمون.
انقر على دعوة مستخدم.
أدخِل عنوان البريد الإلكتروني لحساب الخدمة (مثلاً test-svc@myproject.iam.gserviceaccount.com).
اختَر مطوِّر أو مشرف من القائمة المنسدلة مستوى الوصول
انقر على دعوة.

3- إنشاء فئة بطاقة عامة

في هذه الخطوة، ستنشئ الفئة الأساسية للبطاقة. في كل مرة يتم فيها إنشاء بطاقة جديدة لمستخدم، سترِث هذه البطاقة الخصائص المحدّدة في فئة البطاقة.

يستفيد صف البطاقة الذي ستنشئه خلال هذا الدرس التطبيقي حول الترميز من مرونة البطاقات العامة لإنشاء عنصر يعمل كبطاقة تعريف وتتبُّع لنقاط التحدي. عند إنشاء عنصر بطاقة من هذه الفئة، سيظهر على النحو التالي.

يمكن إنشاء بطاقات الصف مباشرةً في Google Pay & Wallet Console أو باستخدام Google Wallet API. في هذا الدرس التطبيقي حول الترميز، ستنشئ فئة البطاقة العامة باستخدام واجهة برمجة التطبيقات. يتبع ذلك العملية التي يستخدمها خادم خاص للواجهة الخلفية لإنشاء فئات البطاقات.

استنسِخ مستودع GitHub google-pay/wallet-android-codelab إلى محطة العمل المحلية
```
git clone https://github.com/google-pay/wallet-android-codelab.git
```
افتح المستودع الذي تم استنساخه في نافذة Terminal أو موجه سطر الأوامر
انتقِل إلى الدليل backend (تحاكي هذه النصوص البرمجية إجراءات خادم الخلفية)
```
cd backend
```
تثبيت التبعيات في Node.js
```
npm install .
```
في دليل backend، افتح generic_class.js
استبدِل قيمة issuerId بمعرّف الجهة المصدرة من Google Pay & Wallet Console
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
في الوحدة الطرفية أو سطر الأوامر، شغِّل النص البرمجي generic_class.js
```
node generic_class.js
```

عند تشغيل الرمز، سيتم إنشاء فئة بطاقة جديدة وعرض معرّف الفئة. يتألف معرّف الفئة من معرّف جهة الإصدار متبوعًا بلاحقة يحدّدها المطوّر. في هذه الحالة، يتم ضبط اللاحقة على codelab_class (سيكون معرّف الفئة مشابهًا لـ 1234123412341234123.codelab_class). ستتضمّن سجلّات الإخراج أيضًا الردّ من Google Wallet API.

4. فتح المشروع في "استوديو Android"

يحتوي مستودع GitHub الذي استنسخته على مشروع Android يتضمّن نشاطًا فارغًا. في هذه الخطوة، ستعدّل هذا النشاط لتضمين زر الإضافة إلى محفظة Google في صفحة المنتج.

فتح "استوديو Android"
انقر على ملف، ثم على فتح
اختَر الدليل android في المستودع
انقر على فتح.

إضافة حزمة تطوير البرامج (SDK) الخاصة بـ "محفظة Google" إلى تطبيقك

افتح ملف Gradle البرمجي على مستوى الوحدة (android/app/build.gradle)

أضِف حزمة تطوير البرامج (SDK) الخاصة بـ "محفظة Google" إلى القسم dependencies

// TODO: Add the "com.google.android.gms:play-services-pay" dependency to
//       use the Google Wallet API
implementation "com.google.android.gms:play-services-pay:16.0.3"

احفظ الملف.
انقر على ملف (File)، ثم على مزامنة المشروع مع ملفات Gradle (Sync Project with Gradle Files).

5- إنشاء زر الإضافة إلى "محفظة Google"

في هذه الخطوة، ستنشئ زر الإضافة إلى محفظة Google وتضيفه إلى نشاط حالي. تمت إضافة مواد عرض الزر إلى المشروع. لتضمين الزر، عليك إنشاء ملف تصميم منفصل. بعد إضافة الزر، سيظهر بالشكل التالي.

أنشئ ملف تنسيق جديدًا: app/src/main/res/layout/add_to_google_wallet_button.xml

أضِف المحتوى التالي إلى ملف التصميم الجديد

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="48sp"
    android:background="@drawable/add_to_google_wallet_button_background_shape"
    android:clickable="true"
    android:contentDescription="@string/add_to_google_wallet_button_content_description"
    android:focusable="true">
  <ImageView
      android:layout_width="227dp"
      android:layout_height="26dp"
      android:layout_gravity="center"
      android:duplicateParentState="true"
      android:src="@drawable/add_to_google_wallet_button_foreground" />
</FrameLayout>

تضمين التصميم add_to_google_wallet_button.xml في ملف تصميم نشاط الدفع (app/src/main/res/layout/activity_checkout.xml)

<!--
    TODO: Create the button under `add_to_google_wallet_button.xml`
          and include it in your UI
-->
<include
    android:id="@+id/addToGoogleWalletButton"
    layout="@layout/add_to_google_wallet_button"
    android:layout_width="match_parent"
    android:layout_height="48dp"
    android:layout_marginTop="10dp" />

6. التحقّق من توفّر Google Wallet API

إذا فتح أحد المستخدمين تطبيقك على جهاز لا يتوافق مع Google Wallet API، قد يؤدي ذلك إلى تجربة سلبية عند محاولة إضافة البطاقة. إذا كان جهاز المستخدم لا يتوافق مع واجهة برمجة التطبيقات Google Wallet API، سيؤدي إخفاء الزر الإضافة إلى "محفظة Google" إلى تجنُّب أي التباس محتمل. هناك أسباب مختلفة قد تؤدي إلى عدم توفّر واجهة برمجة التطبيقات، مثل عدم تحديث إصدارات Android أو "خدمات Google Play" أو عدم توفّر Google Wallet في بلد المستخدم.

في هذه الخطوة، ستضيف منطقًا إلى تطبيقك يتحقّق مما إذا كانت Google Wallet API متاحة على الجهاز. وفي هذه الحالة، سيتم عرض الزر في النشاط. وإلا، سيتم إخفاء الزر.

افتح الملف CheckoutActivity.kt في app/src/main/java/com/google/android/gms/samples/wallet/activity/

إنشاء سمة صف لمثيل PayClient

// TODO: Create a client to interact with the Google Wallet API
private lateinit var walletClient: PayClient

إنشاء مثيل للسمة PayClient في الطريقة onCreate

// TODO: Instantiate the client
walletClient = Pay.getClient(this)

إنشاء طريقة للتحقّق من توفّر حزمة تطوير البرامج (SDK) وواجهة برمجة التطبيقات (API) في Google Wallet على الجهاز والتعامل مع النتيجة

// TODO: Create a method to check for the Google Wallet SDK and API
private fun fetchCanUseGoogleWalletApi() {
  walletClient
    .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
    .addOnSuccessListener { status ->
      if (status == PayApiAvailabilityStatus.AVAILABLE)
        layout.passContainer.visibility = View.VISIBLE
    }
    .addOnFailureListener {
      // Hide the button and optionally show an error message
    }
}

استدعِ طريقة fetchCanUseGoogleWalletApi في طريقة onCreate للتحقّق مما إذا كانت Google Wallet API متاحة
```
// TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()
```

عند تشغيل التطبيق، من المفترض أن يظهر لك الآن الزر الإضافة إلى "محفظة Google" في واجهة المستخدم.

7. إنشاء عنصر بطاقة عامة

بعد التأكّد من توفّر Google Wallet API، يمكنك إنشاء بطاقة ومطالبة المستخدم بإضافتها إلى محفظته. هناك مساران لإنشاء عناصر البطاقات للمستخدمين.

إنشاء عنصر البطاقة على خادم الخلفية

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

إنشاء عنصر البطاقة عند إضافة المستخدم لها إلى محفظته

في هذا الأسلوب، يتم تحديد عنصر البطاقة وترميزه في رمز ويب JSON موقَّع على خادم الخلفية. بعد ذلك، يتم عرض زر الإضافة إلى محفظة Google في تطبيق العميل الذي يشير إلى رمز JWT. عندما ينقر المستخدم على الزر، يتم استخدام رمز JWT لإنشاء عنصر البطاقة. هذا الخيار هو الأنسب للحالات التي يكون فيها معدّل استخدام المستخدمين متغيّرًا أو غير معروف، لأنّه يمنع إنشاء عناصر البطاقات وعدم استخدامها. سيتم استخدام هذا الأسلوب في الدرس العملي.

افتح ملف backend/generic_pass.js
استبدِل قيمة issuerId بمعرّف الجهة المصدرة من Google Pay & Wallet Console
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
في الوحدة الطرفية أو سطر الأوامر، شغِّل ملف generic_pass.js
```
node generic_pass.js
```
انسخ الرمز المميز الناتج إلى الحافظة أو إلى برنامج تعديل النصوص.

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

aside في بيئة الإنتاج، سيكون نظام الخلفية مسؤولاً عن إنشاء رموز JWT وإرسالها إلى العملاء. في هذا الدرس التطبيقي حول الترميز، يحاكي النص البرمجي generic_pass.js هذا السلوك و "يعرض" رمزًا مميزًا لتستخدمه في تطبيق العميل.

8. إضافة البطاقة إلى "محفظة Google"

بعد التأكّد من توفّر Google Wallet API وإنشاء رمز JWT موقَّع، يمكنك أن تطلب من المستخدم إضافة البطاقة إلى محفظته. في هذه الخطوة، ستضيف أداة معالجة إلى الزر الإضافة إلى "محفظة Google" الذي يستخدم Google Wallet API لحفظ البطاقة في محفظة المستخدم.

افتح ملف app/src/main/CheckoutActivity.kt

استبدِل قيمة token برمز JWT الذي أنشأته سابقًا

// TODO: Save the JWT from the backend "response"
private val token = "TOKEN"

إنشاء سمة صف لتخزين رمز الطلب

// TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000

ضبط أداة معالجة لزر الإضافة إلى "محفظة Google"

// TODO: Set an on-click listener on the "Add to Google Wallet" button
addToGoogleWalletButton = layout.addToGoogleWalletButton.root

addToGoogleWalletButton.setOnClickListener {
  walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
}

عندما ينقر المستخدم على الزر الإضافة إلى "محفظة Google"، يتم استدعاء الطريقة walletClient.savePassesJwt. تطلب هذه الطريقة من المستخدم إضافة عنصر البطاقة الجديد إلى "محفظة Google".

9- التعامل مع نتيجة savePassesJwt

في الخطوة الأخيرة من هذا الدرس العملي، ستضبط تطبيقك للتعامل مع نتيجة عملية walletClient.savePassesJwt.

افتح ملف app/src/main/CheckoutActivity.kt

تجاوز طريقة onActivityResult لتضمين الرمز التالي

// TODO: Handle the result
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

  if (requestCode == addToGoogleWalletRequestCode) {
    when (resultCode) {
      RESULT_OK -> {
        // Pass saved successfully. Consider informing the user.
      }

      RESULT_CANCELED -> {
        // Save canceled
      }

      PayClient.SavePassesResult.SAVE_ERROR ->
        data?.let { intentData ->
          val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
          // Handle error. Consider informing the user.
          Log.e("SavePassesResult", errorMessage.toString())
        }

      else -> {
        // Handle unexpected (non-API) exception
      }
    }
  }
}

يمكن لتطبيقك الآن التعامل مع الحالات التالية:

إضافة البطاقة بنجاح
إلغاء المستخدم
أخطاء غير متوقّعة

شغِّل تطبيقك للتأكّد من إمكانية إضافة البطاقة والتعامل مع النتيجة على النحو المتوقّع.

10. تهانينا

مثال على عنصر بطاقة عامة

تهانينا، لقد نجحت في دمج Google Wallet API على Android.

مزيد من المعلومات

يمكنك الاطّلاع على عملية الدمج الكاملة في مستودع google-pay/wallet-android-codelab على GitHub.

إنشاء بطاقات وطلب الحصول على إذن إصدار

عندما تصبح جاهزًا لإصدار بطاقاتك الخاصة في الإصدار العلني، انتقِل إلى Google Pay & Wallet Console لطلب إذن بالوصول إلى الإصدار العلني وتفويض تطبيق Android.

يمكنك الاطّلاع على المتطلبات الأساسية لحزمة تطوير البرامج (SDK) لنظام التشغيل Android لمعرفة المزيد.