يصف هذا الدليل كيفية دمج واجهات برمجة التطبيقات لتقديم نظام فوترة بديل فقط (أي بدون خيار المستخدم) في التطبيقات المؤهَّلة. لمعرفة المزيد من المعلومات عن هذه البرامج ، بما في ذلك متطلبات الأهلية والنطاق الجغرافي، يُرجى الاطّلاع على مقالة لمحة عن نظام الفوترة البديل.
إعداد Play Billing Library
أضِف تبعية Play Billing Library إلى تطبيق Android. لاستخدام واجهات برمجة التطبيقات لنظام الفوترة البديل، عليك استخدام الإصدار 6.1 أو إصدارًا أحدث.
الربط بخدمة Google Play
تتطابق الخطوات الأولى في عملية التكامل مع الخطوات الموضّحة في دليل تكامل الفوترة في Google Play، مع إجراء بعض التعديلات عند تهيئة `BillingClient`:
- عليك استدعاء طريقة جديدة للإشارة إلى أنّ تطبيقك يستخدم نظام فوترة بديلاً فقط:
enableAlternativeBillingOnly.
يوضّح المثال التالي كيفية تهيئة BillingClient مع هذه التعديلات:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableAlternativeBillingOnly()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableAlternativeBillingOnly()
.build();
بعد تهيئة BillingClient، عليك إنشاء اتصال بخدمة
Google Play كما هو موضّح في دليل التكامل.
التحقّق من التوفّر
يجب أن يؤكّد تطبيقك توفّر نظام الفوترة البديل فقط من خلال استدعاء
isAlternativeBillingOnlyAvailableAsync.
ستعرض واجهة برمجة التطبيقات هذه BillingResponseCode.OK إذا كان نظام الفوترة البديل فقط متوفّرًا. يُرجى الرجوع إلى قسم معالجة الاستجابة للحصول على تفاصيل حول كيفية استجابة تطبيقك لرموز الاستجابة الأخرى.
Kotlin
billingClient.isAlternativeBillingOnlyAvailableAsync(object:
AlternativeBillingOnlyAvailabilityListener {
override fun onAlternativeBillingOnlyAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling alternative billing only being unavailable, etc.
return
}
// Alternative billing only is available. Continue with steps in
// the guide.
}
});
Java
billingClient.isAlternativeBillingOnlyAvailable(
new AlternativeBillingOnlyAvailabilityListener() {
@Override
public void onAlternativeBillingOnlyAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling alternative billing only being unavailable,
// etc.
return;
}
// Alternative billing only is available. Continue with steps in
// the guide.
}
});
مربّع حوار المعلومات للمستخدمين
لإجراء التكامل مع نظام فوترة بديل فقط، يجب أن يعرض تطبيقك المؤهَّل شاشة معلومات تساعد المستخدمين على فهم أنّ Google Play لن تدير الفوترة. يجب عرض شاشة المعلومات للمستخدمين من خلال استدعاء واجهة برمجة التطبيقات
showAlternativeBillingOnlyInformationDialog قبل بدء نظام الفوترة البديل في كل مرة. إذا سبق للمستخدم الموافقة على مربّع الحوار، لن يؤدي استخدام واجهة برمجة التطبيقات هذه عادةً إلى عرض مربّع الحوار مرة أخرى. قد يتم عرض مربّع الحوار مرة أخرى للمستخدم في حالات معيّنة، مثل إذا محا المستخدم ذاكرات التخزين المؤقت على جهازه.
Kotlin
// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;
val listener : AlternativeBillingOnlyInformationDialogListener =
AlternativeBillingOnlyInformationDialogListener {
override fun onAlternativeBillingOnlyInformationDialogResponse(
billingResult: BillingResult) {
// check billingResult
}
}
val billingResult =
billingClient.showAlternativeBillingOnlyInformationDialog(activity,
listener)
Java
// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;
AlternativeBillingOnlyInformationDialogListener listener =
new AlternativeBillingOnlyInformationDialogListener() {
@Override
public void onAlternativeBillingOnlyInformationDialogResponse(
BillingResult billingResult) {
// check billingResult
}
};
BillingResult billingResult =
billingClient.showAlternativeBillingOnlyInformationDialog(activity,
listener);
إذا عرضت هذه الطريقة BillingResponseCode.OK، يمكن لتطبيقك متابعة المعاملة. في حال عرض BillingResponseCode.USER_CANCELED ، يجب أن يستدعي تطبيقك showAlternativeBillingOnlyInformationDialog لعرض مربّع الحوار على المستخدم مرة أخرى. بالنسبة إلى رموز الاستجابة الأخرى، يُرجى الاطّلاع على قسم معالجة الاستجابة الاستجابة.
إبلاغ Google Play بالمعاملات
يجب إبلاغ Google Play بجميع المعاملات التي يتم إجراؤها من خلال نظام فوترة بديل يجب الإبلاغ عنها
إلى Google Play من خلال استدعاء Google Play Developer API من الخلفية خلال
24 ساعة، مع تقديم externalTransactionToken الذي يتم الحصول عليه باستخدام
واجهة برمجة التطبيقات الموضّحة أدناه. يجب إنشاء externalTransactionToken جديد لكل عملية شراء لمرة واحدة ولكل اشتراك جديد ولأي ترقية/تخفيض لاشتراك حالي. لمعرفة كيفية الإبلاغ عن معاملة بعد الحصول على
externalTransactionToken، يُرجى الاطّلاع على دليل التكامل مع الخلفية.
Kotlin
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
AlternativeBillingOnlyReportingDetailsListener {
override fun onAlternativeBillingOnlyTokenResponse(
billingResult: BillingResult,
alternativeBillingOnlyReportingDetails:
AlternativeBillingOnlyReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
alternativeBillingOnlyReportingDetails?
.externalTransactionToken
// Send transaction token to backend and report to Google Play.
}
});
Java
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
new AlternativeBillingOnlyReportingDetailsListener() {
@Override
public void onAlternativeBillingOnlyTokenResponse(
BillingResult billingResult,
@Nullable AlternativeBillingOnlyReportingDetails
alternativeBillingOnlyReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
alternativeBillingOnlyReportingDetails
.getExternalTransactionToken();
// Send transaction token to backend and report to Google Play.
}
});
معالجة الاستجابة
قد تعرض الطرق أعلاه isAlternativeBillingOnlyAvailableAsync(),
showAlternativeBillingOnlyInformationDialog() و
createAlternativeBillingOnlyReportingDetailsAsync() استجابات غير BillingResponseCode.OK في حال حدوث أخطاء. في ما يلي طريقة معالجة الأخطاء المقترَحة:
ERROR: هذا خطأ داخلي. لا تُتابع المعاملة. أعِد المحاولة من خلال استدعاءshowAlternativeBillingOnlyInformationDialog()لعرض مربّع حوار المعلومات على المستخدم في المرة التالية التي يحاول فيها إجراء عملية شراء.FEATURE_NOT_SUPPORTED: واجهات برمجة التطبيقات لنظام الفوترة البديل غير متاحة في "متجر Play" على الجهاز الحالي. لا تُتابع المعاملة.USER_CANCELED: لا تُتابع المعاملة. استدعِshowAlternativeBillingOnlyInformationDialog()مرة أخرى لعرض مربّع حوار المعلومات على المستخدم في المرة التالية التي يحاول فيها إجراء عملية شراء.BILLING_UNAVAILABLE: لا تكون المعاملة مؤهَّلة لنظام الفوترة البديل فقط، لذا يجب عدم متابعتها بموجب هذا البرنامج. يرجع ذلك إما إلى أنّ المستخدم ليس في بلد مؤهَّل لهذا البرنامج أو لم يتم تسجيل حسابك بنجاح في البرنامج. إذا كان السبب الأخير، تحقَّق من حالة التسجيل في Play Console.DEVELOPER_ERROR: هناك خطأ في الطلب. استخدِم رسالة تصحيح الأخطاء لتحديد الخطأ وتصحيحه قبل المتابعة.NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: هذه أخطاء مؤقتة يجب إعادة المحاولة في حال حدوثها. في حال حدوثSERVICE_DISCONNECTED، أعِد إنشاء اتصال بخدمة Google Play قبل إعادة المحاولة.
اختبار نظام الفوترة البديل
يجب استخدام مختبِري التراخيص لاختبار عملية تكامل نظام الفوترة البديل. لن يتم إصدار فاتورة لك مقابل المعاملات التي بدأتها حسابات مختبِري التراخيص. يُرجى الاطّلاع على مقالة اختبار الفوترة داخل التطبيقات من خلال ترخيص التطبيق لمزيد من المعلومات حول إعداد مختبِري التراخيص.
الخطوات التالية
بعد الانتهاء من التكامل داخل التطبيق، يمكنك دمج الخلفية.