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

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

1. مقدمة

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الأهداف

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

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

الدعم

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

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

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

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

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

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

تفعيل Google Wallet API

سجِّل الدخول إلى وحدة تحكُّم Google Cloud
إذا لم يكن لديك مشروع على Google Cloud، يمكنك إنشاء مشروع الآن (راجِع إنشاء المشاريع وإدارتها للحصول على مزيد من المعلومات).
تفعيل Google Wallet API (يُشار إليها أيضًا باسم Google Pay for Cards 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 وحدة تحكُّم المحفظة
اختيار المستخدمون
اختَر دعوة مستخدم.
أدخِل عنوان البريد الإلكتروني لحساب الخدمة (مثل 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
```
افتح المستودع المنسوخ في الوحدة الطرفية أو موجه سطر الأوامر.
انتقِل إلى دليل backend (تحاكي هذه النصوص البرمجية إجراءات خادم الخلفية)
```
cd backend
```
تثبيت تبعيات Node.js
```
npm install .
```
في دليل backend، افتح generic_class.js.
يُرجى استبدال قيمة issuerId برقم تعريف جهة الإصدار من Google Pay. وحدة التحكم في المحفظة
```
// 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. وحدة التحكم في المحفظة
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
في الوحدة الطرفية أو سطر الأوامر، شغِّل ملف generic_pass.js
```
node generic_pass.js
```
.
نسخ الرمز المميّز للإخراج إلى الحافظة أو محرِّر نصوص

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

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