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

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

هناك بعض المكونات التي قد تكون ضرورية للتعامل مع عمليات الشراء داخل التطبيق من الخلفية. لإنشاء الواجهة، عليك إعداد عملية دمج الخلفية كما هو موضح في ضبط واجهة برمجة تطبيقات 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"
 }
}

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

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

لنقل بيانات الاشتراكات النشطة التي بدأت عندما كنت توفِّر نظام فوترة بديلاً غير مزود بميزة إعداد التقارير آليًا، يمكنك إنشاء معاملة جديدة بدون تكلفة باستخدام الحقل 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"
 }
}

إبلاغ 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 API للحصص اليومية لواجهة برمجة التطبيقات لجميع المكالمات، تمامًا مثل أي نقطة نهاية أخرى في واجهة برمجة تطبيقات Google Play Developer API.

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