درباره این codelab
1. مقدمه
نمای کلی
Google Wallet API به شما امکان میدهد از طریق انواع مختلف گذر با کاربران تعامل داشته باشید: کارتهای وفاداری، پیشنهادات، کارتهای هدیه، بلیطهای رویداد، بلیطهای حملونقل، کارتهای پرواز و غیره. هر نوع پاس، یا کلاس پاس، دارای فیلدها و ویژگیهای خاص مورد استفاده برای بهبود تجربه کاربر است.
با این حال، اینها ممکن است برای هر موردی مناسب نباشند. برای ایجاد یک تجربه سفارشی تر، می توانید از نوع پاس عمومی استفاده کنید. در اینجا چند نمونه از موارد استفاده برای نوع پاس عمومی آورده شده است:
- کارت های پارکینگ
- کارت عضویت کتابخانه
- کوپن های ارزش ذخیره شده
- کارت عضویت در باشگاه
- رزرواسیون
میتوانید از مجوزهای عمومی برای هر موردی که میتوان با آن ارائه کرد استفاده کنید:
- حداکثر سه ردیف اطلاعات
- (اختیاری) گرافیک بارکد
- (اختیاری) بخش جزئیات
برای اطلاعات بیشتر در مورد 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 API ثبت نام کنید
یک حساب صادرکننده برای ایجاد و توزیع مجوز برای 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. یک کلاس پاس عمومی ایجاد کنید
در این مرحله کلاس پایه را برای پاس خود ایجاد می کنید. هر زمان که یک پاس جدید برای یک کاربر ایجاد شود، ویژگی های تعریف شده در کلاس 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 جایگزین مقدار
issuerId
کنید// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID'; - در خط فرمان یا ترمینال خود، اسکریپت
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 در دسترس است یا خیر، متد
fetchCanUseGoogleWalletApi
را در متدonCreate
فراخوانی کنید.// TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()
هنگامی که برنامه را اجرا می کنید، اکنون باید دکمه افزودن به کیف پول Google را در رابط کاربری مشاهده کنید.
7. یک شیء پاس عمومی ایجاد کنید
اکنون که تأیید کردهاید که Google Wallet API در دسترس است، میتوانید یک مجوز ایجاد کنید و از کاربر خود بخواهید آن را به کیف پول خود اضافه کند. دو جریان برای ایجاد اشیاء عبور برای کاربران وجود دارد.
شی pass را در سرور باطن ایجاد کنید
در این رویکرد، شی pass بر روی یک سرور باطن ایجاد می شود و به عنوان یک JWT امضا شده به برنامه مشتری بازگردانده می شود. این بهترین گزینه برای مواردی است که پذیرش کاربر زیاد است، زیرا اطمینان حاصل می کند که قبل از اینکه کاربر سعی کند آن را به کیف پول خود اضافه کند وجود دارد.
وقتی کاربر آن را به کیف پول خود اضافه می کند، شی pass را ایجاد کنید
در این رویکرد، شی pass تعریف شده و در یک JWT امضا شده در سرور باطن رمزگذاری می شود. سپس یک دکمه افزودن به کیف پول Google در برنامه مشتری که به JWT اشاره می کند، ارائه می شود. هنگامی که کاربر دکمه را انتخاب می کند، از JWT برای ایجاد شی عبور استفاده می شود. این بهترین گزینه برای مواردی است که پذیرش کاربر متغیر یا ناشناخته است، زیرا از ایجاد و عدم استفاده اشیاء عبور جلوگیری می کند. این رویکرد در نرم افزار Codelab استفاده خواهد شد.
- فایل
backend/generic_pass.js
را باز کنید - شناسه صادرکننده خود را از Google Pay & Wallet Console جایگزین مقدار
issuerId
کنید// 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 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 تنظیم کنید
// 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 را ببینید.