مشاكل البطاقات في حزمة تطوير البرامج (SDK) لنظام التشغيل Android

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

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

قبل محاولة إصدار بطاقة، تأكَّد من إكمال ما يلي:

1. تثبيت حزمة تطوير البرامج (SDK) لنظام التشغيل Android في "محفظة Google"

لاستخدام حزمة تطوير البرامج (SDK) لتطبيق "محفظة Google" على Android، أضِف com.google.android.gms:play-services-pay إلى قسم dependencies في ملف build.gradle على مستوى التطبيق:

  implementation "com.google.android.gms:play-services-pay:16.5.0"

2. التحقّق من توفّر Google Wallet API

قبل حفظ العنصر الجديد، تأكَّد من أنّ واجهة برمجة التطبيقات Google Wallet API متوفرة على الجهاز المستهدَف من خلال استدعاء طريقةgetPayApiAvailabilityStatus في فئةPayClient.

ابدأ بإضافة متغيّر عضو إلى النشاط الذي ستعرض فيه الزر وتنشئه عند إنشاء النشاط:

Kotlin

import com.google.android.gms.pay.PayClient

private lateinit var walletClient: PayClient

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  walletClient = Pay.getClient(this)

  // Additional logic in your onCreate method
}

Java

import com.google.android.gms.pay.PayClient;

private final PayClient walletClient;

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  walletClient = Pay.getClient(application);

  // Additional logic in your onCreate method
}

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

بعد ذلك، استخدِم PayClient للتحقّق من توفّر واجهة برمجة التطبيقات:

Kotlin

import com.google.android.gms.pay.PayApiAvailabilityStatus

private fun fetchCanUseGoogleWalletApi() {
  walletClient
    .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
    .addOnSuccessListener { status ->
      if (status == PayApiAvailabilityStatus.AVAILABLE) {
        // The API is available, show the button in your UI
      } else {
        // The user or device is not eligible for using the Pay API
      }
    }
    .addOnFailureListener {
      // Hide the button and optionally show an error message
    }
}

Java

import com.google.android.gms.pay.PayApiAvailabilityStatus;

private void fetchCanAddPassesToGoogleWallet() {
  walletClient
    .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
    .addOnSuccessListener(status -> {
      if (status == PayApiAvailabilityStatus.AVAILABLE) {
        // The API is available, show the button in your UI
      } else {
        // The user or device is not eligible for using the Pay API
      };
    })
    .addOnFailureListener(exception -> {
      // Google Play Services is too old, or API availability not verified
      // Hide the button and optionally show an error message
    });
}

أخيرًا، استخدِم الطريقة التي حدّدتها للتو في تطبيقك عندما تحتاج إلى تحديد مدى توفّر واجهة برمجة التطبيقات.

التعامل مع حالات عدم توفّر واجهة برمجة التطبيقات

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

إذا لم تكن واجهة برمجة التطبيقات متاحة، ننصحك بإخفاء الزر والرجوع إلى عملية دمج مختلفة (مثل استخدام رابط JWT). يُرجى العِلم أنّ المستخدم قد يصبح مؤهلاً لاستخدام واجهة برمجة التطبيقات في المستقبل.

3- إضافة الزر "الإضافة إلى محفظة Google"

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

يمكنك استيراد مواد العرض المتّجهة في "استوديو Android" ضمن File > New > Vector Asset. اختَر "ملف على الجهاز" في المعالج، وأضِف اسمًا (مثلاً: add_to_google_wallet_button.xml) وحدِّد مكان الملف في محرك الأقراص المحلي لاستيراده.

  • زر "الإضافة إلى محفظة Google"
  • زر "الإضافة إلى محفظة Google" المصغّر

يمكنك الآن استخدام العنصر القابل للرسم الذي تم استيراده لإضافة الزر إلى واجهة المستخدم:

    <ImageButton
        android:id="@+id/addToGoogleWalletButton"
        android:layout_width="match_parent"
        android:layout_height="48dp"
        android:minWidth="200dp"
        android:clickable="true"
        android:src="@drawable/add_to_google_wallet_button" />

يبلغ layout_height للزر 48 بكسل مستقل الكثافة، ويجب ألا يقلّ عرضه عن 200 بكسل مستقل الكثافة.

4. إضافة بطاقة إلى "محفظة Google" الخاصة بالمستخدم

يمكن إضافة OfferObject من خلال تمرير رمز JWT غير موقَّع إلى طريقة savePasses. يمكنك بدء عملية الإضافة نتيجة النقر على زر "محفظة Google".

Kotlin

import android.os.Bundle
import android.view.View
import com.google.android.gms.samples.wallet.databinding.ActivityCheckoutBinding

private val addToGoogleWalletRequestCode = 1000

private lateinit var layout: ActivityCheckoutBinding
private lateinit var addToGoogleWalletButton: View

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  // Use view binding to access the UI elements
  layout = ActivityCheckoutBinding.inflate(layoutInflater)
  setContentView(layout.root)

  addToGoogleWalletButton = layout.addToGoogleWalletButton
  addToGoogleWalletButton.setOnClickListener {
    walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode)
  }

  // Additional logic in your onCreate method
}

Java

import android.os.Bundle;
import android.view.View;
import com.google.android.gms.samples.wallet.databinding.ActivityCheckoutBinding;

private static final int ADD_TO_GOOGLE_WALLET_REQUEST_CODE = 999;

private ActivityCheckoutBinding layout:
private View addToGoogleWalletButton;

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  // Use view binding to access the UI elements
  layout = ActivityCheckoutBinding.inflate(getLayoutInflater());
  setContentView(layout.getRoot());

  addToGoogleWalletButton = layout.addToGoogleWalletButton;
  addToGoogleWalletButton.setOnClickListener(v -> {
    walletClient.savePasses(newObjectJson, this, ADD_TO_GOOGLE_WALLET_REQUEST_CODE);
  });

  // Additional logic in your onCreate method
}

معالجة النتائج

تؤدي الطريقة savePasses إلى بدء عملية الحفظ وتنشيط الطريقة onActivityResult بعد اكتمال عملية الحفظ. يجب أن يكون تنفيذ onActivityResult مشابهًا لما يلي:

Kotlin

import android.content.Intent

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

  if (requestCode == addToGoogleWalletRequestCode) {
    when (resultCode) {
      RESULT_OK -> {
        // Pass saved successfully
      }

      RESULT_CANCELED -> {
        // Save operation canceled
      }

      PayClient.SavePassesResult.SAVE_ERROR -> data?.let { intentData ->
        val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
        // Handle error
      }

      else -> {
          // Handle unexpected (non-API) exception
      }
    }
  }
}

Java

import android.content.Intent;

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
  super.onActivityResult(requestCode, resultCode, data);

  if (requestCode == ADD_TO_GOOGLE_WALLET_REQUEST_CODE) {
    switch (resultCode) {
      case RESULT_OK: {
        // Pass saved successfully
        break;
      }

      case RESULT_CANCELED: {
        // Save operation canceled
        break;
      }

      case PayClient.SavePassesResult.SAVE_ERROR: {
        if (data != null) {
          String apiErrorMessage = data.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE);
          // Handle error
        }
        break;
      }

      default: {
        // Handle unexpected (non-API) exception
      }
    }
  }
}

عند إضافة البطاقة بنجاح، يحتوي العنصر resultCode على قيمة Activity.RESULT_OK.