يوضّح هذا المستند كيفية دمج واجهات برمجة التطبيقات في Play Billing Library لتقديم خيار الدفع خارج التطبيق في التطبيقات المؤهَّلة. لمزيد من المعلومات حول هذا البرنامج، يُرجى الاطّلاع على متطلبات البرنامج.
إعداد Play Billing Library
أضِف تبعية Play Billing Library إلى تطبيق Android. لاستخدام واجهات برمجة التطبيقات لعمليات الدفع الخارجية، عليك استخدام الإصدار 8.3 أو إصدار أحدث. إذا كنت بحاجة إلى نقل البيانات من إصدار سابق، اتّبِع التعليمات الواردة في دليل نقل البيانات للترقية قبل بدء عملية الدمج.
تهيئة عميل الفوترة
تتطابق الخطوات الأولى في عملية الدمج مع الخطوات الموضّحة في دليل دمج نظام الفوترة في Google Play، مع بعض التعديلات عند تهيئة BillingClient:
- عليك استدعاء طريقة جديدة
enableBillingProgram(EnableBillingProgramParams)للإشارة إلى أنّك تريد تقديم خيار الدفع خارج التطبيق. - عليك تسجيل
DeveloperProvidedBillingListenerلـ معالجة الحالات التي يختار فيها المستخدم الدفع على موقعك الإلكتروني أو في تطبيق دفع.
يوضّح المثال التالي كيفية تهيئة BillingClient مع هذه التعديلات:
Kotlin
val purchasesUpdatedListener =
PurchasesUpdatedListener { billingResult, purchases ->
// Handle new Google Play purchase.
}
val developerProvidedBillingListener =
DeveloperProvidedBillingListener { details ->
// Handle user selection for developer provided billing option.
}
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(developerProvidedBillingListener)
.build())
.build()
Java
private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
@Override
public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
// Handle new Google Play purchase.
}
};
private DeveloperProvidedBillingListener developerProvidedBillingListener =
new DeveloperProvidedBillingListener() {
@Override
public void onUserSelectedDeveloperBilling(
DeveloperProvidedBillingDetails details) {
// Handle user selection for developer provided billing option.
}
};
private BillingClient billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(developerProvidedBillingListener)
.build())
.build();
الربط بخدمة Google Play
بعد تهيئة BillingClient، يمكنك الربط بخدمة Google Play كما هو موضّح
في الربط بخدمة Google Play.
التحقّق من أهلية المستخدم
بعد الربط بخدمة Google Play، يمكنك التحقّق مما إذا كان المستخدم مؤهَّلاً للاشتراك في برنامج الدفع خارج التطبيق من خلال استدعاء الطريقة
isBillingProgramAvailableAsync(). تعرض هذه الطريقة الرمز
BillingResponseCode.OK إذا كان المستخدم مؤهَّلاً.
يوضّح المثال التالي كيفية التحقّق من الأهلية:
Kotlin
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_PAYMENTS,
object : BillingProgramAvailabilityListener {
override fun onBillingProgramAvailabilityResponse(
billingProgram: Int, billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external payments unavailable, etc.
return
}
// External payments are available. Can proceed with generating an
// external transaction token.
})
Java
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_PAYMENTS,
new BillingProgramAvailabilityListener() {
@Override
public void onBillingProgramAvailabilityResponse(
int billingProgram, BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external payments unavailable, etc.
return;
}
// External payments are available. Can proceed with generating an external transaction token.
}
});
يُرجى الاطّلاع على قسم معالجة الردود للحصول على تفاصيل حول كيفية استجابة تطبيقك لرموز الاستجابة الأخرى. إذا كنت تستخدم إضافات Kotlin، يمكنك استخدام كوروتين Kotlin حتى لا تضطر إلى تحديد متتبِّع منفصل.
عرض المنتجات المتاحة
يمكنك عرض المنتجات المتاحة للمستخدم بالطريقة نفسها التي تتّبعها عند دمج نظام الفوترة في Google Play. عندما يرى المستخدم المنتجات المتاحة للشراء ويختار أحدها، ابدأ مسار الدفع خارج التطبيق كما هو موضّح في قسم بدء مسار الدفع خارج التطبيق.
إعداد رمز مميّز لمعاملة خارجية
للإبلاغ عن معاملة خارجية إلى Google Play، يجب أن يكون لديك رمز مميّز لمعاملة خارجية تم إنشاؤه من Play Billing Library. يجب إنشاء رمز مميّز جديد لمعاملة خارجية في كل مرة يزور فيها المستخدم موقعًا إلكترونيًا أو تطبيقًا خارجيًا من خلال واجهة برمجة التطبيقات لعمليات الدفع الخارجية. يمكن إجراء ذلك من خلال استدعاء
واجهة برمجة التطبيقات createBillingProgramReportingDetailsAsync. يجب إنشاء الرمز المميّز قبل استدعاء `launchBillingFlow` مباشرةً.
Kotlin
val params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.build()
billingClient.createBillingProgramReportingDetailsAsync(
params,
object : BillingProgramReportingDetailsListener {
override fun onCreateBillingProgramReportingDetailsResponse(
billingResult: BillingResult,
billingProgramReportingDetails: BillingProgramReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
billingProgramReportingDetails?.externalTransactionToken
// Persist the external transaction token locally. Pass it to
// the external website using DeveloperBillingOptionParams when
// launchBillingFlow is called.
}
})
Java
BillingProgramReportingDetailsParams params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.build();
billingClient.createBillingProgramReportingDetailsAsync(
params,
new BillingProgramReportingDetailsListener() {
@Override
public void onCreateBillingProgramReportingDetailsResponse(
BillingResult billingResult,
@Nullable BillingProgramReportingDetails
billingProgramReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
billingProgramReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to
// the external website using DeveloperBillingOptionParams when
// launchBillingFlow is called.
}
});
إذا كنت تستخدم إضافات Kotlin، يمكنك استخدام كوروتينات Kotlin حتى لا تضطر إلى تحديد متتبِّع منفصل.
بدء مسار الدفع خارج التطبيق
ابدأ مسار الدفع خارج التطبيق من خلال استدعاء launchBillingFlow()
بطريقة مشابهة لـ بدء مسار شراء عند دمج نظام الفوترة في Google Play، ولكن مع توفير مَعلمة إضافية
DeveloperBillingOptionParams تشير إلى أنّ تطبيقك يريد تفعيل مسار الدفع خارج التطبيق لعملية الشراء هذه.
يجب أن يحتوي DeveloperBillingOptionParams على ما يلي:
billingProgramمضبوط على برنامج الفوترةEXTERNAL_PAYMENTSlinkURIمضبوط على وجهة الرابطlaunchModeمضبوط علىLAUNCH_IN_EXTERNAL_BROWSER_OR_APPإذا كان على Google Play بدء الرابط، أوCALLER_WILL_LAUNCH_LINKإذا كان تطبيقك سيبدأ الرابط.
عندما يستدعي تطبيقك launchBillingFlow() مع توفير DeveloperBillingOptionParams، يُجري نظام الفوترة في Google Play عملية التحقّق التالية:
- يتحقّق النظام مما إذا كان بلد المستخدم في Google Play بلدًا
يتيح الدفع خارج التطبيق (أي بلدًا متوافقًا). إذا كان بلد المستخدم في Google Play متوافقًا، يتحقّق Google Play مما إذا كانت ميزة الدفع خارج التطبيق مفعّلة استنادًا إلى إعدادات BillingClient وما إذا تم توفير
DeveloperBillingOptionParams.- إذا تم تفعيل ميزة الدفع خارج التطبيق، يعرض مسار الشراء تجربة المستخدم التي تتيح له اختيار نظام الفوترة.
- إذا لم يتم تفعيل ميزة الدفع خارج التطبيق، يعرض مسار الشراء تجربة المستخدم العادية لنظام الفوترة في Google Play، بدون خيار المستخدم.
- إذا لم يكن بلد المستخدم في Google Play بلدًا متوافقًا، يعرض مسار الشراء تجربة المستخدم العادية لنظام الفوترة في Google Play، بدون خيار المستخدم.
بلد المستخدم في Play هو بلد متوافق |
بلد المستخدم في Play ليس بلدًا متوافقًا |
|
ميزة الدفع خارج التطبيق مفعّلة (إعداد BillingClient وlaunchBillingFlow) |
يرى المستخدم تجربة المستخدم التي تتيح له اختيار نظام الفوترة |
يرى المستخدم تجربة المستخدم العادية لنظام الفوترة في Google Play |
ميزة الدفع خارج التطبيق غير مفعّلة (إما لم يتم تفعيلها أثناء إعداد BillingClient أو لم يتم توفير `DeveloperBillingOptionParams` لـ `launchBillingFlow`) |
يرى المستخدم تجربة المستخدم العادية لنظام الفوترة في Google Play |
يرى المستخدم تجربة المستخدم العادية لنظام الفوترة في Google Play |
يوضّح المقتطف التالي كيفية إنشاء DeveloperBillingOptionParams:
Kotlin
val developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build()
Java
DeveloperBillingOptionParams developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build();
معالجة خيار المستخدم
تختلف طريقة معالجة بقية مسار الشراء استنادًا إلى ما إذا اختار المستخدم نظام الفوترة في Google Play أو الدفع على موقعك الإلكتروني.
عندما يختار المستخدم الدفع على موقعك الإلكتروني أو في تطبيق دفع
إذا اختار المستخدم الدفع على موقعك الإلكتروني، يستدعي Google Play السمة
DeveloperProvidedBillingListener لإشعار التطبيق بأنّ المستخدم اختار
الدفع على موقعك الإلكتروني أو في تطبيق دفع. على وجه التحديد، يتم استدعاء الطريقة
onUserSelectedDeveloperBilling().
إذا ضبط تطبيقك launchMode على LAUNCH_IN_EXTERNAL_BROWSER_OR_APP، سيبدأ Google Play الرابط. إذا تم ضبط launchMode على CALLER_WILL_LAUNCH_LINK، يكون تطبيقك مسؤولاً عن بدء الرابط.
عند ربط المستخدمين بتطبيق دفع، تكون مسؤولاً عن التحقّق من أنّ المستخدم قد ثبَّت تطبيق الدفع على جهازه.
استخدِم هذا الرمز المميّز للإبلاغ عن أي معاملة ناتجة عن هذا الخيار كما هو موضّح في دليل دمج النظام الخلفي.
عندما يختار المستخدم نظام الفوترة في Google Play
إذا اختار المستخدم نظام الفوترة في Google Play، سيواصل عملية الشراء من خلال Google Play.
- يُرجى الاطّلاع على مقالة معالجة عمليات الشراء في دليل دمج المكتبة لمزيد من المعلومات حول كيفية معالجة عمليات الشراء الجديدة داخل التطبيق من خلال نظام الفوترة في Google Play.
- يُرجى الاطّلاع على مقالة الاشتراكات الجديدة في دليل إدارة الاشتراكات للحصول على إرشادات إضافية حول عمليات شراء الاشتراكات.
معالجة التغييرات في الاشتراك
بالنسبة إلى المطوّرين الذين يستخدمون خيار الدفع خارج التطبيق، يجب معالجة عمليات الشراء من خلال نظام الفوترة في Google Play أو الإبلاغ عنها باستخدام externalTransactionId، وذلك استنادًا إلى خيار المستخدم. يمكن إجراء تغييرات على الاشتراكات الحالية التي تمت معالجتها من خلال الموقع الإلكتروني للمطوّر من خلال نظام الفوترة نفسه حتى انتهاء صلاحيتها.
يوضّح هذا القسم كيفية معالجة بعض السيناريوهات الشائعة لتغيير الاشتراك.
مسارات الترقية والرجوع إلى إصدار سابق
يجب معالجة التغييرات في خطة الاشتراك، بما في ذلك مسارات الترقية والرجوع إلى إصدار سابق، بشكل مختلف استنادًا إلى ما إذا تم شراء الاشتراك في الأصل من خلال نظام الفوترة في Google Play أو من خلال الموقع الإلكتروني للمطوّر.
تتم معالجة الإضافات التي تعتمد على اشتراك حالي وتستخدم طريقة الدفع نفسها وتتطابق مع الرسوم المتكرّرة كترقيات. بالنسبة إلى الإضافات الأخرى، يجب أن يتمكّن المستخدمون من اختيار نظام الفوترة الذي يريدون استخدامه. ابدأ تجربة شراء جديدة باستخدام launchBillingFlow()، كما
هو موضّح في قسم بدء مسار الدفع خارج التطبيق.
الاشتراكات التي تم شراؤها من خلال الموقع الإلكتروني للمطوّر أو تطبيق دفع
بالنسبة إلى الاشتراكات التي تم شراؤها في الأصل من خلال الموقع الإلكتروني للمطوّر أو تطبيق دفع بعد أن اختار المستخدم نظام الفوترة، يجب أن ينتقل المستخدمون الذين يطلبون ترقية أو الرجوع إلى إصدار سابق من خلال الموقع الإلكتروني للمطوّر أو تطبيق دفع بدون المرور بتجربة اختيار نظام الفوترة مرة أخرى.
لإجراء ذلك، استدعِ الطريقة launchBillingFlow() عندما يطلب المستخدم ترقية أو الرجوع إلى إصدار سابق. بدلاً من تحديد مَعلمات أخرى ضمن العنصر
SubscriptionUpdateParams، استخدِم
setOriginalExternalTransactionId()، مع توفير رقم تعريف المعاملة الخارجية لعملية الشراء الأصلية.
يجب أيضًا توفير DeveloperBillingOptionParams في هذا الاستدعاء. لا يؤدي ذلك إلى عرض شاشة اختيار المستخدم، لأنّه يتم الاحتفاظ بخيار المستخدم لعملية الشراء الأصلية للترقيات والرجوع إلى إصدار سابق. عليك إنشاء
رمز مميّز جديد لمعاملة خارجية لهذه المعاملة كما هو موضّح هنا.
الاشتراكات التي تم شراؤها من خلال نظام الفوترة في Google Play
وبالمثل، يجب أن يتم توجيه المستخدمين الذين اشتروا اشتراكهم الحالي من خلال نظام الفوترة في Google Play's بعد خيار المستخدم إلى مسار الفوترة العادي في Google Play. يجب عدم ضبط DeveloperBillingOptionParams في استدعاء launchBillingFlow.
عمليات إلغاء الاشتراك واستعادته
يجب أن يتمكّن المستخدمون من إلغاء اشتراكهم في أي وقت. عندما يلغي المستخدم اشتراكًا، قد يتم تأجيل إنهاء الحق إلى نهاية الفترة المدفوعة. على سبيل المثال، إذا ألغى المستخدم اشتراكًا شهريًا في منتصف الشهر، قد يظل بإمكانه الوصول إلى الخدمة لمدة أسبوعَين تقريبًا حتى تتم إزالة إمكانية وصوله. خلال هذه الفترة، يظل الاشتراك نشطًا من الناحية الفنية، لذا يمكن للمستخدم استخدام الخدمة.
من الشائع أن يقرّر المستخدمون إلغاء عملية الإلغاء خلال هذه الفترة النشطة. في هذا الدليل، يُطلق على هذه العملية اسم الاستعادة. توضّح الأقسام التالية كيفية معالجة سيناريوهات الاستعادة في عملية دمج واجهة برمجة التطبيقات لعمليات الدفع الخارجية.
الاشتراكات التي تم شراؤها من خلال الموقع الإلكتروني للمطوّر
إذا كان لديك رقم تعريف معاملة خارجية لاشتراك تم إلغاؤه، ليس من الضروري استدعاء launchBillingFlow() لاستعادة الاشتراك، لذا يجب عدم استخدامه لهذا النوع من التفعيل. إذا استعاد المستخدم اشتراكه أثناء الفترة النشطة لاشتراك تم إلغاؤه، لا تحدث أي معاملة في ذلك الوقت. يمكنك فقط مواصلة الإبلاغ عن عمليات التجديد عند انتهاء الدورة الحالية وحدوث عملية التجديد التالية. ويشمل ذلك الحالات التي يحصل فيها المستخدم على رصيد أو سعر تجديد خاص كجزء من عملية الاستعادة (على سبيل المثال، عرض ترويجي لتشجيع المستخدم على مواصلة اشتراكه).
الاشتراكات التي تم شراؤها من خلال نظام الفوترة في Google Play
بشكل عام، يمكن للمستخدمين استعادة الاشتراكات على نظام الفوترة في Google Play. بالنسبة إلى الاشتراكات التي تم إلغاؤها والتي تم شراؤها في الأصل من خلال نظام الفوترة في Google Play's ، قد يختار المستخدم التراجع عن عملية الإلغاء أثناء تفعيل الاشتراك من خلال ميزة إعادة الاشتراك في Google Play's. في هذه الحالة، تتلقّى إشعارًا فوريًا للمطوّرين من النوع SUBSCRIPTION_RESTARTED في نظامك الخلفي، ولا يتم إصدار رمز مميّز جديد للشراء، بل يتم استخدام الرمز المميّز الأصلي لمواصلة الاشتراك. للتعرّف على كيفية إدارة عملية الاستعادة في نظام الفوترة في Google Play، يُرجى الاطّلاع على مقالة عمليات الاستعادة في الـ دليل إدارة الاشتراكات.
يمكنك أيضًا بدء عملية استعادة في نظام الفوترة في Google Play من التطبيق من خلال استدعاء launchBillingFlow(). يُرجى الاطّلاع على مقالة
قبل انتهاء صلاحية الاشتراك - داخل التطبيق للحصول على شرح حول كيفية إجراء
ذلك. في حالة المستخدمين الذين اتّبعوا مسار اختيار المستخدم لعملية الشراء الأصلية (التي تم إلغاؤها ولكنها لا تزال نشطة)، يرصد النظام تلقائيًا خيارهم ويعرض واجهة المستخدم لاستعادة عمليات الشراء هذه. يُطلب منهم تأكيد إعادة شراء الاشتراك من خلال Google Play، ولكن ليس عليهم اتّباع مسار اختيار نظام الفوترة مرة أخرى. يتم إصدار رمز مميّز جديد للشراء للمستخدم في هذه الحالة.
يتلقّى نظامك الخلفي إشعارًا فوريًا للمطوّرين من النوع SUBSCRIPTION_PURCHASED، ويتم ضبط قيمة `linkedPurchaseToken` لحالة الشراء الجديدة كما هو الحال في الترقية أو الرجوع إلى إصدار سابق، مع الرمز المميّز القديم للشراء للاشتراك الذي تم إلغاؤه.
عمليات إعادة الاشتراك
إذا انتهت صلاحية الاشتراك تمامًا، سواء كان ذلك بسبب الإلغاء أو رفض الدفع بدون استرداد (فترة تعليق الاشتراك)، يجب على المستخدم إعادة الاشتراك إذا أراد إعادة تفعيل الحق.
يمكن أيضًا تفعيل إعادة الاشتراك من خلال التطبيق عن طريق معالجته بطريقة مشابهة لعملية الاشتراك العادية. يجب أن يتمكّن المستخدمون من اختيار نظام الفوترة الذي يريدون استخدامه. يمكن استدعاء launchBillingFlow() في هذه الحالة، كما هو
موضّح في قسم بدء مسار الدفع خارج التطبيق.
معالجة الردود
عند حدوث خطأ، قد تعرض الطرق isBillingProgramAvailableAsync() و
createBillingProgramReportingDetailsAsync() وlaunchBillingFlow() رمز BillingResponseCode غير BillingResponseCode.OK. يُرجى مراعاة معالجة رموز الاستجابة هذه على النحو التالي:
BillingResponseCode.ERROR: هذا خطأ داخلي. لا تتابع المعاملة أو فتح الموقع الإلكتروني الخارجي. أعِد المحاولة من خلال استدعاء واجهة برمجة التطبيقات مرة أخرى.BillingResponseCode.FEATURE_NOT_SUPPORTED: واجهات برمجة التطبيقات لعمليات الدفع الخارجية غير متاحة في متجر Play على الجهاز الحالي. لا تتابع المعاملة أو فتح الموقع الإلكتروني الخارجي.BillingResponseCode.DEVELOPER_ERROR: هناك خطأ في الطلب. استخدِم رسالة تصحيح الأخطاء لتحديد الخطأ وتصحيحه قبل المتابعة.BillingResponseCode.USER_CANCELED: لا تتابع فتح الموقع الإلكتروني أو التطبيق الخارجي. استدعِlaunchBillingFlow()مرة أخرى لعرض مربّع المعلومات للمستخدم في المرة التالية التي تحاول فيها توجيه المستخدم خارج التطبيق.BillingResponseCode.BILLING_UNAVAILABLE: المعاملة غير مؤهَّلة للدفع خارج التطبيق، وبالتالي لن يكون خيار الفوترة من قِبل المطوّر متاحًا بموجب هذا البرنامج. يرجع ذلك إما إلى أنّ المستخدم ليس في بلد مؤهَّل لهذا البرنامج أو لم يتم تسجيل حسابك بنجاح في البرنامج. إذا كان السبب هو الأخير، تحقَّق من حالة التسجيل في Play Console.BillingResponseCode.NETWORK_ERRORوBillingResponseCode.SERVICE_DISCONNECTEDوBillingResponseCode.SERVICE_UNAVAILABLE: هذه أخطاء مؤقتة يجب معالجتها باستخدام سياسة مناسبة لإعادة المحاولة. في حالةSERVICE_DISCONNECTED، أعِد إنشاء اتصال بخدمة Google Play قبل إعادة المحاولة.
اختبار روابط الدفع خارج التطبيق
يجب استخدام مختبِري الترخيص لاختبار عملية دمج خيار الدفع خارج التطبيق. لن يتم إصدار فاتورة لك مقابل المعاملات التي بدأتها حسابات مختبِري الترخيص. يُرجى الاطّلاع على مقالة اختبار الفوترة داخل التطبيقات من خلال ترخيص التطبيق لمزيد من المعلومات حول إعداد مختبِري الترخيص.
الخطوات التالية
بعد الانتهاء من عملية الدمج داخل التطبيق، يمكنك دمج نظامك الخلفي.