حفظ الإشعارات وحذفها
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يشرح هذا الدليل كيفية استخدام عمليات معاودة الاتصال مع Google Wallet API. عندما
تم إنشاء بطاقة أو حذفها، ويمكن أن تعاود Google الاتصال بخادم HTTPS
نقطة نهاية من اختيارك.
تكون معاودة الاتصال هذه خاصة بالفئة وتتضمن بيانات
عن الحدث مثل الفئة والكائن ونوع الحدث.
يمكن استخدام هذا
تتبع عدد عمليات إضافة المستخدم وعمليات الحذف التي تحدث. بالنسبة
على سبيل المثال، يمكن ضبط عمليات معاودة الاتصال لإرسال الأحداث إلى أحد الإحصاءات
لتتبع تفاعل العملاء أثناء الأحداث الترويجية.
المتطلبات الأساسية
قبل البدء، راجع المتطلبات الأساسية التالية:
-
وضع نقطة نهاية HTTPS تعالج طلبات POST. تحتاج نقطة النهاية هذه
أن تكون متاحة للجمهور.
-
تعديل نقطة نهاية معاودة الاتصال آليًا لكل فئة. يمكنك الاطّلاع على
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 ويتم تقسيمه إلى سلسلة كما يلي:
المواقع:
| المُعرّف |
الوصف |
|---|
classId |
معرّف الصف المؤهل بالكامل. تستخدم التنسيق التالي:
<issuer_id.class_id>
|
objectId |
رقم تعريف عنصر مؤهّل بالكامل تستخدم التنسيق التالي:
<issuer_id.object_id>
|
expTimeMillis |
وقت انتهاء الصلاحية بالمللي ثانية منذ EPOCH. بعد وقت انتهاء الصلاحية،
يلزم اعتبار الرسالة غير صالحة.
|
eventType |
يمكن أن تكون إما del أو save
DELETE وSAVE
|
|
nonce |
إشعار لتتبّع أي عمليات تسليم مكرّرة. |
معالجة الطلب من خادم Google
فيما يلي قائمة بالحقول الرئيسية في عنوان الطلب
يتم إرساله إلى نقطة نهاية معاودة الاتصال:
- وكيل المستخدم:
Googlebot
- نوع المحتوى:
application/json
اضبط الخادم بحيث لا يرفض الطلب. للقيام بذلك، يمكنك
ضبط ما يلي في robots.txt:
User-agent: Googlebot
Disallow:
إعادة المحاولة
يتم الاستناد إلى أفضل جهد في عمليات معاودة الاتصال. ستستخدم Google استراتيجيات شائعة لإعادة المحاولة
المرونة في الحالات التي لا تستجيب فيها نقطة نهاية معاودة الاتصال أو
انقطاع متقطع وسيؤدي إلى التراجع عن المحاولات بسلاسة.
عمليات تسليم متكرّرة
قد تكون هناك عمليات تسليم مكررة في بعض الحالات. ننصحك باستخدام
nonce لإزالة التكرار منها.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eGoogle Wallet API allows you to set up callbacks to an HTTPS endpoint to track pass creation and deletion events.\u003c/p\u003e\n"],["\u003cp\u003eThese callbacks provide data like class ID, object ID, and event type, allowing you to monitor user engagement and perform analytics.\u003c/p\u003e\n"],["\u003cp\u003eBefore implementing callbacks, ensure you have a publicly available HTTPS endpoint, update the callback endpoint for each class, and consider using the Tink library for signature verification.\u003c/p\u003e\n"],["\u003cp\u003eGoogle uses a JSON message format for callbacks, containing details about the event, and employs retry strategies for delivery.\u003c/p\u003e\n"],["\u003cp\u003eYou should handle potential duplicate deliveries using the provided 'nonce' and configure your server to accept requests from Googlebot.\u003c/p\u003e\n"]]],["Google Wallet API callbacks notify merchants via HTTPS endpoints when a pass is added or deleted. These class-specific callbacks provide details like class ID, object ID, event type (save/delete), and a nonce for deduplication. Merchants must set up a public HTTPS endpoint, update the callback URL per class, and verify message signatures using the Tink library. The endpoint should accept POST requests and expect JSON-formatted messages; it should also allow requests from the Googlebot user-agent.\n"],null,["# Save and delete notifications\n\nThis guide explains how to use callbacks with the Google Wallet API. When a\npass is created or deleted, Google can perform a callback to an HTTPS\nendpoint of your choosing.\n\nThis callback is class-specific, and includes data\nabout the event such as the class, object, and event type.\n\nThis can be used to\nkeep track of the number of user adds and deletions that occur. For\nexample, callbacks can be configured to send events to an analytics\napplication to track customer engagement during promotional events.\n\nPrerequisites\n-------------\n\nBefore you start, review the following prerequisites:\n\n- Stand up an HTTPS endpoint that handles POST requests. This endpoint needs to be publicly available.\n- Programmatically update the callback endpoint for each class. See the [`callbackOptions`](/wallet/tickets/transit-passes/qr-code/rest/v1/CallbackOptions) property by class in the REST API.\n- Recommended: Use the [Tink](https://developers.google.com/tink) library to verify the signatures.\n\nImplement callbacks\n-------------------\n\n\nFor every add or delete performed by the user on an\n\nan object\n\n, Google makes callbacks to the merchants with details about the add or delete on a\n\nper-class\n\nURL. Merchants need to first use the Public Keys to verify the authenticity of\nthe message. After the callbacks verify the message, the callbacks can be used\nfor downstream operations.\n\nVerify the signature\n--------------------\n\n\nWe recommend that you use the Tink library to verify the message signature\nwhen you implement your HTTPS endpoint. The\n[Tink library](https://github.com/google/tink)\nprovides `PaymentMethodTokenRecipient`, a utility that\nautomatically verifies the signature and returns the actual message upon\nsuccessful verification.\n\n\nThe following example shows how to use the Tink library to implement\n`PaymentMethodTokenRecipient`: \n\n```python\nimport java.io.IOException;\nimport javax.servlet.http.*;\nimport com.google.common.io.CharStreams;\nimport com.google.crypto.tink.apps.paymentmethodtoken.*;\n\n// Replace ISSUER_ID with your issuer id\nprivate static final String RECIPIENT_ID = \"\u003cvar translate=\"no\"\u003eISSUER_ID\u003c/var\u003e\";\n\nprivate static final String PUBLIC_KEY_URL = \"https://pay.google.com/gp/m/issuer/keys\";\nprivate static final String SENDER_ID = \"GooglePayPasses\";\nprivate static final String PROTOCOL = \"ECv2SigningOnly\";\n\nprivate static final GooglePaymentsPublicKeysManager keysManager = new GooglePaymentsPublicKeysManager.Builder()\n .setKeysUrl(PUBLIC_KEY_URL)\n .build();\n\npublic void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {\n try {\n // Extract signed message with signature from POST request body.\n String signedMessage = CharStreams.toString(request.getReader());\n PaymentMethodTokenRecipient recipient =\n new PaymentMethodTokenRecipient.Builder()\n .protocolVersion(PROTOCOL)\n .fetchSenderVerifyingKeysWith(keysManager)\n .senderId(SENDER_ID)\n .recipientId(RECIPIENT_ID)\n .build();\n\n String serializedJsonMessage = recipient.unseal(signedMessage);\n\n // Use serializedJsonMessage to extract the details\n } catch (Exception e) {\n // Handle the error\n }\n}\n```\n\nExpected message format\n-----------------------\n\n\nThe message format is JSON that's serialized into a string with the following\nproperties:\n\n| Identifier | Description |\n|-----------------|-----------------------------------------------------------------------------------------------------------------|\n| `classId` | Fully qualified class ID. Uses the following format: ``` \u003cissuer_id.class_id\u003e ``` |\n| `objectId` | Fully qualified object ID. Uses the following format: ``` \u003cissuer_id.object_id\u003e ``` |\n| `expTimeMillis` | Expiration time in milliseconds since EPOCH. After the expiration time, the message needs to be deemed invalid. |\n| `eventType` | Can be either `del` or `save` for `DELETE` and `SAVE`. |\n| `nonce` | Nonce to track any duplicate deliveries. |\n\n### Handle the request from a Google server\n\n\nThe following is a list of the key fields in the header of the request that's\nsent to your callback endpoint:\n\n- User-Agent: `Googlebot`\n- Content-Type: `application/json`\n\n\nConfigure your server so that it doesn't reject the request. To do so, you can\nset the following in `robots.txt`: \n\n```\nUser-agent: Googlebot\nDisallow:\n```\n\n### Retries\n\n\nCallbacks are on a best-effort basis. Google will use common retry strategies\nto be resilient in cases where the callback endpoint is not responding or has an\nintermittent outage and will gracefully back off attempts.\n\n### Duplicate deliveries\n\n\nThere might be duplicate deliveries in some cases. We recommend that you use\n`nonce` to dedupe them."]]
