این سند نحوه ادغام کردن «میاناهای برنامهسازی کاربردی کتابخانه خدمات صورتحساب Play» را برای ارائه پرداختهای خارجی در برنامههای واجدشرایط شرح میدهد. برای کسب اطلاعات بیشتر درباره این برنامه، الزامات برنامه را ببینید.
راهاندازی «کتابخانه خدمات صورتحساب Play»
وابستگی «کتابخانه خدمات صورتحساب Play» را به برنامه Android خود اضافه کنید. برای استفاده از میاناهای برنامهسازی کاربردی پرداختهای برونسازمانی باید از نسخه ۸.۳ یا بالاتر استفاده کنید. اگر نیاز دارید از نسخه قدیمیتری انتقال دهید، برای ارتقا دادن قبلاز شروع یکپارچهسازی، دستورالعملهای راهنمای انتقال را دنبال کنید.
راهاندازی کارخواه صورتحساب
اولین مراحل در فرایند یکپارچهسازی همان مراحلی است که در راهنمای یکپارچهسازی «خدمات صورتحساب Google Play» توضیح داده شده است، با چند تغییر در هنگام راهاندازی BillingClient:
- برای نشان دادن اینکه میخواهید پرداختهای خارجی ارائه دهید، باید روش جدیدی
enableBillingProgram(EnableBillingProgramParams)را فراخوانی کنید. - باید
DeveloperProvidedBillingListenerرا برای رسیدگی به مواردی که کاربر انتخاب میکند در وبسایت شما یا برنامه پرداخت هزینه کند ثبت کنید.
مثال زیر نحوه مقداردهی اولیه کردن BillingClient با این اصلاحات را نشان میدهد:
کاتلین
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(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()) .enableBillingProgram( EnableBillingProgramParams.newBuilder() .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS) .setDeveloperProvidedBillingListener(developerProvidedBillingListener) .build() ) .build()
جاوا
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 را برمیگرداند.
نمونه زیر نحوه بررسی واجدشرایط بودن را نشان میدهد:
کاتلین
billingClient.isBillingProgramAvailableAsync( BillingProgram.EXTERNAL_PAYMENTS, object : BillingProgramAvailabilityListener { override fun onBillingProgramAvailabilityResponse( billingResult: BillingResult, billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails ) { 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. } } )
جاوا
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» تولید شده باشد. هر بار که کاربر ازطریق API پرداختهای خارجی از وبسایت یا برنامه خارجی بازدید میکند، باید یک کد تراکنش خارجی جدید تولید شود. این کار را میتوان با فراخوانی
میانای برنامهسازی کاربردی createBillingProgramReportingDetailsAsync انجام داد. رمز باید بلافاصله قبلاز فراخوانی launchBillingFlow تولید شود.
کاتلین
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. } } )
جاوا
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_PAYMENTSتنظیم شد -
linkURIروی مقصد پیوند تنظیم شد - اگر Google Play باید پیوند را راهاندازی کند،
launchModeرا رویLAUNCH_IN_EXTERNAL_BROWSER_OR_APPتنظیم کنید یا اگر برنامه شما پیوند را راهاندازی میکند، آن را رویCALLER_WILL_LAUNCH_LINKتنظیم کنید.
وقتی برنامه شما launchBillingFlow() را با
DeveloperBillingOptionParams ارائهشده فرا میخواند، سیستم صورتحساب Google Play
بررسی زیر را انجام میدهد:
- سیستم بررسی میکند که آیا کشور Google Play کاربر کشوری است که از پرداختهای خارجی پشتیبانی میکند (یعنی کشوری پشتیبانیشده). اگر کشور کاربر در Google Play پشتیبانی شود، Google Play براساس پیکربندی BillingClient بررسی میکند که آیا پرداختهای خارجی فعال است یا نه و آیا
DeveloperBillingOptionParamsارائه شده است یا نه.- اگر پرداختهای خارجی فعال شده باشد، جریان خرید UX انتخاب کاربر را نشان میدهد.
- اگر پرداختهای خارجی فعال نباشند، جریان خرید تجربه کاربری استاندارد سیستم صورتحساب Google Play را بدون انتخاب کاربر نشان میدهد.
- اگر کشور کاربر در Google Play جزو کشورهای پشتیبانیشده نباشد، جریان خرید تجربه کاربری استاندارد سیستم صورتحساب Google Play را بدون انتخاب کاربر نشان میدهد.
کشور Play کاربر جزو کشورهای پشتیبانیشده باشد |
کشور Play کاربر جزو کشورهای پشتیبانیشده نیست |
|
پرداختهای خارجی فعال شد (راهاندازی BillingClient و راهاندازی BillingFlow) |
کاربر «تجربه کاربری انتخاب کاربر» را میبیند |
کاربر تجربه کاربری استاندارد سیستم صورتحساب Google Play را میبیند |
پرداختهای خارجی فعال نشده است (یا درطول راهاندازی BillingClient فعال نشده است یا DeveloperBillingOptionParams برای راهاندازی BillingFlow ارائه نشده است) |
کاربر تجربه کاربری استاندارد سیستم صورتحساب Google Play را میبیند |
کاربر تجربه کاربری استاندارد سیستم صورتحساب Google Play را میبیند |
تکهکد زیر نحوه ساختن
DeveloperBillingOptionParams را نشان میدهد:
کاتلین
val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder() .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS) .setLinkUri("https://www.example.com/external/purchase".toUri()) .setLaunchMode( DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP ) .build()
جاوا
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 خریداری کردهاند باید روند سیستم صورتحساب استاندارد Google Play را طی کنند. DeveloperBillingOptionParams نباید در تماس با launchBillingFlow تنظیم شود.
لغو و بازگرداندن اشتراک
کاربران باید بتوانند اشتراک خود را در هر زمانی لغو کنند. وقتی کاربری اشتراکی را لغو میکند، ممکن است خاتمه مجوز تا پایان دوره پرداخت بهتعویق بیفتد. برای مثال، اگر کاربری اشتراک ماهانهای را در اواسط ماه لغو کند، ممکن است تا زمان برداشته شدن دسترسیاش همچنان به سرویس دسترسی داشته باشد. درطول این دوره، اشتراک همچنان ازنظر فنی فعال است، بنابراین کاربر میتواند از سرویس استفاده کند.
این غیرمعمول نیست که کاربران درطول این دوره فعال تصمیم بگیرند لغو را برگردانند. در این راهنما، این کار «بازیابی» نامیده میشود. بخشهای زیر نحوه مدیریت سناریوهای بازیابی در ادغام API پرداختهای خارجی را شرح میدهد.
اشتراکهای خریداریشده ازطریق وبسایت توسعهدهنده
اگر شناسه تراکنش خارجی برای اشتراک لغوشده دارید، برای بازیابی اشتراک نیازی به تماس با launchBillingFlow() نیست، بنابراین نباید برای این نوع فعالسازی استفاده شود. اگر کاربری اشتراک خود را درحالیکه هنوز در دوره فعال اشتراک لغوشده است بازیابی کند، در آن زمان هیچ تراکنشی انجام نمیشود؛ شما میتوانید زمانی که چرخه فعلی منقضی شد و تمدید بعدی انجام شد، تمدیدها را گزارش کنید. این شامل مواردی میشود که کاربر بهعنوان بخشی از
بازیابی، اعتبار یا قیمت ویژه تمدید دریافت میکند (برای مثال، تبلیغی برای تشویق کاربر به ادامه اشتراک).
اشتراکهای خریداریشده ازطریق سیستم صورتحساب Google Play
بهطورکلی، کاربران میتوانند اشتراکها را در سیستم صورتحساب Google Play بازیابی کنند. برای اشتراکهای لغوشده که دراصل در سیستم صورتحساب Google Play خریداری شدهاند، کاربر میتواند درحالیکه اشتراک ازطریق ویژگی اشتراک مجدد در Google Play فعال است، لغو را واگرد کند. در این صورت، «اعلان توسعهدهنده همزمان» SUBSCRIPTION_RESTARTED را در پشتیبان خود دریافت میکنید و کد خرید جدیدی صادر نمیشود—از کد اصلی برای ادامه اشتراک استفاده میشود. برای آشنایی با نحوه مدیریت بازیابی در سیستم صورتحساب Google Play، بخش بازیابیها را در راهنمای مدیریت اشتراک ببینید.
همچنین میتوانید با فراخوانی launchBillingFlow()، بازگرداندن را در سیستم صورتحساب Google Play ازطریق برنامه راهاندازی کنید. برای توضیح نحوه انجام این کار، به
قبلاز انقضای اشتراک - درونبرنامه مراجعه کنید. در مورد کاربرانی که جریان انتخاب کاربر را برای خرید اصلی (که لغو شده اما هنوز فعال است) طی کردهاند، سیستم بهطور خودکار انتخاب آنها را تشخیص میدهد و واسط کاربر را برای بازیابی این خریدها نمایش میدهد. از آنها خواسته میشود که خرید مجدد اشتراک را ازطریق Google Play تأیید کنند، اما نیازی نیست که دوباره مراحل انتخاب کاربر را طی کنند. در این مورد، کد خرید جدیدی برای کاربر صادر میشود.
پشتیبان شما «اعلان توسعهدهنده بیدرنگ» SUBSCRIPTION_PURCHASED را دریافت میکند و مقدار linkedPurchaseToken برای وضعیت خرید جدید مانند ارتقا یا تنزل سطح، با کد خرید قدیمی برای اشتراکی که لغو شده است تنظیم میشود.
ازسرگیری اشتراکها
اگر اشتراکی بهطور کامل منقضی شود، چه بهدلیل لغو شدن باشد چه بهدلیل رد شدن پرداخت بدون امکان بازیابی (توقف حساب منقضیشده)، در این صورت کاربر باید دوباره مشترک شود تا بتواند مجوز را ازسر بگیرد.
همچنین میتوان ازطریق برنامه و با پردازش مشابه ثبتنام استاندارد، امکان اشتراک مجدد را فعال کرد. کاربران باید بتوانند سیستم صورتحساب موردنظرشان را انتخاب کنند. در این مورد، ممکن است launchBillingFlow() فراخوانده شود، همانطور که در راهاندازی جریان پرداختهای خارجی توضیح داده شده است.
اداره کردن پاسخ
وقتی خطایی رخ میدهد، روشهای isBillingProgramAvailableAsync() ،
createBillingProgramReportingDetailsAsync()، launchBillingFlow() ممکن است
BillingResponseCode دیگری بهجز BillingResponseCode.OK ارائه دهند. این کدهای پاسخ را بهصورت زیر مدیریت کنید:
BillingResponseCode.ERROR: این یک خطای داخلی است. تراکنش یا باز کردن وبسایت خارجی را ادامه ندهید. با تماس مجدد با API، دوباره امتحان کنید.BillingResponseCode.FEATURE_NOT_SUPPORTED: «میاناهای برنامهسازی کاربردی» پرداختهای خارجی در «فروشگاه Play» در دستگاه فعلی پشتیبانی نمیشود. تراکنش یا باز کردن وبسایت خارجی را ادامه ندهید.BillingResponseCode.DEVELOPER_ERROR: در این درخواست خطایی وجود دارد. قبلاز ادامه دادن، از پیام اشکالزدایی برای شناسایی و اصلاح خطا استفاده کنید.BillingResponseCode.USER_CANCELED: باز کردن وبسایت یا برنامه خارجی را ادامه ندهید. دفعه بعد که تلاش کردید کاربر را به خارج از برنامه هدایت کنید، دوباره باlaunchBillingFlow()تماس بگیرید تا چارگوش اطلاعات به کاربر نمایش داده شود.BillingResponseCode.BILLING_UNAVAILABLE: تراکنش برای پرداختهای خارجی واجدشرایط نیست و بنابراین صورتحساب توسعهدهنده تحت این برنامه دردسترس نخواهد بود. این امر یا به این دلیل است که کاربر در کشوری واجدشرایط برای این برنامه نیست یا حساب شما با موفقیت در این برنامه ثبتنام نشده است. اگر مورد دوم است، وضعیت ثبتنام خود را در Play Developer Console بررسی کنید.BillingResponseCode.NETWORK_ERROR،BillingResponseCode.SERVICE_DISCONNECTED،BillingResponseCode.SERVICE_UNAVAILABLE: این خطاها گذرا هستند و باید با خطمشی مناسبی برای تلاش مجدد مدیریت شوند. در موردSERVICE_DISCONNECTED، قبلاز تلاش مجدد، اتصال با Google Play را دوباره برقرار کنید.
پیوندهای پرداختهای خارجی آزمایشی
از آزمونگران پروانه باید برای آزمایش کردن یکپارچگی پرداختهای خارجی استفاده شود. برای تراکنشهایی که توسط حسابهای آزمایشگر پروانه آغاز شدهاند، صورتحساب دریافت نخواهید کرد. برای اطلاعات بیشتر درباره پیکربندی آزمونگران پروانه، آزمایش کردن خدمات صورتحساب درونبرنامه با پروانه برنامه را ببینید.
مراحل بعدی
پساز تکمیل ادغام درونبرنامهای، آماده ادغام زیرینه خود هستید.