با Google Pay یک تجربه پرداخت سریع در Android ایجاد کنید

با Google Pay یک تجربه پرداخت سریع در Android ایجاد کنید

درباره این codelab

subjectآخرین به‌روزرسانی: آوریل ۳, ۲۰۲۴
account_circleنویسنده: Jose Ugia, Stephen McDonald, Alan Blount

1. مقدمه

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

Auto T-Shirt Shop فروشگاهی نوآورانه است که از آخرین پیشرفت های هوش مصنوعی بهره می برد و با استفاده از اطلاعاتی مانند ترجیحات سبک، آب و هوا، زمان سال و روند مد، مناسب ترین کالا را برای خرید به شما پیشنهاد می کند.

معیارهای درگیری بیش از سقف هستند. متأسفانه، اعداد همچنین نشان دهنده تعداد زیادی از رها شدن در طول فرآیند پرداخت هستند. یکی از صاحبان پروژه که مصمم به مقابله با آن است، به یاد می‌آورد که ویدیویی را دیده است که نتایج امیدوارکننده‌ای را که Google Pay برای سایر سایت‌های مشابه به دست آورده است، نشان می‌دهد ، بنابراین آنها تصمیم می‌گیرند این کار را انجام دهند و به شما برای مراقبت از ادغام اعتماد کنند.

نمای کلی

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

نمونه برنامه

در این کد لبه یاد خواهید گرفت که چگونه:

  1. Google Pay را در یک برنامه اندروید موجود ادغام کنید
  2. تعیین کنید که آیا کاربر آماده پرداخت با استفاده از Google Pay است یا خیر
  3. دکمه Google Pay را به رابط کاربری خود اضافه کنید
  4. عملیات پرداخت را با Google Pay انجام دهید

پیش نیازها

  • Git
  • Android Studio یا یک محیط توسعه جایگزین برای برنامه های اندروید
  • یک دستگاه یا شبیه ساز Android با آخرین نسخه سرویس های Google Play نصب شده است

پشتیبانی کنید

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

2. شروع کنید

مخزن را از GitHub کلون کنید

از دستور زیر برای کلون کردن مخزن در یک پوشه در رایانه خود استفاده کنید:

git clone https://github.com/google-pay/android-quickstart

یا اگر یک آرشیو فشرده را ترجیح می دهید:

نمونه برنامه را مرور کنید

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

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

مخزن GitHub که شبیه سازی کردید حاوی یک پروژه اندروید با یک فعالیت اساسی است. در این مرحله، برای تأیید آمادگی Google Pay و نمایش یک دکمه Google Pay، در این فعالیت ویرایش می‌کنید.

  1. اندروید استودیو را باز کنید
  2. File و سپس Open را انتخاب کنید
  3. دایرکتوری kotlin در مخزن انتخاب کنید
  4. Open را انتخاب کنید

کتابخانه Google Pay را به عنوان یک وابستگی در فایل build.gradle خود اضافه کنید

  1. فایل ساخت Gradle در سطح ماژول را باز کنید ( kotlin/app/build.gradle.kts )
  2. کتابخانه Google Pay را به بخش dependencies اضافه کنید 
implementation "com.google.android.gms:play-services-wallet:19.3.0"
  1. فایل را ذخیره کنید
  2. File و سپس Sync Project با Gradle Files را انتخاب کنید

Google Pay API را در فایل مانیفست اندروید خود فعال کنید

در نهایت، یک عنصر meta-data را در داخل گره application فایل مانیفست خود اضافه کنید:

<meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />

4. تصمیم بگیرید که دکمه Google Pay را در کجای رابط خود قرار دهید

چیدمان و قرارگیری کلی در نماهای شما جنبه های مهمی هستند که بر میزان احتمال انجام تراکنش پرداخت توسط کاربران تأثیر می گذارند. امکان انتخاب یک روش پرداخت با چند ضربه با استفاده از Google Pay، گزینه‌های جدیدی را در مورد مکان و زمان ارائه راهی برای پرداخت در برنامه شما به کاربران فعال می‌کند. به عنوان مثال، می‌توانید گزینه‌های تسویه‌حساب سریع را در مراحل اولیه، در مناطقی مانند نمای جزئیات یک مورد، اضافه کنید تا به کاربران اجازه دهید به سرعت برای یک کالای مورد علاقه خود پرداخت کنند.

هنگامی که تصمیم گرفتید چگونه رابط کاربری خود را مرتب کنید، گام بعدی قرار دادن دکمه Google Pay است. می توانید برخی از ویژگی های بصری دکمه مانند نوع، موضوع و گرد بودن گوشه را پیکربندی کنید. در اینجا چند نمونه آورده شده است:

مثال دکمه های پویا Google Pay

کتابخانه Google Pay شامل یک نمای ساده برای افزودن دکمه به رابط کاربری شما است. اگر طرح‌بندی‌های خود را با استفاده از XML می‌سازید، چگونه این کار را انجام می‌دهید:

<com.google.android.gms.wallet.button.PayButton
    android:id="@+id/googlePayButton"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

بعداً دکمه را از نظر برنامه‌ریزی مقداردهی اولیه می‌کنید (به مثال مراجعه کنید).
اگر از Jetpack Compose استفاده می کنید، آخرین نسخه وابستگی زیر را در فایل build.gradle یا build.gradle.kts خود قرار دهید:

implementation "com.google.pay.button:compose-pay-button:1.0.0"

و دکمه Google Pay را به طرح‌بندی نوشتن خود اضافه کنید:

PayButton(
    modifier = Modifier
        .testTag("payButton")
        .fillMaxWidth(),
    onClick = onGooglePayButtonClick,
    allowedPaymentMethods = PaymentsUtil.allowedPaymentMethods.toString()
)

برای کسب اطلاعات بیشتر در مورد نحوه ساخت لیست روش های پرداخت پذیرفته شده ، نمونه را در GitHub بررسی کنید.

5. API Google Pay را راه‌اندازی و پیکربندی کنید

کلاینت API را نمونه سازی کنید

برای شروع استفاده از API، باید یک شی کلاینت را نمونه‌سازی کنید، که از آن برای برقراری تماس با Google Pay API استفاده می‌کنید. به محض ایجاد فعالیت یا کنترلر می توانید این کار را انجام دهید:

private val paymentsClient: PaymentsClient = createPaymentsClient(context)

fun createPaymentsClient(context: Context): PaymentsClient {
    val walletOptions = Wallet.WalletOptions.Builder()
            .setEnvironment(WalletConstants.ENVIRONMENT_TEST).build()
    return Wallet.getPaymentsClient(context, walletOptions)
}

مشتری پرداخت با یک شی WalletOptions مقداردهی اولیه می شود. تنظیم محیط روی ENVIRONMENT_TEST به شما امکان می دهد اطلاعات پرداخت آزمایشی را آزمایش کنید. هنگامی که برای صدور تراکنش‌های پرداخت واقعی آماده شدید، می‌توانید ویژگی محیط را به ENVIRONMENT_PRODUCTION به‌روزرسانی کنید.

آناتومی درخواست Google Pay

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

{
    apiVersion: number,
    apiVersionMinor: number,
    allowedPaymentMethods: Array
}

ویژگی allowedPaymentMethods فهرستی از روش‌های پرداخت را می‌گیرد. برای هر روش پرداخت باید ویژگی های زیر را در نظر بگیرید:

{
    type: 'CARD',
    parameters: {
        allowedCardNetworks: Array.<string>,
        allowedAuthMethods: Array.<string>
    }
}

پیکربندی روش پرداخت

برای اهداف این مثال، شما فقط می‌خواهید پرداخت‌های کارتی برای Mastercard و Visa را هم به صورت رمزگذاری شده و هم به صورت شماره حساب اصلی ( PAN ) بپذیرید. روش پرداخت شما به این صورت است: 

private val baseCardPaymentMethod =
    JSONObject()
        .put("type", "CARD")
        .put("parameters", JSONObject()
            .put("allowedCardNetworks", JSONArray(listOf("VISA", "MASTERCARD")))
            .put("allowedAuthMethods", JSONArray(listOf("PAN_ONLY", "CRYPTOGRAM_3DS")))
        )

همه را کنار هم گذاشتن

بیایید خلاصه کنیم. شما یک روش پرداخت را برای پذیرفته شدن در برنامه خود تعریف کرده اید و قرار است با نسخه 2.0 API کار کنید. این چیزی است که پیکربندی حاصل به نظر می رسد: 

private val baseCardPaymentMethod = JSONObject()
    .put("type", "CARD")
    .put("parameters", JSONObject()
        .put("allowedCardNetworks", JSONArray(listOf("VISA", "MASTERCARD")))
        .put("allowedAuthMethods", JSONArray(listOf("PAN_ONLY", "CRYPTOGRAM_3DS")))
    )

private val googlePayBaseConfiguration = JSONObject()
    .put("apiVersion", 2)
    .put("apiVersionMinor", 0)
    .put("allowedPaymentMethods",  JSONArray(listOf(baseCardPaymentMethod)))
}

6. آمادگی برای پرداخت با Google Pay را تعیین کنید

استفاده از درخواست isReadyToPay به شما امکان می دهد تعیین کنید که آیا کاربر در برنامه شما قادر به پرداخت با Google Pay است یا خیر. از این اطلاعات برای تنظیم تجربه کاربری در برنامه خود استفاده کنید.

این درخواست از شما می‌خواهد که نسخه Google Pay API و فهرست روش‌های پرداخت مجاز را در برنامه خود مشخص کنید. این دقیقاً همان چیزی است که شیء پیکربندی پایه تعریف شده در مرحله قبل شامل می شود: 

private suspend fun fetchCanUseGooglePay(): Boolean {
    val request = IsReadyToPayRequest.fromJson(googlePayBaseConfiguration.toString())
    return paymentsClient.isReadyToPay(request).await()
}

API Google Pay از Task s برای حل تماس های راه دور استفاده می کند. Tasks API به شما امکان می دهد تا عملیات Task با استفاده از برنامه های معمول حل کنید. بیشتر بدانید

همانطور که می بینید، بررسی آمادگی برای پرداخت با Google Pay یک شی بولی را برمی گرداند. اگر نتیجه مثبت بود، مرحله بعدی نشان دادن دکمه Google Pay در رابط کاربری است. در غیر این صورت، در نظر بگیرید که رابط کاربری دیگری را نشان دهید که از سایر روش‌های پرداخت پشتیبانی می‌کند.

نمایش دکمه Google Pay

اکنون به رابط کاربری خود برگردید و محل قرارگیری دکمه Google Pay را بر اساس نتیجه تماس قبلی به‌روزرسانی کنید. این مثال از یک کلاس برای نگهداری وضعیت نمای استفاده می کند که بر اساس ورودی مانند فراخوانی به isReadyToPay به روز می شود. 

if (payUiState !is PaymentUiState.NotStarted) {
    PayButton(
        modifier = Modifier
            .testTag("payButton")
            .fillMaxWidth(),
        onClick = onGooglePayButtonClick,
        allowedPaymentMethods = PaymentsUtil.allowedPaymentMethods.toString()
    )
}

7. زمان پرداخت است!

### درخواست پرداخت را آماده کنید

در این مرحله، API Google Pay را بارگیری کرده‌اید و تشخیص داده‌اید که کاربر در برنامه شما می‌تواند از Google Pay برای پرداخت استفاده کند. در نتیجه، دکمه پرداخت Google Pay را در رابط کاربری نشان داده اید و اکنون کاربر شما آماده است تا تراکنش را آغاز کند. اکنون زمان بارگیری برگه پرداخت با فرم های پرداخت موجود برای کاربر است.

مشابه فراخوانی به isReadyToPay ، این درخواست به ویژگی‌های موجود در شیء پیکربندی پایه که قبلاً تعریف شده است ( apiVersion ، apiVersionMinor و allowedPaymentMethods ) نیاز دارد. این بار، شما همچنین به یک ویژگی جدید به نام tokenizationSpecification و پارامترهای اضافی برای توصیف تراکنش و درخواست اطلاعاتی مانند آدرس صورتحساب و حمل و نقل یا آدرس ایمیل یا شماره تلفن کاربران نیاز دارید.

#### خاصیت tokenizationSpecification

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

دو نوع مختلف از مکانیسم های جابجایی پشتیبانی می شود. اگر تراکنش پرداخت را از داخل سرورهای سازگار PCI DSS خود پردازش می کنید، از نوع مشخصات DIRECT استفاده کنید. در این مثال، شما از یک درگاه پرداخت برای پردازش پرداخت استفاده می‌کنید، بنابراین، نوع مشخصات PAYMENT_GATEWAY را تنظیم می‌کنید: 

private val tokenizationSpecification = JSONObject()
    .put("type", "PAYMENT_GATEWAY")
    .put("parameters", JSONObject(mapOf(
            "gateway" to "example",
            "gatewayMerchantId" to "exampleGatewayMerchantId")))
}

در بخش parameters ، می‌توانید دروازه‌ای را از فهرست ارائه‌دهندگان پشتیبانی شده توسط Google Pay API به همراه پیکربندی اضافی مورد نیاز هر دروازه مشخص کنید. برای اهداف این آزمایشگاه، از دروازه example استفاده خواهید کرد که نتایج آزمایش تراکنش های انجام شده را برمی گرداند.

پارامترهای اضافی

به همین ترتیب، برای ثبت سفارش با موفقیت می توانید جزئیات بیشتری را از کاربر خود درخواست کنید. ببینید چگونه در این مثال، ویژگی‌های billingAddressRequired و billingAddressParameters را اضافه می‌کنید تا نشان دهید که برای این تراکنش، آدرس صورت‌حساب کاربر در قالب کامل و شامل شماره تلفن مورد نیاز است: 

private val cardPaymentMethod = JSONObject()
    .put("type", "CARD")
    .put("tokenizationSpecification", tokenizationSpecification)
    .put("parameters", JSONObject()
        .put("allowedCardNetworks", JSONArray(listOf("VISA", "MASTERCARD")))
        .put("allowedAuthMethods", JSONArray(listOf("PAN_ONLY", "CRYPTOGRAM_3DS")))
        .put("billingAddressRequired", true)
        .put("billingAddressParameters", JSONObject(mapOf("format" to "FULL")))
    )

#### شامل اطلاعات اضافی در مورد معامله

ویژگی transactionInfo شامل یک شی با جزئیات مالی درباره تراکنش، یعنی قیمت و کد ارز (فرمت آلفا ISO 4217 ) به همراه وضعیت قیمت است که بسته به ماهیت تراکنش می‌تواند نهایی یا تخمین زده شود (به عنوان مثال. : قیمت ممکن است بسته به آدرس حمل و نقل مشخص شده متفاوت باشد): 

private val transactionInfo = JSONObject()
    .put("totalPrice", "123.45")
    .put("totalPriceStatus", "FINAL")
    .put("currencyCode", "USD")
}

#### اضافه کردن اطلاعات کسب و کار شما

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

  • merchantId شناسه مرتبط با حساب شما را نگه می دارد. می‌توانید شناسه فروشنده خود را در کنسول پرداخت و کیف پول دریافت کنید. توجه داشته باشید که این فیلد هنگام استفاده از محیط TEST ارزیابی نمی شود.
  • merchantName نام قابل مشاهده کاربر برنامه یا سازمان شما است. این ممکن است در داخل برگه پرداخت Google Pay نشان داده شود تا به کاربران زمینه بیشتری درباره درخواست کننده عملیات ارائه دهد.

پس از آماده شدن، به سادگی اطلاعات مربوط به تاجر را به شی paymentDataRequest اضافه کنید: 

private val merchantInfo = JSONObject()
    .put("merchantName", "Example Merchant")
    .put("merchantId", "01234567890123456789")

درخواست را صادر کنید و نتیجه را پردازش کنید

اکنون، شیء پیکربندی را کنار هم بیاورید و آن را به درخواست loadPaymentData ارسال کنید: 

private val paymentDataRequestJson = JSONObject(googlePayBaseConfiguration.toString())
    .put("allowedPaymentMethods", JSONArray().put(cardPaymentMethod))
    .put("transactionInfo", transactionInfo)
    .put("merchantInfo", merchantInfo)

در این مرحله، همه چیزهایی را که برای درخواست از Google Pay API نیاز دارید، دارید. برای انجام این کار، از متد loadPaymentData در آبجکت PaymentsClient استفاده کنید و پیکربندی را که به تازگی تعریف کرده اید منتقل کنید: 

fun getLoadPaymentDataTask(): Task<PaymentData> {
    val request = PaymentDataRequest.fromJson(paymentDataRequestJson.toString())
    return paymentsClient.loadPaymentData(request)
}

private fun requestPayment() {
    val task = getLoadPaymentDataTask()
    task.addOnCompleteListener(paymentDataLauncher::launch)
}

Google Pay API از Activity Result API برای برگرداندن نتیجه استفاده می‌کند. API شامل قراردادهایی برای ساده سازی پردازش و واکنش به نتیجه است. این مثال از قرارداد GetPaymentDataResult استفاده می‌کند که شامل اطلاعات مربوط به عملیات علاوه بر نتیجه پرداخت است: 

private val paymentDataLauncher = registerForActivityResult(GetPaymentDataResult()) { taskResult ->
    when (taskResult.status.statusCode) {
        CommonStatusCodes.SUCCESS -> {
            taskResult.result!!.let {
                Log.i("Google Pay result:", it.toJson())
                // TODO something with the result
            }
        }
        CommonStatusCodes.CANCELED -> // The user canceled
        AutoResolveHelper.RESULT_ERROR -> // The API returned an error (it.status: Status)
        CommonStatusCodes.INTERNAL_ERROR -> // Handle other unexpected errors
    }
}

فراخوانی این روش، ارائه برگه پرداخت Google Pay را فعال می کند. اگر هیچ خطایی در پیکربندی وجود نداشته باشد، می‌توانید فهرستی از روش‌های پرداخت معتبر مرتبط با حساب کاربری که در حال حاضر وارد شده‌اید را مشاهده کنید.

پس از انتخاب، برگه بسته می‌شود و نتیجه به فعالیت شما بازگردانده می‌شود و توسط راه‌انداز نتیجه فعالیت تعریف‌شده در بالا ضبط می‌شود.

اگر انتخاب موفقیت آمیز باشد، نتیجه با یک شی PaymentData که شامل اطلاعات مرتبط در مورد روش پرداخت انتخاب شده است، برگردانده می شود: 

{
  "apiVersionMinor": 0,
  "apiVersion": 2,
  "paymentMethodData": {
    "description": "Visa •••• 1234",
    "tokenizationData": {
      "type": "PAYMENT_GATEWAY",
      "token": "examplePaymentMethodToken"
    },
    "type": "CARD",
    "info": {
      "cardNetwork": "VISA",
      "cardDetails": "1234",
      "billingAddress": {
        "phoneNumber": ...,
        ...
      }
    }
  }
}

اکنون می توانید از این روش پرداخت برای تکمیل تراکنش با درگاه پرداخت خود استفاده کنید: 

private fun handlePaymentSuccess(paymentData: PaymentData) {
    val paymentMethodToken = paymentData
            .getJSONObject("tokenizationData")
            .getString("token")

    // Sample TODO: Use this token to perform a payment through your payment gateway
}

8. تبریک می گویم!

شما با موفقیت Google Pay را به یک برنامه Android اضافه کردید.

### مراحل بعدی

### بیشتر بدانید

آیا این را مفید یافتید؟

bug_report گزارش اشتباه