‫Google Pay API for Flutter على Android

1. مقدمة

ما ستنشئه

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

أهداف الدورة التعليمية

• كيفية تثبيت مكتبة Google Pay Flutter وإعدادها
• كيفية عرض زر Google Pay والتعامل مع النقرات
• كيفية طلب رمز مميّز للدفع من Google Pay

المتطلبات

• محرّر نصوص من اختيارك لتعديل ملفات Dart
• بيئة تطوير Flutter تم إعدادها لنظام التشغيل Android
• بالنسبة إلى بيئة الإنتاج، ستحتاج إلى merchantId في Google Pay. لا يستغرق التسجيل في Google Pay & Wallet Console سوى دقيقة واحدة، لذا ننصحك بإكمال هذه الخطوة الآن.

2. إنشاء مشروع Flutter

إنشاء ملفات المشروع

1. أنشئ مشروع Flutter جديدًا باسم googlepay_flutter.

   flutter create googlepay_flutter
   

2. ثبِّت مكتبة Google Pay Flutter.

   cd googlepay_flutter
   flutter pub add pay
   

3. افتح lib/main.dart في بيئة التطوير المتكاملة التي تختارها واستبدِل المحتوى بالرمز التالي:

   import 'package:flutter/material.dart';
   
   void main() => runApp(const MyApp());
   
   class MyApp extends StatelessWidget {
     const MyApp({super.key});
   
     @override
     Widget build(BuildContext context) {
       return const MaterialApp(
         home: PaySampleApp(),
       );
     }
   }
   
   class PaySampleApp extends StatefulWidget {
     const PaySampleApp({super.key});
   
     @override
     State<PaySampleApp> createState() => _PaySampleAppState();
   }
   
   class _PaySampleAppState extends State<PaySampleApp> {
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         appBar: AppBar(
           title: const Text('Google Pay Codelab'),
         ),
         body: Center(
           child: Column(
             mainAxisAlignment: MainAxisAlignment.center,
             children: [
               const Text('Transaction info and errors will be logged to the console.'),
             ],
           ),
         ),
       );
     }
   }
   

3- ضبط إعدادات Google Pay

يتطلّب طلب الدفع في Google Pay عنصر طلب. يحتوي العنصر المحدّد هنا باسم _paymentItems على الحدّ الأدنى من الإعدادات الشائعة لجميع الطلبات. ستتم إضافة إعدادات إضافية حسب الطلب المقدَّم، وسنراجعها في هذا الدرس العملي.

1. أضِف ثوابت إعداد Google Pay إلى lib/main.dart:

import 'package:pay/pay.dart';

const _paymentItems = [
  PaymentItem(
    label: 'Total',
    amount: '14.95',
    status: PaymentItemStatus.final_price,
  )
];

2. أضِف ملف JSON لإعدادات الدفع التلقائية إلى المسار assets/google_pay_config.json:

  {
    "provider": "google_pay",
    "data": {
      "environment": "TEST",
      "apiVersion": 2,
      "apiVersionMinor": 0,
      "allowedPaymentMethods": [
        {
          "type": "CARD",
          "tokenizationSpecification": {
            "type": "PAYMENT_GATEWAY",
            "parameters": {
              "gateway": "example",
              "gatewayMerchantId": "exampleGatewayMerchantId"
            }
          },
          "parameters": {
            "allowedCardNetworks": ["VISA", "MASTERCARD"],
            "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
            "billingAddressRequired": true,
            "billingAddressParameters": {
              "format": "FULL",
              "phoneNumberRequired": true
            }
          }
        }
      ],
      "merchantInfo": {
        "merchantName": "Example Merchant Name"
      },
      "transactionInfo": {
        "countryCode": "US",
        "currencyCode": "USD"
      }
    }
  }

الموارد

• مرجع واجهة برمجة التطبيقات: مستندات عناصر الطلب في Google Pay API
• مرجع واجهة برمجة التطبيقات: يُرجى الرجوع إلى PaymentMethod للحصول على مزيد من المعلومات حول طرق التفويض المسموح بها وشبكات البطاقات المسموح بها ومواصفات الترميز، بما في ذلك قيمة البوابة الصحيحة.

4. إضافة زر Google Pay

تتضمّن مكتبة pay مكوّن زر Google Pay أصليًا.

عدِّل الفئة _PaySampleAppState في lib/main.dart باستخدام الرمز التالي:

class _PaySampleAppState extends State<PaySampleApp> {
  late final Future<PaymentConfiguration> _gpayConfig;

  void onGooglePayResult(paymentResult) {
    // Send 'token' to your payment service provider (PSP)
    print(paymentResult);
  }

  @override
  void initState() {
    super.initState();
    _gpayConfig = PaymentConfiguration.fromAsset('google_pay_config.json');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Google Pay Codelab')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            FutureBuilder<PaymentConfiguration>(
              future: _gpayConfig,
              builder: (context, snapshot) {
                if (snapshot.connectionState != ConnectionState.done) {
                  return const Center(child: CircularProgressIndicator());
                }
                if (snapshot.hasError || !snapshot.hasData) {
                  return const Text('Error loading Google Pay config');
                }
                return GooglePayButton(
                  paymentConfiguration: snapshot.data!,
                  onPaymentResult: onGooglePayResult,
                  paymentItems: _paymentItems,
                  height: 48,
                  type: GooglePayButtonType.buy,
                  theme: GooglePayButtonTheme.dark,
                  margin: const EdgeInsets.only(top: 15.0),
                  loadingIndicator: const Center(
                    child: CircularProgressIndicator(),
                  ),
                );
              },
            ),
            const Text('Transaction info and errors will be logged to the console.'),
          ],
        ),
      ),
    );
  }
}

شرح الرمز البرمجي

1. تصف _paymentItems المعاملة التي يجب معالجتها عند النقر على هذا الزر.
2. تحمّل paymentConfigurationAsset في التطبيق المصغّر GooglePayButton الإعدادات من الملف assets/google_pay_config.json.
3. عند الضغط على GooglePayButton، يتم استدعاء الدالة onGooglePayResult. تتلقّى هذه الدالة نتيجة الدفع.
4. بعد الحصول على رمز الدفع المميّز من الردّ، عليك إرساله إلى بوابة الدفع لمعالجة المعاملة.

5- تفعيل الدفع عند النقر

يؤدي النقر على GooglePayButton إلى فتح ورقة Google Pay وعرض نتيجة، ولا يلزم إجراء طلب منفصل "إجراء دفعة". أضِف معالِجات لتسجيل الرمز المميز وعرض الأخطاء وتسجيل الضغط على الزر اختياريًا.

1. أضِف معالج النتائج أو عدِّله داخل _PaySampleAppState:

void onGooglePayResult(dynamic paymentResult) {
  try {
    final token = paymentResult['paymentMethodData']['tokenizationData']['token'];
    debugPrint('Google Pay payment token: $token');
  } catch (e) {
    debugPrint('Unexpected payment result: $e');
  }
}

2. عدِّل GooglePayButton لتضمين معالجات الضغط والأخطاء:

GooglePayButton(
  paymentConfiguration: snapshot.data!,
  paymentItems: _paymentItems,
  onPaymentResult: onGooglePayResult,
  onError: (Object err) => debugPrint('Google Pay error: $err'),
  onPressed: () => debugPrint('Google Pay button pressed'),
  height: 48,
  type: GooglePayButtonType.buy,
  theme: GooglePayButtonTheme.dark,
  margin: const EdgeInsets.only(top: 15.0),
  loadingIndicator: const Center(child: CircularProgressIndicator()),
)

ملاحظات

• يؤدي النقر نفسه إلى تشغيل ورقة الدفع، ويتلقّى onPaymentResult الحمولة.
• في مرحلة الإنتاج، أرسِل الرمز المميّز إلى مقدّم خدمة الدفع لإكمال عملية تحصيل الرسوم.

6. الخاتمة

تهانينا على إكمال هذا الدرس التطبيقي حول الترميز. لقد تعرّفت على كيفية دمج Google Pay API في تطبيق Flutter على Android.

تشغيل المشروع

نفِّذ الأمر التالي لبدء تطبيقك:

flutter run

الخطوة التالية

• مراجعة قائمة مهام الدمج

مراجع إضافية

• الانضمام إلى المحادثة في قناة ‎#payments على Discord
• متابعة @GooglePayDevs على X
• مشاهدة فيديوهات ذات صلة بـ Google Pay على YouTube