Reminder: By Aug 31, 2025, all new apps and updates to existing apps must use Billing Library version 7 or newer. If you need more time to update your app, you can request an extension until Nov 1, 2025. Learn about Play Billing Library version deprecation.
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتسم المنتجات التي يتم شراؤها لمرة واحدة بدورة حياة أبسط من المنتجات التي تتطلب اشتراكًا،
ولكن لا يزال هناك العديد من الحالات وأحداث الانتقال التي يجب أن يتمكّن الخلفية من التعامل معها بشكل صحيح.
الشكل 1 حالات مراحل النشاط وأحداث الانتقال لعمليات الشراء لمرة واحدة
عمليات شراء جديدة لمنتجات يتم تحصيل سعرها مرة واحدة
بعد أن يكمل المستخدم عملية الفوترة، يمكن لتطبيقك الاطّلاع على معلومات حول عملية الشراء الجديدة بإحدى الطرق التالية:
اضبط Real-time developer notifications وفعِّل Get all
notifications for subscriptions and one-time products لتلقّي إشعارات بشأن حالة عمليات الشراء.
نفِّذ واجهة PurchasesUpdatedListener
من BillingClient لتلقّي إشعارات بشأن عمليات الشراء تلقائيًا.
عندما يشتري المستخدم منتجًا يتم تحصيل سعره مرة واحدة أو يلغي عملية شرائه، يرسل Google Play رسالة OneTimeProductNotification.
لتعديل حالة عملية الشراء في الخلفية، استخدِم رمز الشراء المقدَّم في العنصر
OneTimeProductNotification لاستدعاء الطريقة
purchases.productsv2.getproductpurchasev2. توفّر هذه الطريقة آخر حالة للشراء والاستهلاك بالنظر إلى رمز مميّز للشراء.
يجب التعامل مع إشعارات RTDN المرتبطة بالمعاملات في الخلفية الآمنة.
التعامل مع المعاملات المكتملة
عندما يُكمل المستخدم عملية شراء منتج لمرة واحدة، يرسل Google Play رسالة
OneTimeProductNotification من النوع ONE_TIME_PRODUCT_PURCHASED.
عند تلقّي هذا الإشعار في الوقت الفعلي الخاص بالمطوّرين، عالِج عملية الشراء كما هو موضّح في معالجة عمليات شراء المنتجات لمرة واحدة في الخلفية.
التعامل مع المعاملات الملغاة
عند إلغاء عملية شراء منتج يتم تحصيل سعره مرة واحدة، يرسل Google Play رسالة OneTimeProductNotification من النوع ONE_TIME_PRODUCT_CANCELED
إذا كنت قد أعددت تلقّي إشعارات في الوقت الفعلي خاصة بالمطوّرين. على سبيل المثال، يمكن أن يحدث ذلك إذا لم يُكمل المستخدم عملية الدفع خلال الإطار الزمني المطلوب، أو إذا ألغى المطوّر عملية الشراء أو إذا طلب العميل ذلك. عندما يتلقّى خادم الخلفية هذا الإشعار، استدعِ طريقة
purchases.productsv2.getproductpurchasev2
للحصول على أحدث حالة شراء، ثم عدِّل خادم الخلفية وفقًا لذلك،
بما في ذلك أذونات المستخدم.
إذا تم ردّ أموال عملية شراء منتج يتم تحصيل سعره مرة واحدة في الحالة Purchased، سيتم إعلامك أيضًا باستخدام Voided Purchases API.
معالجة عمليات شراء المنتجات لمرة واحدة في الخلفية
سواء رصدت عملية شراء جديدة باستخدام ONE_TIME_PRODUCT_PURCHASED
RTDN
أو تم إعلامك بها داخل التطبيق من خلال
PurchasesUpdatedListener أو استرجاع عمليات الشراء
يدويًا في طريقة onResume() بتطبيقك، عليك معالجة
عملية الشراء الجديدة. ننصحك بالتعامل مع معالجة عمليات الشراء في الخلفية لتحقيق أمان أفضل.
اتّبِع الخطوات التالية لإجراء عملية شراء جديدة لمرة واحدة:
أرسِل طلب بحث إلى نقطة النهاية
purchases.productsv2.getproductpurchasev2
للحصول على أحدث حالة لعملية شراء منتج لمرة واحدة. لاستدعاء هذه الطريقة لعملية شراء، يجب توفُّر purchaseToken المقابل إما من تطبيقك أو من ONE_TIME_PRODUCT_PURCHASED RTDN.
اتّصِل بالرقم getPurchaseState() وتأكَّد من أنّ حالة الشراء هي PURCHASED.
امنح المستخدم إذن الوصول إلى المحتوى. يمكن تحديد حساب المستخدم المرتبط بعملية الشراء باستخدام الحقل obfuscatedExternalAccountId من purchases.productsv2.getproductpurchasev2، إذا تم ضبطه باستخدام setObfuscatedAccountId() عند إجراء عملية الشراء.
بالنسبة إلى عمليات شراء المنتجات غير الاستهلاكية، يجب الإقرار بتسليم المحتوى من خلال استدعاء الطريقة purchases.products.acknowledge.
تأكَّد من عدم التصديق على عملية الشراء مسبقًا من خلال التحقّق من الحقل acknowledgementState.
إذا كان المنتج استهلاكيًا، ضَع علامة على المنتج بأنه مستهلك من خلال استدعاء طريقة purchases.products.consume، ليتمكّن المستخدم من شراء المنتج مرة أخرى بعد استهلاكه. تؤكّد هذه الطريقة أيضًا عملية الشراء.
تتوفّر أيضًا طريقتان لتأكيد عمليات الشراء والاستهلاك في
Play Billing Library تتيحان لك معالجة عمليات الشراء من تطبيقك، ولكننا
ننصحك بالتعامل مع المعالجة في الخلفية إذا كان لديك واحدة لتنفيذ أكثر
أمانًا.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# One-time purchase lifecycle\n\nOne-time purchase products have a simpler lifecycle than subscription products,\nbut there are still several states and transition events that your backend needs\nto be able to handle properly.\n**Figure 1** Lifecycle states and transition events for one-time purchases.\n\nNew one-time product purchases\n------------------------------\n\nAfter the user completes the billing flow, your app can see information about\nthe new purchase in one of the following ways:\n\n- Setup [`Real-time developer notifications`](/google/play/billing/getting-ready#enable-rtdn \"Real-time developer notifications\") and enable `Get all\n notifications for subscriptions and one-time products` to receive updates on the status of purchases.\n- Implement the [`PurchasesUpdatedListener`](/reference/com/android/billingclient/api/PurchasesUpdatedListener) interface from `BillingClient` to automatically receive purchase updates.\n- Call the [`BillingClient.queryPurchasesAsync()`](/reference/com/android/billingclient/api/BillingClient#queryPurchasesAsync(com.android.billingclient.api.QueryPurchasesParams,%20com.android.billingclient.api.PurchasesResponseListener)) method.\n\nAfter receiving the new purchase, use the\n[`getPurchaseState`](/reference/com/android/billingclient/api/Purchase#getPurchaseState()) method or\n[`purchases.productsv2.getproductpurchasev2 in Play Developer API`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2/getproductpurchasev2 \"purchases.productsv2.getproductpurchasev2 in Play Developer API\")\n\nto determine the payment state of the new purchase.\n\n### Real-time developer notifications\n\n| **Note:** One-time purchase real-time developer notifications are only published if you have [opted into them while configuring real-time developer\n| notifications](/google/play/billing/getting-ready#enable-rtdn \"Real-time developer notifications\").\n\nWhen a user purchases or cancels the purchase of a one-time product, Google Play\nsends a [`OneTimeProductNotification`](/google/play/billing/rtdn-reference#one-time) message.\nTo update your backend purchase state, use the purchase token provided in the\n`OneTimeProductNotification` object to call the\n[`purchases.productsv2.getproductpurchasev2`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2)\nmethod. This method provides the latest purchase and consumption status given a\npurchase token.\n\nWhen a pre-order is fulfilled and its purchase state changes to PURCHASED, an\nRTDN is sent to your client. After receiving the RTDN, process the pre-order\npurchase as described in [Process one-time product purchases in your\nbackend](#process).\n\nYou should handle transaction-related RTDNs in your secure backend.\n\n### Handle completed transactions\n\nWhen a user completes a one-time product purchase, Google Play sends a\n`OneTimeProductNotification` message with the type `ONE_TIME_PRODUCT_PURCHASED`.\nWhen you receive this RTDN, process the purchase as described in [Process\none-time product purchases in your backend](#process).\n\n### Handle canceled transactions\n\nWhen a one-time product purchase is canceled, Google Play sends a\n`OneTimeProductNotification` message with the type `ONE_TIME_PRODUCT_CANCELED`\nif you have configured to receive real-time developer notifications. For\nexample, this can occur if the user doesn't complete payment within the required\ntimeframe, or if the purchase is revoked by the developer or by customer\nrequest. When your backend server receives this notification, call the\n[`purchases.productsv2.getproductpurchasev2`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2)\nmethod to get the latest purchase state, then update your backend accordingly,\nincluding user entitlements.\n\nIf a one-time product purchase in `Purchased` state gets refunded, you will also\nbe made aware using the [Voided Purchases API](https://developers.google.com/android-publisher/voided-purchases).\n\nProcess one-time product purchases in your backend\n--------------------------------------------------\n\nWhether you have detected a new purchase using a `ONE_TIME_PRODUCT_PURCHASED`\nRTDN\nor you have been made aware in-app through\n[`PurchasesUpdatedListener`](/reference/com/android/billingclient/api/PurchasesUpdatedListener) or [manually fetching\npurchases](/google/play/billing/integrate#fetch) in your app's `onResume()` method, you must process\nthe new purchase. We recommend that you handle purchase processing in your\nbackend for better security.\n\nFollow these steps to process a new one-time purchase:\n\n1. Query the [`purchases.productsv2.getproductpurchasev2`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2) endpoint to obtain the latest one-time product purchase status. To call this method for a purchase, you need the corresponding `purchaseToken` either from your app or from the `ONE_TIME_PRODUCT_PURCHASED` RTDN.\n2. Call [`getPurchaseState()`](/reference/com/android/billingclient/api/Purchase#getPurchaseState()) and make sure that the purchase state is `PURCHASED`.\n3. [Verify the purchase](/google/play/billing/security#verify).\n4. Give the user access to the content. The user account associated with the purchase can be identified with the [`obfuscatedExternalAccountId`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2#ProductPurchaseV2) field from `purchases.productsv2.getproductpurchasev2`, if one was set using [`setObfuscatedAccountId()`](/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId(java.lang.String)) when the purchase was made.\n 1. For non-consumable product purchases, acknowledge delivery of the content by calling the [`purchases.products.acknowledge`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge) method. Make sure that the purchase hasn't been previously acknowledged by checking the [`acknowledgementState`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2) field.\n 2. If the product is consumable, mark the item as consumed by calling the [`purchases.products.consume`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/consume) method so that the user can buy the item again after they have consumed it. This method also acknowledges the purchase.\n\n| **Note:** If you don't acknowledge a purchase within three days, the user automatically receives a refund, and Google Play revokes the purchase.\n\nThere are also purchase acknowledgement and consume methods available in the\nPlay Billing Library that allow you to process purchases from you app, but we\nrecommend that you handle processing in your backend if you have one for a more\nsecure implementation."]]
