إضافة طلبات معاودة الاتصال وحذفها

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

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

قبل البدء، راجِع المتطلبات الأساسية التالية:

• استخدِم نقطة نهاية HTTPS تعالج طلبات POST. يجب أن تكون نقطة النهاية هذه متاحة للجميع.
• عدِّل آليًا عنوان URL لنقطة نهاية معاودة الاتصال لجهة الإصدار. يمكنك الاطّلاع على السمة callbackOptions الخاصة بجهة الإصدار في واجهة برمجة تطبيقات REST.
• إجراء يُنصح به: يمكنك استخدام مكتبة Tink للتحقّق من التوقيعات.

تنفيذ عمليات معاودة الاتصال

بالنسبة إلى كل عملية إضافة أو حذف يجريها المستخدم على بطاقة، تُجري Google معاودة الاتصال بالتجّار مع تضمين تفاصيل حول الإضافة أو الحذف على عنوان URL لمعاودة الاتصال بجهة إصدار البطاقة. ويجب أن يستخدم التجّار أولاً المفاتيح العامة للتحقّق من صحة الرسالة. بعد التحقّق من الرسالة من خلال عمليات معاودة الاتصال، يمكن استخدام عمليات رد الاتصال لعمليات تنزيل البيانات.

إثبات صحة التوقيع

ننصحك باستخدام مكتبة Tink للتحقّق من توقيع الرسائل عند تنفيذ نقطة نهاية HTTPS. توفّر مكتبة Tik PaymentMethodTokenRecipient، وهي أداة تتحقّق تلقائيًا من التوقيع وتعرض الرسالة الفعلية عند إثبات الملكية بنجاح.

يوضِّح المثال التالي كيفية استخدام مكتبة Tink لتنفيذ PaymentMethodTokenRecipient:

import java.io.IOException;
import javax.servlet.http.*;
import com.google.common.io.CharStreams;
import com.google.crypto.tink.apps.paymentmethodtoken.*;

// Replace ISSUER_ID with your issuer id
private static final String RECIPIENT_ID = "ISSUER_ID";

private static final String PUBLIC_KEY_URL = "https://pay.google.com/gp/m/issuer/keys";
private static final String SENDER_ID = "GooglePayPasses";
private static final String PROTOCOL = "ECv2SigningOnly";

private static final GooglePaymentsPublicKeysManager keysManager = new GooglePaymentsPublicKeysManager.Builder()
        .setKeysUrl(PUBLIC_KEY_URL)
        .build();

public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
  try {
    // Extract signed message with signature from POST request body.
    String signedMessage = CharStreams.toString(request.getReader());
    PaymentMethodTokenRecipient recipient =
            new PaymentMethodTokenRecipient.Builder()
                    .protocolVersion(PROTOCOL)
                    .fetchSenderVerifyingKeysWith(keysManager)
                    .senderId(SENDER_ID)
                    .recipientId(RECIPIENT_ID)
                    .build();

    String serializedJsonMessage = recipient.unseal(signedMessage);

    // Use serializedJsonMessage to extract the details
  } catch (Exception e) {
    // Handle the error
  }
}

تنسيق الرسالة المتوقع

تنسيق الرسالة هو JSON وهو متسلسل في سلسلة تحتوي على السمات التالية:

المُعرّف	الوصف
externalPassId	رقم تعريف البطاقة الخارجية المؤهَّلة بالكامل. تستخدم التنسيق التالي: <issuer_id.external_pass_id>
expTimeMillis	وقت انتهاء الصلاحية بالمللي ثانية منذ EPOCH. وبعد وقت انتهاء الصلاحية، يجب اعتبار الرسالة غير صالحة.
eventType	ويمكن أن تكون القيمة del أو save لـ DELETE وSAVE.
nonce	لا يوجد مكان لتتبع أي عمليات تسليم مكررة.

معالجة الطلب من خادم Google

في ما يلي قائمة بالحقول الرئيسية في عنوان الطلب والتي يتم إرسالها إلى نقطة نهاية معاودة الاتصال:

• وكيل المستخدم: Googlebot
• نوع المحتوى: application/json

اضبط الخادم حتى لا يرفض الطلب. لإجراء ذلك، يمكنك ضبط ما يلي في robots.txt:

User-agent: Googlebot
Disallow:

مرات إعادة المحاولة

تُجرى عمليات معاودة الاتصال على أساس أفضل جهد. ويحاول Google مرتين لتفسير الإخفاقات العابرة. وبعد المحاولة مرّتين، تحذفها Google ولا تحاول إعادة إرسالها مرة أخرى.

عمليات تسليم مكرّرة

قد تكون هناك عمليات تسليم مكررة في بعض الحالات. وننصحك باستخدام nonce لإزالة تكرارها.