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

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

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

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

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

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

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

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

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

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

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

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

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

يجب توفير externalTransactionToken الذي يتلقّاه التطبيق من خلال عمليات الرجوع UserChoiceBillingListener أو AlternativeBillingOnlyReportingDetailsListener أو BillingProgramReportingDetailsListener كجزء من نص الطلب لعمليات تنزيل التطبيق وعمليات الشراء لمرة واحدة والمعاملات الأولى في عملية شراء متكرّرة (مثل الاشتراك). ويُعرف ذلك باسم المعاملة الأولية. بعد إجراء المعاملة الأولية، عليك إعداد تقارير عن المعاملات اللاحقة (مثل تجديد الاشتراكات) من خلال تقديم 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.
  • بعد تثبيت تطبيق خارجي من خلال برنامج العروض الترويجية الخارجية، عليك إعداد تقارير عن المعاملات التي تتم في التطبيق الخارجي. وعند إعداد تقارير عن هذه المعاملات، عليك ربطها بحدث تنزيل التطبيق الأصلي باتّباع الخطوات التالية:
    • قدِّم 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"
 }
}

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

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

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

لا يمكن استخدام الحقل 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 طلب في الدقيقة.