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

واجهة برمجة تطبيقات مطوّر برامج Google Play تتضمن الآن ميزات إضافية لإعداد التقارير عن المعاملات من نظام فوترة بديل أو العروض الترويجية الخارجية. يصف هذا الدليل طريقة الإبلاغ عن بدائل لمعاملات الفوترة أو العروض الترويجية الخارجية

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

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

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

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

عليك الاتصال برقم "Externaltransactions API" للإبلاغ عن معاملة خارجية. بعد السماح بالدفع من خلال نظام الفوترة البديل أو نظام العروض الخارجية. وينطبق ذلك على جميع المعاملات، بما في ذلك المعاملات الأوّلية. والرسوم وعمليات التجديد وعمليات ردّ الأموال وغيرها يجب أن تكون جميع المعاملات والإبلاغ عنه خلال 24 ساعة من إجراء المعاملة.

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

الإبلاغ عن عملية شراء جديدة

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

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

ملاحظة: إعداد تقارير عن معاملة شراء باستخدام نظام الفوترة البديل فقط أو العروض الخارجية هي نفسها المذكورة أعلاه باستثناء حالة externalTransactionToken يتم الحصول عليها باستخدام الخطوات الموضحة في نظام الفوترة البديل فقط أو دليل العروض الترويجية الخارجية

إذا كنت تجري معاملة مع مستخدم مقيم في الهند حيث تختلف الضرائب حسب المنطقة الإدارية (مثل الولاية أو المقاطعة)، فاحرص على تضمين ضمن 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"
 }
}

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

وفي بعض الحالات، هناك أكثر من دفعة واحدة مرتبطة بالحساب عملية شراء خارجية (على سبيل المثال، عمليات تجديد الاشتراك أو إضافة رصيد إلى خطة الدفع المُسبَق). يمكنك إعداد تقارير عن هذه المعاملات اللاحقة باستخدام واجهة برمجة التطبيقات نفسها في 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 الذي المقدَّمة إلى التطبيق لإجراء معاملة الترقية أو الرجوع إلى إصدار سابق. يعمل هذا الإجراء طريقة مماثلة للإبلاغ عن عملية شراء جديدة

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

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

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

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

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

لا يمكن استخدام الحقل 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 API للإبلاغ عن المعاملات التي تم ردّ أموالها المستخدمين خارج نظام الفوترة في 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 API 1,200 طلب في الدقيقة (QPM) الحد المفروض على المكالمات إلى Externaltransactions.createexternaltransaction أو Externaltransactions.refundexternaltransaction المكالمات إلى لا يتم احتساب Externaltransactions.getexternaltransaction ضمن 1,200 QPM الحد.