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

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

1. مقدمة

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

في هذا الدليل التعليمي حول الرموز البرمجية، عليك إكمال المهام التالية.

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

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

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

الأهداف

بعد إكمال هذا الدليل التعليمي حول الرموز البرمجية، ستتمكّن من تنفيذ ما يلي:

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

الدعم

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

2. ضبط إعدادات الجهاز

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

يجب توفّر حساب مُصدِر لإنشاء البطاقات وتوزيعها في "محفظة Google". يمكنك الاشتراك باستخدام 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، افتح حسابات الخدمة.
إدخال اسم وتعريف ووصف لحساب الخدمة
انقر على إنشاء ومتابعة.
انقر على تم.

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

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

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

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

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

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

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

أخيرًا، عليك تفويض حساب الخدمة لإدارة البطاقات في "محفظة Google".

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

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

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

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

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

استنسِخ مستودع GitHub google-pay/wallet-android-codelab إلى محطة العمل المحلية.
```
git clone https://github.com/google-pay/wallet-android-codelab.git
```
افتح المستودع المُنشئ في المحطة الطرفية أو موجه سطر الأوامر.
انتقِل إلى الدليل backend (تُقلِّد النصوص البرمجية هذه إجراءات خادم الخلفية).
```
cd backend
```
تثبيت تبعيات Node.js
```
npm install .
```
في الدليل backend، افتح generic_class.js.
استبدِل قيمة issuerId بمعرّف جهة الإصدار من وحدة تحكّم Google Pay و"محفظة Google".
```
// 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"

احفظ الملف.
اختَر ملف، ثم مزامنة المشروع مع ملفات Gradle.

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" في بلد المستخدم.

في هذه الخطوة، ستضيف منطقًا إلى تطبيقك للتحقّق مما إذا كانت 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) وواجهة برمجة التطبيقات في "محفظة Google" متوفّرَين على الجهاز، وعالج النتيجة.

// 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 موقَّع. وهذا الإجراء هو الأنسب للحالات التي يكون فيها استخدام المستخدمين مرتفعًا، لأنّه يضمن توفّر العنصر قبل أن يحاول المستخدم إضافته إلى محفظته.

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

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

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

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

في بيئة الإنتاج، سيكون نظام الخلفية مسؤولاً عن إنشاء ملفات 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.

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.

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

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

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

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

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