این سند نحوه ادغام «کتابخانه خدمات صورتحساب Google Play» در برنامهتان را برای شروع فروش محصولات شرح میدهد.
طول عمر خرید
در اینجا جریان خرید معمولی برای خرید یکباره یا اشتراک آورده شده است.
- به کاربر نشان دهید چه چیزهایی میتواند بخرد.
- جریان خرید را راهاندازی کنید تا کاربر خرید را بپذیرد.
- خرید را در سرورتان درستیسنجی کنید.
- محتوا را به کاربر بدهید.
- تحویل محتوا را تأیید کنید. برای محصولات مصرفی، خرید را مصرف کنید تا کاربر بتواند دوباره آن محصول را خریداری کند.
اشتراکها بهطور خودکار تمدید میشوند تا زمانی که لغو شوند. اشتراک میتواند وضعیتهای زیر را داشته باشد:
- فعال: کاربر خوشحساب است و به اشتراک دسترسی دارد.
- لغوشده: کاربر لغو کرده است اما تا زمان انقضا همچنان دسترسی دارد.
- در مهلت ارفاقی: کاربر با مشکل پرداخت مواجه شده است اما همچنان دسترسی دارد درحالیکه Google درحال امتحان مجدد روش پرداخت است.
- تعلیق: کاربر با مشکل پرداخت مواجه شده است و دیگر دسترسی ندارد، درحالیکه Google درحال امتحان مجدد روش پرداخت است.
- موقتاً متوقفشده: کاربر دسترسی خود را موقتاً متوقف کرده است و تا زمانی که آن را ازسر نگیرد، دسترسی ندارد.
- منقضیشده: کاربر اشتراک را لغو کرده و دسترسی به آن را ازدست داده است. کاربر در زمان انقضا ریزشکرده درنظر گرفته میشود.
راهاندازی اتصال به Google Play
اولین قدم برای ادغام با سیستم صورتحساب Google Play، افزودن «کتابخانه صورتحساب Google Play» به برنامهتان و مقداردهی اولیه اتصال است.
افزودن وابستگی «کتابخانه خدمات صورتحساب Google Play»
وابستگی «کتابخانه خدمات صورتحساب Google Play» را به فایل build.gradle برنامهتان اضافه کنید، همانطور که نشان داده شده است:
شیک
dependencies { def billing_version = "9.1.0" implementation "com.android.billingclient:billing:$billing_version" }
کاتلین
dependencies { val billing_version = "9.1.0" implementation("com.android.billingclient:billing:$billing_version") }
اگر از Kotlin استفاده میکنید، ماژول KTX «کتابخانه خدمات صورتحساب Google Play» حاوی
افزونههای Kotlin و پشتیبانی از روالهای همزمان است که به شما امکان میدهد هنگام استفاده از
«کتابخانه خدمات صورتحساب Google Play»، به زبان اصطلاحی Kotlin بنویسید. برای گنجاندن این
افزونهها در پروژهتان، وابستگی زیر را به فایل
build.gradle برنامهتان اضافه کنید:
شیک
dependencies { def billing_version = "9.1.0" implementation "com.android.billingclient:billing-ktx:$billing_version" }
کاتلین
dependencies { val billing_version = "9.1.0" implementation("com.android.billingclient:billing-ktx:$billing_version") }
مقداردهی اولیه BillingClient
وقتی وابستگی به «کتابخانه خدمات صورتحساب Google Play» را اضافه کردید، باید
نمونه BillingClient را مقداردهی اولیه کنید. BillingClient میانای اصلی برای ارتباط بین «کتابخانه خدمات صورتحساب Google Play» و بقیه برنامه شما است. BillingClient روشهای راحتی را برای بسیاری از عملیاتهای رایج صورتحساب، هم بهصورت همزمان و هم ناهمزمان، ارائه میدهد. به موارد زیر
توجه کنید:
- توصیه میشود که در هر زمان فقط یک اتصال
BillingClientفعال باز داشته باشید تا از چندین فراخوانی برگشتیPurchasesUpdatedListenerبرای یک رویداد جلوگیری شود. - توصیه میشود وقتی برنامهتان راهاندازی میشود یا به پیشزمینه میآید، اتصالی برای BillingClient آغاز کنید تا مطمئن شوید برنامهتان خریدها را بهموقع پردازش میکند. این کار را میتوان بااستفاده از
ActivityLifecycleCallbacksثبتشده توسطregisterActivityLifecycleCallbacksو گوش دادن به onActivityResumed برای مقداردهی اولیه اتصال هنگام اولین تشخیص ازسرگیری فعالیت انجام داد. برای جزئیات بیشتر درباره اینکه چرا باید این روال مطلوب را دنبال کنید، به بخش پردازش خریدها مراجعه کنید. همچنین بهخاطر داشته باشید که وقتی برنامهتان بسته است، اتصال را قطع کنید.
برای ایجاد BillingClient، از newBuilder استفاده کنید. میتوانید هر بافتی را به
newBuilder() ارسال کنید و BillingClient از آن برای دریافت بافت برنامه استفاده میکند. یعنی
لازم نیست نگران نشت حافظه باشید. برای دریافت بهروزرسانیهای مربوط به خریدها، باید setListener را نیز فراخوانی کنید و ارجاعی به PurchasesUpdatedListener ارسال کنید. این شنونده بهروزرسانیهای مربوط به همه
خریدهای درون برنامهتان را دریافت میکند.
کاتلین
private val purchasesUpdatedListener = PurchasesUpdatedListener { billingResult, purchases -> // To be implemented in a later section. } private var billingClient = BillingClient.newBuilder(context) .setListener(purchasesUpdatedListener) // Configure other settings. .build()
جاوا
private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
@Override
public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
// To be implemented in a later section.
}
};
private BillingClient billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
// Configure other settings.
.build();
اتصال به Google Play
پساز ایجاد BillingClient، باید اتصالی به Google Play برقرار کنید.
برای اتصال به Google Play، با startConnection تماس بگیرید. فرایند اتصال
ناهمگام است و باید BillingClientStateListener را پیادهسازی کنید تا
پساز تکمیل راهاندازی کارخواه و آماده شدن آن برای
ارسال درخواستهای بیشتر، بازخوان دریافت کنید.
اگر اتصال مجدد خودکار سرویس را فعال نکردهاید، باید منطق تکرار مجدد را نیز برای مدیریت اتصالهای قطعشده به Google Play پیادهسازی کنید. برای پیادهسازی منطق تکرار،
روش فراخوانی onBillingServiceDisconnected() را لغو کنید و مطمئن شوید که
BillingClient روش startConnection() را برای اتصال مجدد به Google Play
قبلاز ایجاد درخواستهای بیشتر فراخوانی میکند. اگر اتصال مجدد خودکار سرویس را فعال کردهاید، میتوانید این روش را بهعنوان عملیات بیتأثیر پیادهسازی کنید.
مثال زیر نشان میدهد که چگونه اتصال را شروع کنید و آزمایش کنید که آماده استفاده است:
کاتلین
billingClient.startConnection(object : BillingClientStateListener { override fun onBillingSetupFinished(billingResult: BillingResult) { if (billingResult.responseCode == BillingResponseCode.OK) { // The BillingClient is ready. You can query purchases here. } } override fun onBillingServiceDisconnected() { // If automatic service reconnection is enabled, this can be left empty (no-op) // because the library handles retries. You can still use this for non-retry // tasks like logging or updating the UI to reflect a disconnected state. // Otherwise, try to restart the connection on the next request to // Google Play by calling the startConnection() method. } })
جاوا
billingClient.startConnection( new BillingClientStateListener() { @Override public void onBillingSetupFinished(BillingResult billingResult) { if (billingResult.getResponseCode() == BillingResponseCode.OK) { // The BillingClient is ready. You can query purchases here. // It's a good practice to query products after the connection is established. queryProductDetails(); } } @Override public void onBillingServiceDisconnected() { // Try to restart the connection on the next request to // Google Play by calling the startConnection() method. // This is automatically handled by the library when you call a method that requires a connection. } });
برقراری مجدد اتصال بهطور خودکار
با معرفی روش enableAutoServiceReconnection() در
BillingClient.Builder در نسخه ۸.۰.۰، «کتابخانه خدمات صورتحساب Play» اکنون میتواند
بهطور خودکار اتصال سرویس را مجدداً برقرار کند، اگر فراخوانی میانای برنامهسازی کاربردی درحالیکه
سرویس قطع است انجام شود. این امر میتواند به کاهش پاسخهای
SERVICE_DISCONNECTED منجر شود زیرا اتصال مجدد
بهصورت داخلی قبلاز برقراری تماس میانای برنامهسازی کاربردی انجام میشود.
نحوه فعال کردن اتصال مجدد خودکار
هنگام ساختن نمونه BillingClient، از روش
enableAutoServiceReconnection() در BillingClient.Builder برای
فعال کردن اتصال مجدد خودکار استفاده کنید.
کاتلین
val billingClient = BillingClient.newBuilder(context) .setListener(listener) .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()) .enableAutoServiceReconnection() // Add this line to enable reconnection .build()
جاوا
BillingClient billingClient = BillingClient.newBuilder(context)
.setListener(listener)
.enablePendingPurchases()
.enableAutoServiceReconnection() // Add this line to enable reconnection
.build();
نمایش محصولات دردسترس برای خرید
پساز برقراری اتصال به Google Play، آمادهاید تا محصولات دردسترس خود را جستجو کنید و آنها را به کاربرانتان نمایش دهید.
پرسوجو برای جزئیات محصول گام مهمی قبلاز نمایش محصولات به کاربران است، زیرا اطلاعات محصول بومیسازیشده را برمیگرداند. برای اشتراکها، بررسی کنید که نمایش محصولتان از همه خطمشیهای Play پیروی کند.
برای جستجوی جزئیات محصول یکباره، روش queryProductDetailsAsync را فراخوانی کنید. این روش میتواند چندین پیشنهاد ویژه را براساس پیکربندی محصول یکباره شما برگرداند. برای اطلاعات بیشتر، چند گزینه خرید و پیشنهاد ویژه
برای محصولات یکباره را ببینید.
برای مدیریت نتیجه عملیات ناهمگام، باید شنوندهای را نیز مشخص کنید که میانای ProductDetailsResponseListener را پیادهسازی کند.
سپس میتوانید onProductDetailsResponse را لغو کنید، که وقتی پُرسمان تمام میشود به شنونده اطلاع میدهد، همانطور که در مثال زیر نشان داده شده است:
کاتلین
val queryProductDetailsParams = QueryProductDetailsParams.newBuilder() .setProductList( listOf( Product.newBuilder() .setProductId("product_id_example") .setProductType(ProductType.SUBS) .build() ) ) .build() billingClient.queryProductDetailsAsync(queryProductDetailsParams) { billingResult, queryProductDetailsResult -> if (billingResult.responseCode == BillingResponseCode.OK) { for (productDetails in queryProductDetailsResult.productDetailsList) { // Process successfully retrieved product details here. } for (unfetchedProduct in queryProductDetailsResult.unfetchedProductList) { // Handle any unfetched products as appropriate. } } }
جاوا
QueryProductDetailsParams queryProductDetailsParams =
QueryProductDetailsParams.newBuilder()
.setProductList(
ImmutableList.of(
Product.newBuilder()
.setProductId("product_id_example")
.setProductType(ProductType.SUBS)
.build()))
.build();
billingClient.queryProductDetailsAsync(
queryProductDetailsParams,
new ProductDetailsResponseListener() {
public void onProductDetailsResponse(BillingResult billingResult,
QueryProductDetailsResult queryProductDetailsResult) {
if (billingResult.getResponseCode() == BillingResponseCode.OK) {
for (ProductDetails productDetails : queryProductDetailsResult.getProductDetailsList()) {
// Process successfully retrieved product details here.
}
for (UnfetchedProduct unfetchedProduct : queryProductDetailsResult.getUnfetchedProductList()) {
// Handle any unfetched products as appropriate.
}
}
}
}
)
هنگام پرسمان برای جزئیات محصول، نمونهای از
QueryProductDetailsParams را ارسال کنید که فهرستی از رشتههای شناسه محصول
ایجادشده در «کنسول Google Play» را بههمراه ProductType مشخص میکند. ProductType میتواند ProductType.INAPP برای محصولات یکباره یا ProductType.SUBS برای اشتراکها باشد.
پرسمان با افزونههای Kotlin
اگر از افزونههای Kotlin استفاده میکنید، میتوانید با فراخوانی تابع افزونه queryProductDetails()، جزئیات محصول یکباره را جستجو کنید.
queryProductDetails() از کوروتینهای Kotlin استفاده میکند تا نیازی به تعریف شنونده جداگانه نداشته باشید. درعوض، تابع تا زمانی که پُرسمان تکمیل شود تعلیق میشود،
و پساز آن میتوانید نتیجه را پردازش کنید:
suspend fun processPurchases() { val productList = listOf( QueryProductDetailsParams.Product.newBuilder() .setProductId("product_id_example") .setProductType(BillingClient.ProductType.SUBS) .build() ) val params = QueryProductDetailsParams.newBuilder() params.setProductList(productList) // leverage queryProductDetails Kotlin extension function val productDetailsResult = withContext(Dispatchers.IO) { billingClient.queryProductDetails(params.build()) } // Process the result. }
بهندرت، برخیاز دستگاهها نمیتوانند از ProductDetails و queryProductDetailsAsync() پشتیبانی کنند، معمولاً بهدلیل قدیمی بودن نسخههای خدمات Google Play. برای ارائه پشتیبانی مناسب برای این سناریو، با نحوه استفاده از ویژگیهای سازگاری با نسخههای قدیمی در راهنمای انتقال به «کتابخانه خدمات صورتحساب Play» نسخه ۷ آشنا شوید.
پردازش نتیجه
«کتابخانه خدمات صورتحساب Google Play» نتایج پُرسمان را در شیء
QueryProductDetailsResult ذخیره میکند. QueryProductDetailsResult
حاوی List از اشیای ProductDetails است. سپس میتوانید روشهای مختلفی را در هر شیء ProductDetails در فهرست فراخوانی کنید تا اطلاعات مربوط به محصول یکبارهای را که با موفقیت واکشی شده است، مانند قیمت یا شرح آن، مشاهده کنید. برای مشاهده اطلاعات جزئیات محصول دردسترس،
فهرست روشها را در کلاس ProductDetails ببینید.
QueryProductDetailsResult همچنین حاوی List از
اشیاء UnfetchedProduct است. سپس میتوانید هر UnfetchedProduct را پُرسمان کنید
تا کد وضعیتی مطابق با دلیل عدم واکشی دریافت کنید.
برای مشاهده اطلاعات محصول واکشینشده دردسترس،
فهرست روشها را در کلاس UnfetchedProduct ببینید.
قبلاز ارائه محصول برای فروش، بررسی کنید که کاربر ازقبل مالک آن محصول نباشد. اگر کاربر محصول مصرفیای دارد که هنوز در کتابخانه محصول او است، باید آن محصول را مصرف کند تا بتواند دوباره آن را بخرد.
قبلاز ارائه اشتراک، بررسی کنید که کاربر ازقبل مشترک نشده باشد. همچنین به موارد زیر توجه کنید:
برای اشتراکها، روش
queryProductDetailsAsync()جزئیات محصول اشتراکی و حداکثر ۵۰ پیشنهاد ویژه واجدشرایط برای کاربر را بهازای هر اشتراک برمیگرداند. اگر کاربر تلاش کند پیشنهاد ویژهای را که واجدشرایط نیست خریداری کند (برای مثال، اگر برنامه فهرست قدیمیای از پیشنهادهای ویژه واجدشرایط را نمایش دهد)، Play به کاربر اطلاع میدهد که واجدشرایط نیست و کاربر میتواند بهجای آن طرح پایه را خریداری کند.برای محصولات یکباره، روش
queryProductDetailsAsync()فقط پیشنهادهای واجدشرایط کاربر را برمیگرداند. اگر کاربر تلاش کند پیشنهادی را خریداری کند که واجدشرایط آن نیست (برای مثال، اگر کاربر به حد تعداد خرید رسیده باشد)، Play به کاربر اطلاع میدهد که واجدشرایط نیست و کاربر میتواند بهجای آن، پیشنهاد گزینه خرید را خریداری کند.
راهاندازی جریان خرید
برای شروع درخواست خرید از برنامهتان، روش launchBillingFlow() را از رشته اصلی برنامهتان فراخوانی کنید. این روش ارجاعی به شیء
BillingFlowParams میگیرد که حاوی شیء
ProductDetails مربوطه است که از فراخوانی
queryProductDetailsAsync بهدست آمده است. برای ایجاد شیء BillingFlowParams، از
کلاس BillingFlowParams.Builder استفاده کنید.
کاتلین
// An activity reference from which the billing flow will be launched. val activity : Activity = ... val productDetailsParamsList = listOf( BillingFlowParams.ProductDetailsParams.newBuilder() // retrieve a value for productDetails by calling queryProductDetailsAsync() .setProductDetails(productDetails) // Get the offer token: // a. For one-time products, call ProductDetails.getOneTimePurchaseOfferDetailsList() // for a list of offers that are available to the user. // b. For subscriptions, call ProductDetails.getSubscriptionOfferDetails() // for a list of offers that are available to the user. .setOfferToken(selectedOfferToken) .build() ) val billingFlowParams = BillingFlowParams.newBuilder() .setProductDetailsParamsList(productDetailsParamsList) .build() // Launch the billing flow val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
جاوا
// An activity reference from which the billing flow will be launched. Activity activity = ...; ImmutableList<BillingFlowParams.ProductDetailsParams> productDetailsParamsList = ImmutableList.of( BillingFlowParams.ProductDetailsParams.newBuilder() // retrieve a value for "productDetails" by calling queryProductDetailsAsync() .setProductDetails(productDetails) // Get the offer token: // a. For one-time products, call ProductDetails.getOneTimePurchaseOfferDetailsList() // for a list of offers that are available to the user. // b. For subscriptions, call ProductDetails.getSubscriptionOfferDetails() // for a list of offers that are available to the user. .setOfferToken(selectedOfferToken) .build() ); BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder() .setProductDetailsParamsList(productDetailsParamsList) .build(); // Launch the billing flow BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);
روش launchBillingFlow() یکی از چند کد پاسخ فهرستشده در
BillingClient.BillingResponseCode را برمیگرداند. حتماً این نتیجه را بررسی کنید تا
مطمئن شوید که هیچ خطایی در راهاندازی جریان خرید وجود نداشته است. BillingResponseCode
OK نشاندهنده راهاندازی موفق است.
درصورت موفقیتآمیز بودن فراخوانی launchBillingFlow()، سیستم صفحه خرید Google Play را نمایش میدهد. شکل ۱ صفحه خرید اشتراک را نشان میدهد:
Google Play با onPurchasesUpdated() تماس میگیرد تا نتیجه عملیات خرید را به شنوندهای که رابط PurchasesUpdatedListener را پیادهسازی میکند ارائه دهد. شنونده بااستفاده از روش setListener() هنگام
راهاندازی مشتری مشخص میشود.
برای رسیدگی به کدهای پاسخ احتمالی باید onPurchasesUpdated() را پیادهسازی کنید. مثال زیر نشان میدهد که چگونه onPurchasesUpdated() را لغو کنید:
کاتلین
override fun onPurchasesUpdated(billingResult: BillingResult, purchases: List<Purchase>?) { if (billingResult.responseCode == BillingResponseCode.OK && purchases != null) { for (purchase in purchases) { // Process the purchase as described in the next section. } } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) { // Handle an error caused by a user canceling the purchase flow. } else { // Handle any other error codes. } }
جاوا
@Override
void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
if (billingResult.getResponseCode() == BillingResponseCode.OK
&& purchases != null) {
for (Purchase purchase : purchases) {
// Process the purchase as described in the next section.
}
} else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
// Handle an error caused by a user canceling the purchase flow.
} else {
// Handle any other error codes.
}
}
خرید موفقیتآمیز صفحه موفقیت خرید Google Play را مشابه شکل ۲ ایجاد میکند.
خرید موفق همچنین یک توکن خرید تولید میکند که یک شناسه یکتا است که کاربر و شناسه محصول را برای محصول یکبارهای که خریداری کردهاند نشان میدهد. برنامههایتان میتوانند توکن خرید را بهصورت محلی ذخیره کنند، اما ما اکیداً توصیه میکنیم توکن را به سرور زیرینه امن خود منتقل کنید تا بتوانید خرید را تأیید کنید و از کلاهبرداری جلوگیری کنید. این فرایند در شناسایی و پردازش خریدها بیشتر توضیح داده شده است.
همچنین رسید تراکنش حاوی «شناسه سفارش» یا شناسه یکتای تراکنش برای کاربر ایمیل میشود. کاربران برای هر خرید محصول یکباره و همچنین برای خرید اشتراک اولیه و تمدیدهای خودکار تکرارشونده بعدی، ایمیلی با «شناسه سفارش» منحصربهفرد دریافت میکنند. میتوانید از «شناسه سفارش» برای مدیریت استرداد مبلغ در «کنسول Google Play» استفاده کنید.
قیمت شخصیسازیشده را نشان دهید
اگر برنامهتان میتواند برای کاربران ساکن اتحادیه اروپا توزیع شود،
هنگام فراخوانی launchBillingFlow از روش setIsOfferPersonalized() استفاده کنید تا به کاربران اطلاع دهید
که قیمت محصول بااستفاده از تصمیمگیری خودکار شخصیسازی شده است.
باید به بند ماده ۶ (۱) (ea) از «دستور حقوق مصرفکننده» ۲۰۱۱/۸۳/EU برای تشخیص اینکه آیا قیمتی که به کاربران ارائه میدهید شخصی شده است یا نه.
setIsOfferPersonalized() ورودی بولی میگیرد. وقتی true، میانای کاربر Play
شامل شفافسازی است. وقتی false، میانای کاربر شفافسازی را حذف میکند. مقدار پیشفرض
false است.
برای اطلاعات بیشتر، به مرکز راهنمایی مصرفکننده مراجعه کنید.
پیوست کردن شناسههای کاربر
وقتی جریان خرید را راهاندازی میکنید، برنامهتان میتواند هر شناسه کاربری را که برای کاربر خریدار دارید بااستفاده از obfuscatedAccountId یا obfuscatedProfileId پیوست کند. یک شناسه نمونه میتواند نسخه مبهمی از ورود کاربر به سیستم شما باشد. تنظیم این پارامترها میتواند به Google کمک کند کلاهبرداری را شناسایی کند. علاوهبراین، میتواند به شما کمک کند مطمئن شوید که خریدها به کاربر مناسب نسبت داده شده است، همانطور که در اعطای حق استفاده به کاربران بحث شد.
شناسایی و پردازش خریدها
تشخیص و پردازش خرید شرحدادهشده در این بخش برای همه انواع خریدها، ازجمله خریدهای خارج از برنامه مانند پسخرید تبلیغات، قابلاجرا است.
برنامه شما خریدهای جدید و خریدهای معلقه تکمیلشده را به یکی از روشهای زیر شناسایی میکند:
- وقتی
onPurchasesUpdatedدرنتیجه فراخوانی برنامهتان فراخوانده میشودlaunchBillingFlow(همانطور که در بخش قبلی توضیح داده شد) یا اگر برنامهتان با اتصال فعال «کتابخانه خدمات صورتحساب» اجرا میشود، وقتی خریدی خارج از برنامهتان انجام میشود یا خرید معلقهای تکمیل میشود. برای مثال، یکی از اعضای خانواده خرید معلقه را در دستگاه دیگری تأیید میکند. - وقتی برنامهتان queryPurchasesAsync را برای پرسمان خریدهای کاربر فراخوانی میکند.
برای شماره ۱، تا زمانی که برنامهتان درحال اجرا باشد و اتصال فعال به «کتابخانه خدمات صورتحساب Google Play» داشته باشد، onPurchasesUpdated بهطور خودکار برای خریدهای جدید یا تکمیلشده فراخوانی میشود. اگر برنامه شما درحال اجرا نباشد یا برنامه شما اتصال فعال به کتابخانه «خدمات صورتحساب Google Play» نداشته باشد، onPurchasesUpdated فراخوانی نخواهد شد. بهیاد داشته باشید که توصیه میشود برنامهتان تا زمانی که در پیشنما است، اتصال فعال را حفظ کند تا بهروزرسانیهای خرید را بهموقع دریافت کند.
برای مورد ۲، باید BillingClient.queryPurchasesAsync() را فراخوانی کنید تا مطمئن شوید برنامهتان همه خریدها را پردازش میکند. توصیه میشود این کار را زمانی انجام دهید که برنامهتان با موفقیت با «کتابخانه خدمات صورتحساب Google Play» ارتباط برقرار میکند (که توصیه میشود زمانی انجام شود که برنامهتان راهاندازی میشود یا به پیشزمینه میآید، همانطور که در مقداردهی اولیه BillingClient بحث شد. این کار را میتوان با فراخوانی queryPurchasesAsync هنگام دریافت نتیجه موفقیتآمیز برای onServiceConnected انجام داد. دنبال کردن این توصیه برای رسیدگی به رویدادها و شرایطی مثل موارد زیر حیاتی است:
- مشکلات شبکه درطول خرید: کاربر میتواند خرید موفقی انجام دهد و تأییدیه را از Google دریافت کند، اما دستگاه او اتصال شبکه را قبلاز اینکه دستگاه و برنامه شما اعلان خرید را ازطریق
PurchasesUpdatedListenerدریافت کند، ازدست میدهد. - چند دستگاه: ممکن است کاربر محصولی را در یک دستگاه بخرد و سپس انتظار داشته باشد وقتی دستگاهش را عوض میکند، آن محصول را ببیند.
- مدیریت خریدهای انجامشده در خارج از برنامه: برخیاز خریدها، مثل پسخرید کردن تبلیغ، میتواند در خارج از برنامه انجام شود.
- مدیریت انتقالهای وضعیت خرید: ممکن است کاربر پرداخت خرید «معلقه» را زمانی تکمیل کند که برنامه شما درحال اجرا نیست و انتظار داشته باشد که هنگام باز کردن برنامه شما، تأییدیه تکمیل خرید را دریافت کند.
- اشتراکهای تعلیقشده: اشتراک ممکن است درطول چرخه حیات اشتراک تعلیق شود. BillingClient.queryPurchasesAsync()
فقط درصورتی اشتراکهای تعلیقشده را برمیگرداند که پارامتر
includeSuspendedSubscriptionsرویQueryPurchasesParams.Builderتنظیم شده باشد. اشتراکهای تعلیقشده درPurchasesUpdatedListenerبرگردانده نمیشوند.
وقتی برنامهتان خرید جدید یا تکمیلشدهای را شناسایی کرد، باید:
- خرید را بهتأیید برسانید.
- محتوا را برای خریدهای تکمیلشده به کاربر اعطا کنید.
- به کاربر اطلاع دهید.
- به Google اطلاع دهید که برنامهتان خریدهای تکمیلشده را پردازش کرده است.
این مراحل بهطور مفصل در بخشهای زیر توضیح داده شده است و سپس بخش خلاصه همه مراحل آمده است.
درستیسنجی خرید
برنامه شما باید همیشه قبلاز اعطای مزایا به کاربر، قانونی بودن خریدها را تأیید کند. این کار را میتوان با دنبال کردن دستورالعملهای شرحدادهشده در درستیسنجی خریدها قبلاز اعطای حقوق انجام داد. فقط پساز درستیسنجی خرید، برنامهتان باید به پردازش خرید و اعطای حق استفاده به کاربر ادامه دهد که در بخش بعدی توضیح داده شده است. اگر خریدی در بررسیهای درستیسنجی، واجدشرایط بودن، یا سوءاستفاده رد شد، به رسیدگی به خریدهای ردشده یا تکمیلنشده مراجعه کنید.
اعطای حق استفاده به کاربر
وقتی برنامهتان خریدی را تأیید کرد، میتواند به اعطای حق استفاده به کاربر ادامه دهد و به کاربر اطلاع دهد. قبلاز اعطای حق استفاده، مطمئن شوید که برنامهتان بررسی میکند که وضعیت خرید PURCHASED باشد. اگر خرید در وضعیت «درحال انتظار» باشد، برنامهتان باید به کاربر اطلاع دهد که هنوز باید اقداماتی را برای تکمیل خرید انجام دهد تا حق استفاده اعطا شود.
فقط زمانی حق استفاده را اعطا کنید که خرید از حالت «درحال انتظار» به «خریداریشده» تغییر کند.
اطلاعات بیشتر را میتوانید در رسیدگی به تراکنشهای معلق پیدا کنید.
اگر شناسههای کاربر را به خرید پیوست کردهاید، همانطور که در پیوست کردن شناسههای کاربر بحث شد، میتوانید آنها را بازیابی کنید و از آنها برای نسبت دادن به کاربر صحیح در سیستم خود استفاده کنید. این تکنیک هنگام تطبیق خریدها مفید است جایی که ممکن است برنامه شما زمینه مربوط به اینکه خرید برای کدام کاربر است را ازدست داده باشد. برای محافظت دربرابر سوءاستفاده، Google Play توصیه میکند که این شناسهها را پیشاز اعطای حقوق در پسای امن خود درستیسنجی کنید. برای اطلاعات بیشتر، درستیسنجی خریدها قبلاز اعطای حقوق را ببینید. توجه داشته باشید که خریدهای انجامشده خارج از برنامهتان این شناسهها را نخواهند داشت. در این حالت، برنامهتان میتواند حق استفاده را به کاربر واردشده به سیستم اعطا کند یا از کاربر بخواهد حساب ترجیحی را انتخاب کند.
برای پیشسفارشها، خرید قبلاز رسیدن زمان انتشار در وضعیت «درانتظار» است. خرید پیشسفارش در زمان انتشار تکمیل میشود و وضعیت آن بدون کنشهای اضافی به «خریداریشده» تغییر میکند.
اطلاعرسانی به کاربر
پساز اعطای حق استفاده به کاربر، برنامهتان باید اعلانی برای تأیید موفقیتآمیز بودن خرید نشان دهد. بهدلیل این اعلان، کاربر درباره اینکه خرید با موفقیت تکمیل شده است یا نه سردرگم نمیشود، که این امر میتواند منجر به توقف استفاده کاربر از برنامه شما، تماس با پشتیبانی کاربر، یا شکایت درباره آن در رسانههای اجتماعی شود. توجه داشته باشید که برنامهتان ممکن است بهروزرسانیهای خرید را در هر زمانی درطول چرخه حیات برنامهتان شناسایی کند. برای مثال، ولی خرید معلقهای را در دستگاه دیگری تأیید میکند، در این حالت ممکن است برنامهتان بخواهد اعلان به کاربر را تا زمان مناسبی بهتأخیر بیندازد. چند نمونه از مواردی که تأخیر در آنها مناسب است:
- درطول بخش اکشن بازی یا صحنههای برش، نمایش پیام ممکن است حواس کاربر را پرت کند. در این حالت، باید پساز پایان بخش اقدام به کاربر اطلاع دهید.
- درطول بخشهای آموزش اولیه و راهاندازی کاربر در بازی. برای مثال، ممکن است کاربری قبلاز نصب برنامهتان، خریدی خارج از آن انجام داده باشد. توصیه میکنیم بلافاصله پساز اینکه کاربران جدید بازی را باز کردند یا درطول راهاندازی اولیه کاربر، پاداش را به آنها اطلاع دهید. اگر برنامه شما کاربر را ملزم میکند قبلاز اعطای حق استفاده، حساب ایجاد کند یا به سیستم وارد شود، توصیه میشود به کاربرتان اطلاع دهید که برای مطالبه خریدش چه مراحلی را باید تکمیل کند. این موضوع بسیار مهم است زیرا اگر برنامهتان خرید را پردازش نکرده باشد، مبلغ خریدها پساز ۳ روز مسترد میشود.
هنگام اطلاعرسانی به کاربر درباره خرید، Google Play سازوکارهای زیر را توصیه میکند:
- کادر گفتگوی درونبرنامهای نشان دهید.
- پیام را به صندوق پیام درونبرنامه ارسال کنید و بهطور واضح بیان کنید که پیام جدیدی در صندوق پیام درونبرنامه وجود دارد.
- از پیام اعلان سیستمعامل استفاده کنید.
اعلان باید کاربر را از مزایایی که دریافت کرده است مطلع کند. برای مثال، «۱۰۰ سکه طلا خریدید!». علاوهبراین، اگر خرید نتیجه مزایای برنامهای مثل Play Pass باشد، برنامهتان این موضوع را به کاربر اطلاع میدهد. برای مثال «موارد دریافت شد! با Play Pass، ۱۰۰ «گوهر» دریافت کردید. ادامه دهید». هر برنامه ممکن است راهنمایی درباره نوشتار توصیهشده برای نمایش به کاربران جهت اطلاعرسانی مزایا داشته باشد.
به Google اطلاع دهید که خرید پردازش شده است
پساز اینکه برنامهتان حق استفاده را به کاربر اعطا کرد و او را از موفقیتآمیز بودن تراکنش مطلع کرد، برنامهتان باید به Google اطلاع دهد که خرید با موفقیت پردازش شده است. این کار با تأیید خرید انجام میشود و باید ظرف سه روز انجام شود تا خرید بهطور خودکار مسترد نشود و حق استفاده لغو نشود. فرایند تأیید انواع مختلف خرید در بخشهای زیر شرح داده شده است.
محصولات مصرفی
برای محصولات مصرفی، اگر برنامهتان باطن امنی دارد، توصیه میکنیم از
Purchases.products:consume برای مصرف مطمئن خریدها استفاده کنید. با بررسی consumptionState از نتیجه فراخوانی Purchases.products:get مطمئن شوید که خرید قبلاً مصرف نشده باشد. اگر برنامهتان فقط سمت کارخواه است و
سمت سرور ندارد، از consumeAsync() از
«کتابخانه خدمات صورتحساب Google Play» استفاده کنید. هر دو روش الزامات تأیید را برآورده میکنند و نشان میدهند که برنامه شما حق استفاده را به کاربر اعطا کرده است.
این روشها همچنین به برنامه شما امکان میدهند محصول یکباره مربوط به
ژتون خرید ورودی را برای خرید مجدد دردسترس قرار دهد. با consumeAsync() باید شیئی را نیز ارسال کنید که میانای ConsumeResponseListener را پیادهسازی کند. این شیء نتیجه عملیات مصرف را مدیریت میکند. میتوانید
روش onConsumeResponse() را لغو کنید، که
«کتابخانه خدمات صورتحساب Google Play» پساز تکمیل عملیات آن را فراخوانی میکند.
مثال زیر مصرف محصولی را بااستفاده از «کتابخانه خدمات صورتحساب Google Play» و بااستفاده از کد خرید مرتبط نشان میدهد:
کاتلین
val consumeParams = ConsumeParams.newBuilder() .setPurchaseToken(purchase.getPurchaseToken()) .build() val consumeResult = withContext(Dispatchers.IO) { client.consumePurchase(consumeParams) }
جاوا
ConsumeParams consumeParams = ConsumeParams.newBuilder().setPurchaseToken(purchase.getPurchaseToken()).build(); ConsumeResponseListener listener = (billingResult, purchaseToken) -> { if (billingResult.getResponseCode() == BillingResponseCode.OK) { // Handle the success of the consume operation. } }; billingClient.consumeAsync(consumeParams, listener);
محصولات غیرمصرفی
برای تأیید خریدهای غیرمصرفی، اگر برنامهتان باطن امنی دارد،
توصیه میکنیم از Purchases.products:acknowledge برای تأیید مطمئن
خریدها استفاده کنید. با بررسی acknowledgementState از نتیجه فراخوانی Purchases.products:get مطمئن شوید که خرید قبلاً تأیید نشده باشد.
اگر برنامهتان فقط مشتری است، از BillingClient.acknowledgePurchase() از
«کتابخانه خدمات صورتحساب Google Play» در برنامهتان استفاده کنید. قبلاز تأیید
خرید، برنامهتان باید بااستفاده از روش isAcknowledged() در «کتابخانه خدمات صورتحساب Google Play» بررسی کند که آیا خرید قبلاً تأیید شده است یا نه.
مثال زیر نشان میدهد که چگونه بااستفاده از «کتابخانه خدمات صورتحساب Google Play» خرید را تأیید کنید:
کاتلین
val client: BillingClient = billingClient val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder() .setPurchaseToken(purchase.purchaseToken) val ackPurchaseResult = withContext(Dispatchers.IO) { client.acknowledgePurchase(acknowledgePurchaseParams.build()) }
جاوا
if (purchase.getPurchaseState() == Purchase.PurchaseState.PURCHASED) { if (!purchase.isAcknowledged()) { AcknowledgePurchaseParams acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder() .setPurchaseToken(purchase.getPurchaseToken()) .build(); billingClient.acknowledgePurchase(acknowledgePurchaseParams, (billingResult) -> { // Acknowledgment handled. }); } }
اشتراکها
اشتراکها مشابه محصولات غیرمصرفی مدیریت میشوند. درصورت امکان، از
Purchases.subscriptions.acknowledge از
Google Play Developer API استفاده کنید تا خرید را بهطور مطمئن از
پشتبام امن خود تأیید کنید. با بررسی acknowledgementState در منبع خرید از Purchases.subscriptions:get، تأیید کنید که خرید قبلاً تأیید نشده باشد. درغیراینصورت، میتوانید پساز بررسی isAcknowledged()، اشتراک را بااستفاده از BillingClient.acknowledgePurchase() از «کتابخانه خدمات صورتحساب Google Play» تأیید کنید. همه
خریدهای اشتراک اولیه باید تأیید شوند. تمدید اشتراک
نیازی به تأیید ندارد. برای اطلاعات بیشتر درباره زمان اعلام کردن اشتراکها،
موضوع فروش اشتراک را ببینید.
رسیدگی به خریدهای ردشده یا تکمیلنشده
اگر خریدی درستیسنجی پسبک، بررسیهای واجدشرایط بودن کاربر، بررسیهای کلاهبرداری و سوءاستفاده را با موفقیت نگذراند، یا اگر سیستم شما نتواند حق استفاده را برآورده کند، حق استفاده را اعطا نکنید و خرید را تأیید یا مصرف نکنید.
درحالیکه خریدهای تأییدنشده پساز منقضی شدن پنجره تأیید بهعنوان یک شبکه ایمنی مصرفکننده بهطور خودکار مسترد و لغو میشوند، برای رد کردن خریدها به این پنجره انقضا تکیه نکنید. اگر اجازه دهید پنجره تأیید منقضی شود، سفارش در وضعیت تأییدنشده باقی میماند و برای Google Play مبهم است، زیرا نمیتواند رد عمدی توسعهدهنده را از وقفه زمانی پردازش پشتصحنه تشخیص دهد.
درعوض، بلافاصله خریدهای ردشده را از باطن خود بااستفاده از Google Play Developer API لغو کنید و وجه آنها را مسترد کنید:
- اشتراکها: با
purchases.subscriptionsv2.revokeبا"fullRefund": {}درrevocationContextتماس بگیرید. این کار بلافاصله اشتراک را فسخ میکند، دسترسی را لغو میکند، و استرداد کامل را آغاز میکند. - محصولات یکباره:
orders.refundرا با پارامترrevokeتنظیمشده رویtrueفراخوانی کنید تا بلافاصله سفارش را مسترد کنید و حق استفاده آن را لغو کنید. هنگام فراخوانی این روش، باید شناسه سفارش خرید را ارسال کنید که میتوانید آن را بااستفاده ازPurchase.getOrderId()یاpurchases.productsv2.getproductpurchasev2بازیابی کنید. هرگز باconsumeAsync()،acknowledgePurchase()،Purchases.products:consume، یاPurchases.products:acknowledgeدرباره خریدهای ردشده تماس نگیرید. - رفتار RTDN و Voided Purchases: لغوها و استردادهای وجهی که توسعهدهنده شروع کرده است (
purchases.subscriptionsv2.revokeوorders.refundباrevokeتنظیمشده رویtrue) «اعلانهای بیدرنگ توسعهدهنده» را راهاندازی میکنند و در Voided Purchases API (purchases.voidedpurchases.listبا فیلد پاسخvoidedSourceتنظیمشده روی1برای توسعهدهنده) ثبت میشوند:- اشتراکها: هم اعلان
SUBSCRIPTION_REVOKEDو همVoidedPurchaseNotificationارسال میکند. - محصولات یکباره:
VoidedPurchaseNotification(و اعلانONE_TIME_PRODUCT_CANCELEDرا درصورتیکه برنامهتان در «کنسول Play» برای دریافت همه اعلانهای محصولات یکباره پیکربندی شده باشد) ارسال میکند. - فراخوانی
orders.refundبدون تنظیمrevokeرویtrue، مبلغ سفارش را بدون لغو حق استفاده مسترد میکند و اعلان لغو یا ابطال خرید را راهاندازی نمیکند. برای جزئیات بیشتر، مدیریت اشتراکها و خریدهای یکباره را ببینید.
- اشتراکها: هم اعلان
خلاصه
در زیر خلاصهای از این مراحل آمده است.
خرید را به پسای امن خود ارسال کنید تا خریدها را پیشاز اعطای حقوق درستیسنجی کنید.
فضای ذخیرهسازی استحقاقیتان را با خرید بهروز کنید. اگر خرید در وضعیت «درانتظار» است، مطمئن شوید که حق استفاده بهعنوان «درانتظار» علامتگذاری شده باشد و کاربر هنوز مزایا را دریافت نکرده باشد. توصیه میشود این مرحله در زیرینه امن شما انجام شود و میتواند در فراخوانی میانای برنامهسازی کاربردی به زیرینه شما در مرحله ۱ ترکیب شود.
بااستفاده از پیامرسانی مناسب به کاربر اطلاع دهید (درصورت نیاز، همانطور که قبلاً بحث شد، اعلان را بهتأخیر بیندازید).
بااستفاده از مراحل بحثشده در بخش پردازش خریدها، به Google اطلاع دهید که خرید پردازش شده است.
برای تأیید اینکه برنامهتان این مراحل را بهدرستی اجرا کرده است، میتوانید راهنمای آزمایش را دنبال کنید.
رسیدگی به تراکنشهای معلق
Google Play از تراکنشهای معلقه یا تراکنشهایی که به یک یا چند مرحله اضافی بین زمانی که کاربر خرید را شروع میکند و زمانی که روش پرداخت برای خرید پردازش میشود نیاز دارند، پشتیبانی میکند. برنامه شما نباید حق استفاده از این نوع خریدها را اعطا کند تا زمانی که Google به شما اطلاع دهد که هزینه با موفقیت از روش پرداخت کاربر کسر شده است.
برای مثال، کاربر میتواند با انتخاب فروشگاه فیزیکیای که بعداً در آنجا نقدی پرداخت خواهد کرد، تراکنشی را آغاز کند. کاربر کدی را هم ازطریق اعلان و هم ازطریق ایمیل دریافت میکند. وقتی کاربر به فروشگاه فیزیکی میرسد، میتواند کد را به صندوقدار بدهد و با پول نقد پرداخت کند. سپس Google به شما و کاربر اطلاع میدهد که پرداخت دریافت شده است. سپس برنامهتان میتواند حق استفاده را به کاربر اعطا کند.
enablePendingPurchases() را بهعنوان بخشی از مقداردهی اولیه
BillingClient فراخوانی کنید تا تراکنشهای معلق برای برنامهتان فعال شود. برنامهتان باید
تراکنشهای معلق را برای محصولات یکباره فعال و پشتیبانی کند. قبلاز افزودن پشتیبانی، مطمئن شوید که چرخه حیات خرید را برای تراکنشهای معلق درک کردهاید.
وقتی برنامهتان خرید جدیدی را دریافت میکند، چه ازطریق
PurchasesUpdatedListener یا درنتیجه فراخوانی
queryPurchasesAsync، از روش getPurchaseState() استفاده کنید تا
تعیین کنید که وضعیت خرید PURCHASED است یا PENDING. فقط زمانی باید حق استفاده را اعطا کنید که وضعیت PURCHASED باشد.
اگر برنامهتان درحال اجرا باشد و اتصال «کتابخانه خدمات صورتحساب Play» فعال داشته باشید،
وقتی کاربر خرید را تکمیل میکند، PurchasesUpdatedListener شما
دوباره فراخوانی میشود و PurchaseState اکنون PURCHASED است. در این مرحله،
برنامهتان میتواند خرید را بااستفاده از روش استاندارد برای شناسایی و
پردازش خریدها پردازش کند. برنامه شما همچنین باید queryPurchasesAsync() را در روش onResume() برنامهتان فراخوانی کند تا خریدهایی را که در زمانی که برنامهتان اجرا نمیشده است به وضعیت PURCHASED منتقل شدهاند مدیریت کند.
وقتی خرید از PENDING به PURCHASED منتقل میشود، مشتری
real_time_developer_notifications شما اعلان
ONE_TIME_PRODUCT_PURCHASED یا SUBSCRIPTION_PURCHASED دریافت میکند. اگر خرید لغو شود، اعلان ONE_TIME_PRODUCT_CANCELED یا SUBSCRIPTION_PENDING_PURCHASE_CANCELED دریافت خواهید کرد. این اتفاق زمانی میافتد که مشتری پرداخت را در چارچوب زمانی لازم تکمیل نکند. توجه داشته باشید که همیشه میتوانید از Google Play Developer API برای بررسی وضعیت فعلی خرید استفاده کنید.
مدیریت خریدهای چندتایی
در نسخههای ۴.۰ و بالاتر «کتابخانه خدمات صورتحساب Google Play» پشتیبانی میشود، Google Play به مشتریان اجازه میدهد با مشخص کردن تعداد در سبد خرید، بیشاز یک عدد از یک محصول یکباره را در یک تراکنش خریداری کنند. انتظار میرود برنامه شما خریدهای چندتایی را مدیریت کند و براساس تعداد خرید مشخصشده، حق استفاده اعطا کند.
برای رعایت خریدهای چندتایی، منطق تدارک برنامه شما باید
تعداد محصول را بررسی کند. میتوانید ازطریق یکی از میاناهای برنامهسازی کاربردی زیر به فیلد quantity دسترسی پیدا کنید:
getQuantity()از «کتابخانه خدمات صورتحساب Google Play».Purchases.products.quantityاز Google Play Developer API
پساز اینکه منطق را برای مدیریت خریدهای چندتایی اضافه کردید، باید ویژگی چندتایی را برای محصول مربوطه در صفحه مدیریت محصول یکباره در «کنسول Google Play Developer» فعال کنید.
پرسوجو درباره پیکربندی صورتحساب کاربر
getBillingConfigAsync() کشوری را که کاربر برای Google Play استفاده میکند ارائه میدهد.
پساز ایجاد
BillingClient میتوانید پیکربندی صورتحساب کاربر را جستجو کنید. تکهکد زیر نحوه برقراری تماس با getBillingConfigAsync() را شرح میدهد. با پیادهسازی
BillingConfigResponseListener، پاسخ را مدیریت کنید. این شنونده بهروزرسانیهای مربوط به همه پُرسمانهای پیکربندی صورتحساب را که از برنامهتان شروع شدهاند دریافت میکند.
اگر BillingResult برگرداندهشده حاوی هیچ خطایی نباشد، میتوانید فیلد countryCode را در شیء BillingConfig بررسی کنید تا کشور Play کاربر را بهدست آورید.
کاتلین
// Use the default GetBillingConfigParams. val getBillingConfigParams = GetBillingConfigParams.newBuilder().build() billingClient.getBillingConfigAsync( getBillingConfigParams, object : BillingConfigResponseListener { override fun onBillingConfigResponse( billingResult: BillingResult, billingConfig: BillingConfig? ) { if (billingResult.responseCode == BillingResponseCode.OK && billingConfig != null ) { val countryCode = billingConfig.countryCode // ... } else { // Handle errors } } } )
جاوا
GetBillingConfigParams getBillingConfigParams = GetBillingConfigParams.newBuilder().build(); billingClient.getBillingConfigAsync( getBillingConfigParams, (billingResult, billingConfig) -> { if (billingResult.getResponseCode() == BillingResponseCode.OK && billingConfig != null) { String countryCode = billingConfig.getCountryCode(); } else { // TODO: Handle errors } });