بدء استخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android

قبل بدء استخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android، تأكّد من تنفيذ المتطلبات الأساسية.

تتيح لك حزمة تطوير البرامج (SDK) لنظام التشغيل Android إضافة البطاقات إلى "محفظة Google". عند إضافة زرّ محفظة Google إلى تطبيقك، سيحظى المستخدمون بتجربة بسيطة وممتعة بإضافة بطاقاتهم إلى "محفظة Google".

اتّبِع الخطوات لإضافة زر محفظة Google إلى تطبيق Android:

1- إنشاء عنصر من "البطاقات"

ملاحظة: يجب توفير فئة البطاقات لإنشاء كائن البطاقات. إذا لم يسبق لك إنشاء بطاقة، اتّبِع التعليمات حول كيفية إنشاء فئة بطاقات. حدِّد سمة GiftCardObject مطابقة، بما في ذلك السمات المطلوبة التالية:

• classId: رقم تعريف فئة البطاقات الذي تم إنشاؤه في المتطلبات الأساسية.
• id: معرّف فريد للكائن

• cardNumber: المعرّف المرتبط بالبطاقة

• state: يُستخدم هذا الحقل لتحديد طريقة عرض الكائن. على سبيل المثال، يتم نقل عنصر غير نشط إلى قسم "البطاقات المنتهية الصلاحية".

يمكنك مراجعة نموذج التنسيق للاطّلاع على مزيد من المعلومات حول كيفية تمثيل هذه السمات في بطاقة الهدايا.

في ما يلي تعريف نموذج بطاقة الهدايا:

JSON

      
{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.CLASS_ID",
  "cardNumber": "1234567890",
  "state": "ACTIVE"
}
      
    

2. إنشاء JWT غير موقَّع باستخدام الكائن

عند إنشاء GiftCardObject، يجب لفّه باستخدام JWT غير موقَّع مع السمة payload.GiftCardObjects، كما هو موضّح في المقتطف التالي:

JSON

{
  "iss": "OWNER_EMAIL_ADDRESS",
  "aud": "google",
  "typ": "savetowallet",
  "iat": "UNIX_TIME",
  "origins": [],
  "payload": {
      "giftcardObjects": [ NEW_OBJECT ]
  }
}

3. تضمين زر "محفظة Google" في واجهة المستخدم

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

ملاحظة: احرِص على تضمين رسومات للإعدادات المتوافقة فقط.

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

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

<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 Wallet API على الجهاز المستهدَف

قبل حفظ العنصر الجديد، تأكَّد من أنّ واجهة برمجة تطبيقات Google Wallet متاحة على الجهاز المستهدَف من خلال استدعاء الطريقة 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، فضع منطق العمل المرتبط بواجهة المستخدم في النشاط أو الجزء (على سبيل المثال: عناصر واجهة المستخدم ونتيجة النشاط) والمنطق التشغيلي في نموذج العرض (مثل: توضيح العميل وعوامل تشغيل الاتصال بالشبكة).

يمكنك الآن الاستعانة بالعميل للتحقق مما إذا كانت واجهة برمجة التطبيقات متوفرة أم لا:

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). يُرجى العلم بأنّ المستخدم قد يصبح مؤهلاً لاستخدام واجهة برمجة التطبيقات في المستقبل.

5. إضافة العنصر إلى "محفظة Google"

يمكن إضافة GiftCardObject من خلال تمرير JWT غير الموقَّع من الخطوة 2 إلى طريقة 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.

ملاحظة: في حال تنفيذ عملية الدمج على كلّ من Android والويب، يمكنك إعادة استخدام ملف JWT الموقَّع والمطلوب للدمج على الويب، وذلك من خلال طلب savePassesJwt بدلاً من savePasses.

تمريرات [للاختبار فقط]

عندما لا تزال في الوضع التجريبي، ستتضمّن جميع البطاقات التي تنشئها نصًا إضافيًا "[للاختبار فقط]" في عنوان بطاقتك. يساعد ذلك في التفريق بين البطاقات التجريبية والبطاقات المباشرة. بعد الحصول على موافقة الإنتاج من فريقنا، لن يتوفر نص إضافي لبطاقات الوضع التجريبي هذه عندما يعيد المستخدم فتح تطبيق المحفظة على جهاز متصل.

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

• قم بتقييم حالات استخدام بطاقات الهدايا وتنفيذ تلك التي تناسب احتياجات العمل
• يمكنك تخصيص مظهر بطاقات الهدايا من خلال اتّباع إرشادات العلامة التجارية
• أرسِل خطوات تجربة المستخدم للمراجعة النهائية في قسم Google Wallet API على Google Pay و Wallet Console.
• اختبِر عملية الدمج وابدأ البث المباشر.
• هل لديك مزيد من الأسئلة؟ يُرجى الاطّلاع على الأسئلة الشائعة.