إرشادات حول دمج الخلفية لتحقيق الربح خارج خدمة "الفوترة في Google Play"

تتضمّن Google Play Developer API وظائف إضافية لإعداد تقارير عن المعاملات من برامج الفوترة والربط. يوضّح هذا الدليل كيفية الإبلاغ عن المعاملات من برامج الفوترة هذه.

هناك بعض المكوّنات التي قد تكون ضرورية للتعامل مع المعاملات الخارجية من الخلفية. لإنشاء هذه الإشعارات، عليك إعداد عملية الدمج مع الخلفية كما هو موضّح في إعداد Google Play Developer API. لإنشاء وظائف خلفية للمطوّرين غير مرتبطة بالفوترة وبرامج الربط، يُرجى الاطّلاع على نظام الفوترة في Google Play.

مسرد المصطلحات

اتّبِع اصطلاحات المصطلحات التالية في هذا الدليل:

• برامج الفوترة والربط: برامج تسهّل عمليات شراء المحتوى الرقمي أو تنزيل التطبيقات من خارج Google Play. ويشمل ذلك برنامجَي نظام الفوترة البديل والمحتوى الخارجي.
• واجهات برمجة التطبيقات للمعاملات الخارجية: هي واجهات برمجة تطبيقات تُستخدَم للإبلاغ عن المعاملات في برامج الفوترة والربط المؤهّلة.
• المعاملة الخارجية: هي معاملة مؤهَّلة تتم خارج التطبيق على النحو المحدّد في برنامجي نظام الفوترة البديل والمحتوى الخارجي.
• رمز المعاملة الخارجية: هو رمز يتم توفيره من خلال مكتبة Play Billing Library لتستخدمه عندما يُكمل المستخدم معاملة خارجية. يُستخدَم هذا الرمز المميز لإعلام Google Play بإتمام معاملة خارجية بنجاح.
• معرّف المعاملة الخارجية: هو معرّف فريد تنشئه لتحديد معاملة خارجية.

إبلاغ Google Play بالمعاملات الخارجية الجديدة

يمكنك الدمج مع واجهة برمجة التطبيقات externaltransactions من أجل إعداد تقارير عن المعاملات التي تتم خارج نظام الفوترة في Google Play في البلدان المؤهَّلة، بما في ذلك المعاملات التي تبلغ قيمتها 0 دولار أمريكي الناتجة عن عمليات شراء تجريبية مجانية وعمليات تثبيت التطبيقات. يجب عدم بدء المعاملات وإعداد تقارير عنها في برامج الفوترة والربط إلا في بلدان المستخدمين المؤهَّلة على النحو المسموح به بموجب إرشادات نظام الفوترة البديل أو العروض الترويجية الخارجية أو الدفعات الخارجية، وإلا سيتم رفض طلب البيانات من واجهة برمجة التطبيقات. ينطبق ذلك على جميع المعاملات، بما في ذلك عمليات الشراء والتجديد وإضافة الرصيد والترقية وخفض المستوى وتنزيل التطبيقات.

إعداد تقارير المعاملات الخارجية

عليك طلب واجهة برمجة التطبيقات externaltransactions للإبلاغ عن معاملة خارجية بعد السماح بعملية الدفع من خلال برنامج الفوترة والربط. ينطبق ذلك على جميع المعاملات، بما في ذلك الرسوم الأولية وعمليات التجديد وردّ الأموال وغيرها. يُرجى الاطّلاع على إرشادات برنامج الفوترة والربط المعنيَّين لمعرفة متطلبات إعداد التقارير.

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

الإبلاغ عن معاملة أولية

في كل مرة تتم فيها عملية شراء جديدة أو تنزيل تطبيق بنجاح في برامج الفوترة والربط، عليك طلب البيانات من واجهة برمجة التطبيقات externaltransactions.

يجب تضمين externalTransactionToken التي يتلقّاها التطبيق من خلال مكتبة الفوترة في Google Play ضمن نص الطلب الخاص بعمليات تنزيل التطبيقات وعمليات الشراء لمرة واحدة والمعاملات التي تتم لأول مرة في عملية شراء متكررة (مثل الاشتراك). ويُعرف ذلك باسم المعاملة الأولية. بعد المعاملة الأولية، يجب إعداد تقارير عن المعاملات اللاحقة (مثل تجديد الاشتراكات) من خلال تقديم externalTransactionId جديد وفريد. لمزيد من المعلومات، اطّلِع على مقالة الإبلاغ عن معاملات لاحقة لعملية شراء.

مثال:

1. يضبط المطوّر نظام الفوترة البديل ويفعّله في تطبيقه.
2. المستخدم 1 مقيم في كوريا الجنوبية، وهي بلد يتوفّر فيه هذا العرض، ويحاول شراء product1 مقابل 12634.10 وون كوري جنوبي شهريًا، مع عرض فترة تجريبية مجانية لمدة شهر واحد.
3. يُطلق التطبيق مسار الشراء باستخدام ProductDetails مقابل product1 والعرض الذي اختاره المستخدم.
4. يختار المستخدم 1 نظام الفوترة البديل الذي يوفّره المطوّر.
5. يتلقّى UserChoiceBillingListener القيمة my_token كـ externalTransactionToken.
6. بعد ذلك، يرسل المطوّر المعلومات ذات الصلة إلى الخلفية (قيمة externalTransactionToken والمنتجات التي يتم شراؤها). بعد ذلك، يبدأون عملية الشراء الخاصة بـ product1 في نظام الفوترة البديل. يتم تخصيص معرّف معاملة فريد لهذه المعاملة من جهة المطوّر ويُستخدَم في إرسال تقرير بها إلى Google Play: 123-456-789. يجب تقديم معرّف المعاملة، حتى إذا كان المستخدم سيحصل على فترة تجريبية مجانية.
7. بعد إجراء معاملة الشراء في نظام الفوترة البديل، يرسل المطوّر تقريرًا عن المعاملة إلى Google Play باستخدام الطلب التالي. ويتم تسجيلها كمعاملة بقيمة صفر دولار أمريكي في البداية لأنّ المستخدم يحصل على شهر مجاني.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

عند الإبلاغ عن معاملة أولية، يُرجى مراعاة ما يلي:

• يمكن أن تكون قيمة subscriptionType هي RECURRING (للاشتراكات التي يتم تجديدها تلقائيًا) أو PREPAID (للاشتراكات المدفوعة مسبقًا).
• يجب استخدام OtherRecurringProduct لتمثيل عمليات الشراء لمرة واحدة التي تتطلّب دفعات متعدّدة أو دفعة مؤجّلة. على سبيل المثال، قد تتضمّن عملية الطلب المُسبَق معاملة أولية بقيمة 0 دولار أمريكي، تليها معاملة ثانية في تاريخ لاحق بسعر رمز التخزين التعريفي عند إكمال الطلب المُسبَق. لمزيد من التفاصيل حول الإبلاغ عن المعاملات اللاحقة، يُرجى الاطّلاع على مقالة الإبلاغ عن المعاملات اللاحقة لعملية شراء.
• يجب تقديم ExternalOfferDetails عند الإبلاغ عن المعاملات الأولية للعروض الترويجية الخارجية. هذا الإجراء غير مطلوب للمعاملات اللاحقة.

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

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

العروض الترويجية الخارجية

إذا كانت المعاملة التي يتم الإبلاغ عنها ضمن برنامج العروض الترويجية الخارجية، عليك ضبط الحقل externalOfferDetails إذا كانت المعاملة لمرة واحدة أو كانت المعاملة الأولى من سلسلة متكررة:

• عند تسجيل معاملات تنزيل التطبيق، اضبط قيمة linkType على LINK_TO_APP_DOWNLOAD وقدِّم القيم المناسبة لكلّ من installedAppPackage وinstalledAppCategory. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة الإبلاغ عن تنزيل تطبيق.
• عند تسجيل معاملات عروض المحتوى الرقمي، اضبط قيمة linkType على LINK_TO_DIGITAL_CONTENT_OFFER.
• بعد تثبيت تطبيق خارجي من خلال برنامج العروض الترويجية الخارجية، عليك الإبلاغ عن المعاملات التي تتم في التطبيق الخارجي، مع ربط هذه المعاملات بحدث تنزيل التطبيق الأصلي:
  • قدِّم externalTransactionToken من حدث تنزيل التطبيق.
  • في الحقل externalOfferDetails، اضبط قيمة appDownloadEventExternalTransactionId على externalTransactionId لحدث تنزيل التطبيق. لا تكون الحقول الأخرى في externalOfferDetails مطلوبة.

مثال على طلب إجراء معاملة في تطبيق خارجي تم تنزيله من خلال عروض ترويجية خارجية:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "100000",
   "currency": "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros": "10000",
   "currency": "EUR"
 },
"transactionTime" : "2025-11-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": my_external_transaction_token_for_link_to_download_event"
 },
 "userTaxAddress" : {
   "regionCode": "DE"
 },
 "externalOfferDetails" : {
   "appDownloadEventExternalTransactionId": "my_external_transaction_id_for_link_to_download_event"
 }
}

يمكن الاطّلاع على تفاصيل رسوم خدمة Play المعدَّلة لأنواع المعاملات المختلفة في مقالة تغييرات في "برنامج العروض الترويجية الخارجية" للمستخدمين في المنطقة الاقتصادية الأوروبية.

الإبلاغ عن المعاملات اللاحقة لعملية شراء

في بعض الحالات، يكون هناك أكثر من دفعة واحدة مرتبطة بعملية الشراء الخارجية نفسها، مثل عمليات تجديد الاشتراكات أو إضافة رصيد إلى الخطط المدفوعة مسبقًا. يمكنك إعداد تقارير عن هذه المعاملات اللاحقة باستخدام واجهة برمجة التطبيقات نفسها في Externaltransactions. كما هو موضّح في الإبلاغ عن عملية شراء جديدة، لا يلزم استخدام externalTransactionToken في المعاملات اللاحقة. بدلاً من ذلك، يتم إرسال externalTransactionId جديد وفريد كمعلَمة طلب لكل معاملة تجديد أو إعادة شحن، مع تضمين معرّف المعاملة الأولية في الحقل initialExternalTransactionId.

استنادًا إلى المثال السابق:

1. يتم تجديد اشتراك المستخدم 1 لأول مرة من خلال نظام الفوترة البديل. كان معرّف المعاملة الأوّلي هو 123-456-789.
2. يُبلغ المطوِّر عن تكرار المعاملة في مَعلمة طلب البحث في عنوان URL باعتباره معرّف المعاملة الخارجية لهذه المعاملة الجديدة، مع الإشارة إلى معرّف المعاملة الخارجية للمعاملة الأولية في الحقل initialExternalTransactionId.

مثال على الطلب:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

الإبلاغ عن ترقية أو الرجوع إلى إصدار سابق

للإبلاغ عن ترقية أو تخفيض مستوى عندما يكون لدى المستخدم اشتراك في نظام الفوترة البديل، عليك استخدام نقطة النهاية والدالة نفسها في واجهة برمجة التطبيقات Externaltransactions، وإرسال externalTransactionToken الذي تم تقديمه إلى التطبيق لإجراء معاملة الترقية أو تخفيض المستوى. ويشبه ذلك الإبلاغ عن عملية شراء جديدة.

الإبلاغ عن تنزيل تطبيق

للإبلاغ عن عملية تثبيت تطبيق في نظام فوترة العروض الترويجية الخارجية، عليك استدعاء Externaltransactions.createexternaltransaction وإرسال externalTransactionToken الذي تم تقديمه إلى التطبيق. سجِّل هذه العملية كمعاملة لمرة واحدة بدون تكلفة، وتتشابه هذه العملية مع الإبلاغ عن معاملة أولية. احرص على تضمين ExternalOfferDetails في نص الطلب.

مثال على الطلب:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
"transactionTime" : "2025-12-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": "my_token",
 },
 "userTaxAddress" : {
   "regionCode": "US"
 }
 "externalOfferDetails" : {
   "linkType" : "LINK_TO_APP_DOWNLOAD",
   "installedAppPackage" : "my.external.app",
   "installedAppCategory" : "APP"
 }
}

نقل البيانات من نظام إعداد التقارير اليدوي لمعاملات نظام الفوترة البديل

ملاحظة: سيتم إيقاف إعداد التقارير يدويًا عن نظام الفوترة البديل فقط ونظام الفوترة حسب اختيار المستخدم. لمزيد من التفاصيل حول المواعيد النهائية لنقل البيانات، يُرجى الاطّلاع على معلومات عن ميزة "الفوترة حسب اختيار المستخدم" على Google Play. يُرجى الحرص على نقل جميع الاشتراكات النشطة التي بدأت عندما كنت توفِّر نظام فوترة بديلاً غير مزود بميزة إعداد التقارير آليًا من خلال واجهة برمجة التطبيقات externaltransactions قبل إيقاف ميزة إعداد التقارير يدويًا.

لنقل بيانات الاشتراكات النشطة التي بدأت عندما كنت توفِّر نظام فوترة بديلاً غير مزود بميزة إعداد التقارير آليًا، أنشئ معاملة جديدة بدون تكلفة باستخدام الحقل migratedTransactionProgram بدلاً من تحديد initialExternalTransactionId أو externalTransactionToken. اضبط قيمة transactionTime على الوقت الذي اشترك فيه المستخدم لأول مرة في كل اشتراك نشط. بعد ذلك، أبلِغ عن كل معاملة لاحقة لهذه الاشتراكات كالمعتاد من خلال واجهات برمجة التطبيقات، مع تقديم initialExternalTransactionId الذي تم استخدامه سابقًا لإنشاء معاملات التجديد. بعد نقل الاشتراك، لن تحتاج إلى إعداد تقارير يدويًا عن المعاملات اللاحقة للاشتراك، شرط أن يتم إعداد التقارير من خلال الطرق الآلية الموضّحة في هذه الصفحة.

أثناء نقل الاشتراكات، يجب الانتباه إلى حدود الحصة المحدّدة للتأكّد من أنّ عملية النقل لن تؤدي إلى انقطاع الحصة. إذا كان عليك نقل عدد كبير من الاشتراكات، يمكنك توزيعها على عدة أيام أو طلب زيادة في الحصة.

ملاحظة: لن يتمكّن من ضبط الحقل migratedTransactionProgram سوى المطوّرين الذين وفّروا نظام فوترة بديلاً بدون إعداد التقارير تلقائيًا. إذا كنت قد وفّرت نظام فوترة بديلاً غير مزود بميزة إعداد التقارير آليًا في السابق وتلقّيت رسالة خطأ عند محاولة تقديم طلب لنقل الاشتراك، يمكنك التواصل مع فريق الدعم للحصول على المساعدة.

لا يمكن استخدام الحقل migratedTransactionProgram إلا عند نقل البيانات من نظام إعداد التقارير اليدوي. سيتم إيقافها نهائيًا عندما تتوقف إمكانية الإبلاغ يدويًا.

مثال على الطلب:

# Note that the externalTransactionId specified here will used to report
# subsequent transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

متطلبات برامج شركاء Play

على المطوّرين المشاركين في برامج الشركاء، مثل برنامج Play Media Experience، تقديم transaction_program_code عند الإبلاغ عن المعاملات الخارجية. إذا كنت مطوّرًا مؤهَّلاً، يُرجى التواصل مع مدير تطوير الأعمال للحصول على مزيد من المعلومات حول كيفية ضبط هذا الحقل.

إبلاغ Google Play بعمليات ردّ الأموال المدفوعة في عمليات الشراء

يمكنك الدمج مع واجهة برمجة التطبيقات externaltransactions لإعداد تقارير عن المعاملات التي تم ردّ أموالها إلى المستخدمين خارج نظام الفوترة في Google Play. لكي يتمكّن Play من تحديد المعاملة التي تم ردّ أموالها بشكل صحيح، عليك تضمين externalTransactionId المقابل للمعاملة التي تم الإبلاغ عنها سابقًا كجزء من مَعلمات عنوان URL.

عند إعداد تقارير عن عمليات ردّ الأموال المدفوعة مقابل عمليات شراء الاشتراكات، يُرجى الرجوع إلى externalTransactionId للتكرار المحدّد للاشتراك الذي يتم ردّ الأموال المدفوعة مقابله.

مثال: لنفترض أنّ أحد الاشتراكات يتضمّن المعاملات التالية:

• معاملة أولية تتضمّن معرّف المعاملة الخارجية ABC.1234-5678-9012-34567

• أول معاملة متكرّرة تحمل معرّف معاملة خارجيًا ABC.1234-5678-9012-34567..0

• المعاملة المتكرّرة الثانية التي تحمل معرّف المعاملة الخارجية ABC.1234-5678-9012-34567..1

للإبلاغ عن استرداد أموال جميع معاملات الاشتراك، عليك تقديم ثلاثة طلبات منفصلة لاسترداد الأموال، أحدها للمعاملة الأولية واثنان للمعاملات اللاحقة.

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

حصص واجهة برمجة التطبيقات

تخضع واجهة برمجة التطبيقات Externaltransactions للحصص المفروضة على واجهات برمجة التطبيقات في جميع الطلبات، تمامًا مثل أي نقطة نهاية أخرى في Google Play Developer API.

بالإضافة إلى ذلك، تفرض واجهة برمجة التطبيقات Externaltransactions حدًا أقصى يبلغ 1,200 طلب في الدقيقة على الطلبات التي يتم إرسالها إلى Externaltransactions.createexternaltransaction أو Externaltransactions.refundexternaltransaction. لا يتم احتساب المكالمات إلى Externaltransactions.getexternaltransaction ضمن الحدّ الأقصى البالغ 1,200 طلب بحث في الدقيقة.