این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

با استفاده از Google Wallet API در Android مجوز ایجاد کنید

1. معرفی

بررسی اجمالی

Google Wallet API به شما امکان می‌دهد از طریق انواع مختلف گذر با کاربران تعامل داشته باشید: کارت‌های وفاداری، پیشنهادات، کارت‌های هدیه، بلیط‌های رویداد، بلیط‌های حمل‌ونقل، کارت‌های پرواز و غیره. هر نوع پاس، یا کلاس پاس، دارای فیلدها و ویژگی‌های خاص مورد استفاده برای بهبود تجربه کاربر است.

با این حال، اینها ممکن است برای هر موردی مناسب نباشند. برای ایجاد یک تجربه سفارشی تر، می توانید از نوع پاس عمومی استفاده کنید. در اینجا چند نمونه از موارد استفاده برای نوع پاس عمومی آورده شده است:

کارت های پارکینگ
کارت عضویت کتابخانه
کوپن های ارزش ذخیره شده
کارت عضویت در باشگاه
رزرواسیون

می‌توانید از مجوزهای عمومی برای هر موردی که می‌توان با آن ارائه کرد استفاده کنید:

حداکثر سه ردیف اطلاعات
(اختیاری) گرافیک بارکد
(اختیاری) بخش جزئیات

یک دستگاه مجهز به Android که جریان تدارکات افزودن به Google Wallet را نشان می‌دهد

برای اطلاعات بیشتر در مورد Google Wallet API یا افزودن دکمه افزودن به Google Wallet به برنامه Android، لطفاً به مستندات برنامه‌نویس Google Wallet مراجعه کنید.

کلاس ها و اشیاء را پاس کنید

Google Wallet API روش‌هایی را برای ایجاد موارد زیر نشان می‌دهد:

تایپ کنید	شرح
گذراندن کلاس	یک الگو برای یک شی گذر فردی. این شامل اطلاعات مشترک برای تمام اشیاء عبور متعلق به این کلاس است.
عبور شی	نمونه ای از یک کلاس عبور که منحصر به یک شناسه کاربر است.

درباره این کد لبه

در این کد لبه کارهای زیر را انجام خواهید داد.

یک حساب صادرکننده جدید در حالت نمایشی ایجاد کنید
یک حساب خدماتی برای صدور مجوز ایجاد کنید
یک کلاس پاس عمومی جدید ایجاد کنید
یک شی pass جدید ایجاد کنید
برای ذخیره گذرنامه یک دکمه افزودن به کیف پول Google ایجاد کنید
دکمه را در برنامه اندروید خود نمایش دهید
نتیجه ذخیره پاس را مدیریت کنید

پیش نیازها

اندروید استودیو
Git
یک حساب Google با دسترسی به کنسول Google Cloud
Node.js نسخه 10 یا بالاتر

اهداف

پس از تکمیل این کد لبه، می توانید کارهای زیر را انجام دهید:

Google Wallet SDK را به برنامه Android خود اضافه کنید
بررسی کنید که آیا Google Wallet API در دستگاه مجهز به Android موجود است یا خیر
یک دکمه افزودن به کیف پول Google ایجاد کنید

حمایت کردن

اگر در هر نقطه ای از Codelab گیر کرده اید، مخزن google-pay/wallet-android-codelab GitHub حاوی یک راه حل کامل برای مرجع است.

2. راه اندازی

در این مرحله یک حساب صادر کننده در حالت نمایشی ایجاد می کنید. این به شما امکان می دهد کلاس ها و اشیایی را ایجاد کنید که می توانند به کیف پول کاربران اضافه شوند. در مرحله بعد، یک پروژه و حساب سرویس Google Cloud ایجاد خواهید کرد. اینها برای ایجاد برنامه‌نویسی کلاس‌ها و اشیاء عبور به همان روشی که یک سرور پشتیبان است استفاده می‌شود. در آخر، به حساب سرویس Google Cloud اجازه می‌دهید تا مجوزهای حساب صادرکننده Google Wallet خود را مدیریت کند.

یک حساب صادرکننده برای ایجاد و توزیع مجوز برای Google Wallet ضروری است. می توانید با استفاده از Google Pay & Wallet Console ثبت نام کنید. در ابتدا، به ایجاد پاس در حالت نمایشی دسترسی خواهید داشت. این به این معنی است که فقط کاربران آزمایشی خاص می‌توانند پاس‌هایی را که ایجاد می‌کنید اضافه کنند. کاربران آزمایشی را می‌توان در Google Pay & Wallet Console مدیریت کرد.

برای اطلاعات بیشتر در مورد حالت نمایشی، پیش نیازهای مجوز عمومی را ببینید.

Google Pay & Wallet Console را باز کنید
دستورالعمل های روی صفحه را برای ایجاد یک حساب صادرکننده دنبال کنید
Google Wallet API را انتخاب کنید
تأیید کنید که شرایط خدمات و خط مشی رازداری را درک می کنید
مقدار شناسه صادرکننده را در یک ویرایشگر متن یا مکان دیگری کپی کنید
در تب Manage ، Set up test accounts را انتخاب کنید
هر آدرس ایمیلی را که در این لبه کد استفاده می کنید اضافه کنید

Google Wallet API را فعال کنید

وارد کنسول Google Cloud شوید
اگر قبلاً پروژه Google Cloud ندارید، اکنون یک پروژه ایجاد کنید (برای اطلاعات بیشتر به ایجاد و مدیریت پروژه‌ها مراجعه کنید)
Google Wallet API (که به آن Google Pay for Passes API نیز گفته می شود) را برای پروژه خود فعال کنید

یک حساب سرویس و کلید ایجاد کنید

یک حساب سرویس و یک کلید حساب سرویس برای تماس با Google Wallet API ضروری است. حساب سرویس هویتی است که Google Wallet API را فراخوانی می کند. کلید حساب سرویس حاوی یک کلید خصوصی است که برنامه شما را به عنوان حساب سرویس شناسایی می کند. این کلید حساس است، بنابراین آن را محرمانه نگه دارید.

یک حساب کاربری ایجاد کنید

در کنسول Google Cloud، حساب‌های سرویس را باز کنید
نام، شناسه و توضیحات حساب سرویس خود را وارد کنید
ایجاد و ادامه را انتخاب کنید
انجام شد را انتخاب کنید

یک کلید حساب کاربری ایجاد کنید

حساب سرویس خود را انتخاب کنید
منوی KEYS را انتخاب کنید
ADD KEY و سپس Create new key را انتخاب کنید
نوع کلید JSON را انتخاب کنید
CREATE را انتخاب کنید

از شما خواسته می شود که فایل کلید را در ایستگاه کاری محلی خود ذخیره کنید. حتما مکان آن را به خاطر بسپارید.

متغیر محیطی `GOOGLE_APPLICATION_CREDENTIALS` را تنظیم کنید

متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS توسط Google SDK برای احراز هویت به عنوان یک حساب سرویس و دسترسی به API های مختلف برای پروژه Google Cloud استفاده می شود.

برای تنظیم متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS ، دستورالعمل‌های موجود در اسناد کلیدهای حساب Google Cloud Service را دنبال کنید.
بررسی کنید که متغیر محیط در یک جلسه ترمینال جدید (MacOS/Linux) یا خط فرمان (ویندوز) تنظیم شده باشد (اگر قبلاً یک جلسه باز دارید، ممکن است لازم باشد جلسه جدیدی را شروع کنید)
```
echo $GOOGLE_APPLICATION_CREDENTIALS
```

مجوز حساب سرویس

در نهایت، باید حساب سرویس را برای مدیریت مجوزهای Google Wallet مجاز کنید.

Google Pay & Wallet Console را باز کنید
کاربران را انتخاب کنید
دعوت از کاربر را انتخاب کنید
آدرس ایمیل حساب سرویس را وارد کنید (به عنوان مثال test-svc@myproject.iam.gserviceaccount.com )
از منوی کشویی سطح دسترسی، Developer یا Admin را انتخاب کنید
Invite را انتخاب کنید

3. یک کلاس Generic pass ایجاد کنید

در این مرحله کلاس پایه را برای پاس خود ایجاد می کنید. هر زمان که یک پاس جدید برای یک کاربر ایجاد شود، ویژگی های تعریف شده در کلاس pass را به ارث می برد.

کلاس عبوری که در طول این کد لبه ایجاد خواهید کرد از انعطاف پذیری پاس های عمومی برای ایجاد یک شی استفاده می کند که هم به عنوان نشان هویت و هم به عنوان ردیاب نقاط چالش عمل می کند. هنگامی که یک شی pass از این کلاس ایجاد می شود، مانند تصویر زیر به نظر می رسد.

کلاس‌های Pass را می‌توان مستقیماً در Google Pay & Wallet Console یا با استفاده از Google Wallet API ایجاد کرد. در این لبه کد، کلاس Generic pass را با استفاده از API ایجاد خواهید کرد. این فرآیندی را دنبال می‌کند که یک سرور خصوصی و باطن از آن برای ایجاد کلاس‌های عبور استفاده می‌کند.

مخزن google-pay/wallet-android-codelab GitHub را در ایستگاه کاری محلی خود
```
git clone https://github.com/google-pay/wallet-android-codelab.git
```
کلون کنید
مخزن کلون شده را در ترمینال یا خط فرمان خود باز کنید
به دایرکتوری backend بروید (این اسکریپت ها از اقدامات سرور باطن تقلید می کنند)
```
cd backend
```
وابستگی های Node.js
```
npm install .
```
را نصب کنید
در دایرکتوری backend ، generic_class.js باز کنید
شناسه صادرکننده خود را از Google Pay & Wallet Console
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
جایگزین مقدار issuerId کنید
در خط فرمان یا ترمینال خود، اسکریپت generic_class.js
```
node generic_class.js
```
را اجرا کنید.

وقتی کد شما اجرا می شود، یک کلاس پاس جدید ایجاد می کند و شناسه کلاس را خروجی می کند. شناسه کلاس از شناسه صادرکننده و پسوندی تعریف شده توسط توسعه دهنده تشکیل شده است. در این مورد، پسوند روی codelab_class تنظیم می شود (شناسه کلاس شبیه به 1234123412341234123.codelab_class است). گزارش‌های خروجی همچنین شامل پاسخ از Google Wallet API خواهند بود.

4. پروژه را در اندروید استودیو باز کنید

مخزن GitHub که کلون کردید حاوی یک پروژه اندروید با یک فعالیت خالی است. در این مرحله، در این فعالیت ویرایش می‌کنید تا دکمه افزودن به Google Wallet را در صفحه محصول اضافه کنید.

اندروید استودیو را باز کنید
File و سپس Open را انتخاب کنید
دایرکتوری android را در مخزن انتخاب کنید
Open را انتخاب کنید

Google Wallet SDK را به برنامه خود اضافه کنید

فایل ساخت Gradle در سطح ماژول را باز کنید ( android/app/build.gradle )

Google Wallet SDK را به بخش 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 و سپس Sync Project با Gradle Files را انتخاب کنید

5. دکمه Add to Google Wallet را ایجاد کنید

در این مرحله یک دکمه افزودن به کیف پول گوگل ایجاد کرده و آن را به یک فعالیت موجود اضافه می کنید. دارایی های دکمه قبلاً در پروژه گنجانده شده است. برای قرار دادن دکمه، یک فایل طرح بندی جداگانه ایجاد می کنید. پس از اضافه شدن، دکمه به شکل زیر خواهد بود.

یک فایل طرح‌بندی جدید ایجاد کنید: 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 Wallet از سردرگمی احتمالی جلوگیری می کند. دلایل مختلفی برای در دسترس نبودن API وجود دارد، مانند قدیمی بودن نسخه Android یا Google Play Services یا در دسترس نبودن 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)

روشی ایجاد کنید که بررسی کند آیا Google Wallet SDK و API در دستگاه موجود است و نتیجه

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

مدیریت کند.

برای بررسی اینکه آیا Google Wallet API در دسترس است
```
// TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()
```
متد fetchCanUseGoogleWalletApi در متد onCreate فراخوانی کنید.

هنگامی که برنامه را اجرا می کنید، اکنون باید دکمه افزودن به کیف پول Google را در رابط کاربری مشاهده کنید.

7. یک شی گذر عمومی ایجاد کنید

اکنون که تأیید کرده‌اید که Google Wallet API در دسترس است، می‌توانید یک مجوز ایجاد کنید و از کاربر خود بخواهید آن را به کیف پول خود اضافه کند. دو جریان برای ایجاد اشیاء عبور برای کاربران وجود دارد.

شی pass را در سرور باطن ایجاد کنید

در این رویکرد، شی pass بر روی یک سرور باطن ایجاد می شود و به عنوان یک JWT امضا شده به برنامه مشتری بازگردانده می شود. این بهترین گزینه برای مواردی است که پذیرش کاربر زیاد است، زیرا اطمینان حاصل می کند که قبل از اینکه کاربر سعی کند آن را به کیف پول خود اضافه کند وجود دارد.

وقتی کاربر آن را به کیف پول خود اضافه می کند، شی pass را ایجاد کنید

در این رویکرد، شی pass تعریف شده و در یک JWT امضا شده در سرور باطن رمزگذاری می شود. سپس یک دکمه افزودن به کیف پول Google در برنامه مشتری که به JWT اشاره می کند، ارائه می شود. هنگامی که کاربر دکمه را انتخاب می کند، از JWT برای ایجاد شی عبور استفاده می شود. این بهترین گزینه برای مواردی است که پذیرش کاربر متغیر یا ناشناخته است، زیرا از ایجاد و عدم استفاده اشیاء عبور جلوگیری می کند. این رویکرد در نرم افزار Codelab استفاده خواهد شد.

فایل backend/generic_pass.js را باز کنید
شناسه صادرکننده خود را از Google Pay & Wallet Console
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
جایگزین مقدار issuerId کنید
در خط فرمان یا ترمینال خود، فایل generic_pass.js
```
node generic_pass.js
```
را اجرا کنید.
کد خروجی را در کلیپ بورد یا یک ویرایشگر متن کپی کنید

هنگامی که کد شما اجرا می شود، یک شی گذر جدید تعریف می کند و آن را در JWT جاسازی می کند. سپس JWT توسط کلید حساب سرویس که قبلا ایجاد کرده اید امضا می شود. با این کار درخواست به Google Wallet API احراز هویت می شود تا نیازی به ذخیره اعتبارنامه ها در برنامه مشتری نباشد.

در محیط تولید، سیستم باطن شما مسئول ایجاد JWT و بازگرداندن آنها به مشتریان خواهد بود. در این لبه کد، اسکریپت generic_pass.js این رفتار را شبیه‌سازی می‌کند و یک توکن را به شما برمی‌گرداند تا در برنامه مشتری استفاده کنید.

8. پاس را به Google Wallet اضافه کنید

اکنون که تأیید کرده‌اید که Google Wallet API در دسترس است و یک JWT امضا شده ایجاد کرده‌اید، می‌توانید از کاربر بخواهید پاس را به کیف پول خود اضافه کند. در این مرحله یک شنونده به دکمه افزودن به کیف پول گوگل اضافه می کنید که از API Google Wallet برای ذخیره پاس در کیف پول کاربر استفاده می کند.

فایل 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 Wallet

// 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 Wallet خود اضافه کند.

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 خود را بدهید.

برای کسب اطلاعات بیشتر ، پیش نیازهای Android SDK را ببینید.