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

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

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

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

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

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

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

تأكيد التوقيع

ننصحك باستخدام مكتبة Tink للتحقّق من توقيع الرسالة عند تنفيذ نقطة نهاية HTTPS. توفّر مكتبة Tink 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 وقت انتهاء الصلاحية بالمللي ثانية منذ بداية الحقبة بعد انتهاء وقت الصلاحية، يجب اعتبار الرسالة غير صالحة.
eventType يمكن أن تكون القيمة del أو save لكل من DELETE وSAVE.
nonce رقم عشوائي لتتبُّع أي عمليات تسليم مكرّرة

التعامل مع الطلب من خادم Google

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

  • User-Agent: Googlebot
  • Content-Type: application/json

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

User-agent: Googlebot
Disallow:

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

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

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

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