تجزیه و تحلیل موارد انصراف از خرید محصول در Play Billing

۱. مقدمه

در این آزمایشگاه کد، شما بر ایجاد یک محصول یکبار مصرف، ادغام برنامه خود با کتابخانه پرداخت Play (PBL) و تجزیه و تحلیل دلایل انصراف از خرید تمرکز خواهید کرد.

مخاطب

این آزمایشگاه کد برای توسعه‌دهندگان برنامه‌های اندرویدی که از کتابخانه پرداخت Play (PBL) استفاده می‌کنند یا می‌خواهند از PBL برای کسب درآمد از محصولات یکبار مصرف خود استفاده کنند، در نظر گرفته شده است.

آنچه یاد خواهید گرفت...

  • نحوه ایجاد محصولات یکبار مصرف در کنسول گوگل پلی
  • چگونه برنامه خود را با PBL ادغام کنید.
  • نحوه پردازش خریدهای یکبار مصرف محصولات مصرفی و غیر مصرفی در PBL.
  • چگونه می‌توان میزان انصراف از خرید را تحلیل کرد؟

آنچه نیاز خواهید داشت...

۲. ساخت اپلیکیشن نمونه

این برنامه نمونه به گونه‌ای طراحی شده است که یک برنامه اندرویدی کاملاً کاربردی باشد و کد منبع کاملی دارد که جنبه‌های زیر را نشان می‌دهد:

  • ادغام برنامه با PBL
  • محصولات یکبار مصرف را دریافت کنید
  • جریان‌های خرید را برای محصولات یکبار مصرف راه‌اندازی کنید
  • سناریوهای خریدی که منجر به پاسخ‌های صورتحساب زیر می‌شوند:
    • BILLING_UNAVAILABLE
    • USER_CANCELLED
    • OK
    • ITEM_ALREADY_OWNED

ویدیوی آزمایشی زیر نشان می‌دهد که برنامه‌ی نمونه پس از استقرار و اجرا، چگونه به نظر می‌رسد و چگونه رفتار خواهد کرد.

پیش‌نیازها

قبل از ساخت و استقرار برنامه نمونه، موارد زیر را انجام دهید:

ساختن

هدف از این مرحله ساخت، تولید یک فایل بسته نرم‌افزاری اندروید امضا شده از برنامه نمونه است.

برای تولید بسته نرم‌افزاری اندروید، مراحل زیر را انجام دهید:

  1. برنامه نمونه را از گیت‌هاب دانلود کنید.
  2. برنامه نمونه را بسازید . قبل از ساخت، نام بسته برنامه نمونه را تغییر دهید و سپس آن را بسازید. اگر بسته‌هایی از برنامه‌های دیگر در کنسول Play خود دارید، مطمئن شوید که نام بسته‌ای که برای برنامه نمونه ارائه می‌دهید منحصر به فرد است.

    نکته : ساخت برنامه نمونه فقط یک فایل APK ایجاد می‌کند که می‌توانید برای آزمایش محلی از آن استفاده کنید. با این حال، اجرای برنامه محصولات و قیمت‌ها را دریافت نمی‌کند زیرا محصولات در کنسول Play پیکربندی نشده‌اند که در ادامه این آزمایشگاه کد به آن خواهیم پرداخت.
  3. یک بسته نرم‌افزاری اندروید امضا شده ایجاد کنید.
    1. ایجاد کلید آپلود و کلید اصلی
    2. برنامه خود را با کلید آپلود خود امضا کنید
    3. پیکربندی امضای برنامه Play

مرحله بعدی آپلود بسته برنامه اندروید در کنسول گوگل پلی است.

۳. ایجاد محصول یکبار مصرف در کنسول پلی

برای ایجاد محصولات یکبار مصرف در کنسول گوگل پلی، باید یک برنامه در کنسول پلی داشته باشید. یک برنامه در کنسول پلی ایجاد کنید و سپس بسته برنامه امضا شده قبلی را آپلود کنید.

یک برنامه ایجاد کنید

برای ایجاد یک برنامه:

  1. با استفاده از حساب توسعه‌دهنده خود، وارد کنسول گوگل پلی شوید .
  2. روی ایجاد برنامه کلیک کنید. این صفحه ایجاد برنامه را باز می‌کند.
  3. نام برنامه را وارد کنید، زبان پیش‌فرض و سایر جزئیات مربوط به برنامه را انتخاب کنید.
  4. روی ایجاد برنامه کلیک کنید. این یک برنامه در کنسول گوگل پلی ایجاد می‌کند.

اکنون می‌توانید بسته‌ی برنامه‌ی امضا شده‌ی برنامه‌ی نمونه را آپلود کنید.

بسته برنامه امضا شده را آپلود کنید

  1. بسته‌ی برنامه‌ی امضا شده را در مسیر تست داخلی کنسول گوگل پلی آپلود کنید . تنها پس از آپلود، می‌توانید ویژگی‌های مرتبط با کسب درآمد را در کنسول پلی پیکربندی کنید.
  2. روی تست و انتشار > در حال آزمایش > انتشار داخلی > ایجاد نسخه جدید کلیک کنید.
  3. نام نسخه را وارد کنید و فایل بسته برنامه امضا شده را آپلود کنید.
  4. روی «بعدی» کلیک کنید و سپس روی «ذخیره و انتشار» کلیک کنید.

حالا می‌توانید محصولات یکبار مصرف خود را ایجاد کنید.

یک محصول یکبار مصرف ایجاد کنید

برای ایجاد یک محصول یکبار مصرف:

  1. در کنسول گوگل پلی ، از منوی ناوبری سمت چپ، به مسیر کسب درآمد از طریق بازی > محصولات > محصولات یکبار مصرف بروید.
  2. روی ایجاد محصول یکبار مصرف کلیک کنید.
  3. جزئیات محصول زیر را وارد کنید:
    • شناسه محصول: یک شناسه منحصر به فرد برای محصول وارد کنید. one_time_product_01 را وارد کنید.
    • (اختیاری) برچسب‌ها: برچسب‌های مرتبط اضافه کنید.
    • نام: نام محصول را وارد کنید. برای مثال، Product name .
    • توضیحات: توضیحات محصول را وارد کنید. برای مثال، Product description .
    • (اختیاری) افزودن تصویر آیکون: آیکونی را که نمایانگر محصول شماست، بارگذاری کنید.
    توجه: برای اهداف این آزمایشگاه کد، می‌توانید از پیکربندی بخش مالیات، انطباق و برنامه‌ها صرف نظر کنید.
  4. روی بعدی کلیک کنید.
  5. یک گزینه خرید اضافه کنید و موجودی منطقه‌ای آن را پیکربندی کنید. یک محصول یکبار مصرف حداقل به یک گزینه خرید نیاز دارد که نحوه اعطای حق، قیمت و موجودی منطقه‌ای آن را تعریف می‌کند. برای این codelab، گزینه استاندارد خرید را برای محصول اضافه خواهیم کرد. در بخش گزینه خرید ، جزئیات زیر را وارد کنید:
    • شناسه گزینه خرید: شناسه گزینه خرید را وارد کنید. برای مثال، buy .
    • نوع خرید: گزینه خرید را انتخاب کنید.
    • (اختیاری) برچسب‌ها: برچسب‌های مخصوص این گزینه خرید را اضافه کنید.
    • (اختیاری) برای پیکربندی گزینه‌های پیشرفته ، روی گزینه‌های پیشرفته کلیک کنید. برای اهداف این آزمایشگاه کد، می‌توانید از پیکربندی گزینه‌های پیشرفته صرف نظر کنید.
  6. در بخش «موجودی و قیمت‌گذاری» ، روی «تنظیم قیمت‌ها» > «ویرایش انبوه قیمت‌گذاری» کلیک کنید.
  7. گزینه Country / region را انتخاب کنید. این گزینه همه مناطق را انتخاب می‌کند.
  8. روی ادامه کلیک کنید. این کار یک پنجره برای وارد کردن قیمت باز می‌کند. 10 دلار آمریکا وارد کنید و سپس روی اعمال کلیک کنید.
  9. روی ذخیره و سپس روی فعال‌سازی کلیک کنید. این گزینه خرید را ایجاد و فعال می‌کند.

برای اهداف این آزمایشگاه کد، ۳ محصول یکبار مصرف دیگر با شناسه‌های محصول زیر ایجاد کنید:

  • محصول_مصرفی_۰۱
  • محصول_مصرفی_02
  • محصول_مصرفی_03

برنامه‌ی نمونه برای استفاده از این شناسه‌های محصول پیکربندی شده است. شما می‌توانید شناسه‌های محصول متفاوتی ارائه دهید، که در این صورت، باید برنامه‌ی نمونه را برای استفاده از شناسه‌ی محصولی که ارائه داده‌اید، تغییر دهید.

برنامه نمونه را در کنسول گوگل پلی باز کنید و به مسیر کسب درآمد از طریق بازی > محصولات > محصولات یکبار مصرف بروید. سپس روی ایجاد محصول یکبار مصرف کلیک کنید و مراحل ۳ تا ۹ را تکرار کنید.

ویدیوی ساخت محصول یکبار مصرف

ویدیوی نمونه زیر مراحل ایجاد محصول یکباره را که قبلاً شرح داده شده است، نشان می‌دهد.

۴. با PBL ادغام شوید

اکنون، خواهیم دید که چگونه برنامه خود را با کتابخانه پرداخت Play (PBL) ادغام کنید. این بخش مراحل سطح بالای ادغام را شرح می‌دهد و برای هر یک از مراحل، یک قطعه کد ارائه می‌دهد. می‌توانید از این قطعه کدها به عنوان راهنمایی برای پیاده‌سازی ادغام واقعی خود استفاده کنید.

برای ادغام برنامه خود با PBL، مراحل زیر را انجام دهید:

  1. وابستگی Play Billing Library را به برنامه نمونه اضافه کنید. 
    dependencies {
val billing_version = "8.0.0"

implementation("com.android.billingclient:billing-ktx:$billing_version")
}
  2. BillingClient را مقداردهی اولیه کنید. BillingClient، SDK کلاینت است که در برنامه شما قرار دارد و با کتابخانه Play Billing ارتباط برقرار می‌کند. قطعه کد زیر نحوه مقداردهی اولیه کلاینت صورتحساب را نشان می‌دهد. 
    protected BillingClient createBillingClient() {
return BillingClient.newBuilder(activity)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .enableAutoServiceReconnection()
    .build();
}
  3. اتصال به گوگل پلی. قطعه کد زیر نحوه اتصال به گوگل پلی را نشان می‌دهد. 
    public void startBillingConnection(ImmutableList<Product> productList) {
Log.i(TAG, "Product list sent: " + productList);
Log.i(TAG, "Starting connection");
billingClient.startConnection(
    new BillingClientStateListener() {
      @Override
      public void onBillingSetupFinished(BillingResult billingResult) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
          // Query product details to get the product details list.
          queryProductDetails(productList);
        } else {
          // BillingClient.enableAutoServiceReconnection() will retry the connection on
          // transient errors automatically.
          // We don't need to retry on terminal errors (e.g., BILLING_UNAVAILABLE,
          // DEVELOPER_ERROR).
          Log.e(TAG, "Billing connection failed: " + billingResult.getDebugMessage());
          Log.e(TAG, "Billing response code: " + billingResult.getResponseCode());
        }
      }

      @Override
      public void onBillingServiceDisconnected() {
        Log.e(TAG, "Billing Service connection lost.");
      }
    });
}
  4. جزئیات محصول یکبار مصرف را دریافت کنید. پس از ادغام برنامه خود با PBL، باید جزئیات محصول یکبار مصرف را در برنامه خود دریافت کنید. قطعه کد زیر نحوه دریافت جزئیات محصول یکبار مصرف را در برنامه شما نشان می‌دهد.
    private void queryProductDetails(ImmutableList<Product> productList) {
Log.i(TAG, "Querying products for: " + productList);
QueryProductDetailsParams queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder().setProductList(productList).build();
billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
      @Override
      public void onProductDetailsResponse(
          BillingResult billingResult, QueryProductDetailsResult productDetailsResponse) {
        // check billingResult
        Log.i(TAG, "Billing result after querying: " + billingResult.getResponseCode());
        // process returned productDetailsList
        Log.i(
            TAG,
            "Print unfetched products: " + productDetailsResponse.getUnfetchedProductList());
        setupProductDetailsMap(productDetailsResponse.getProductDetailsList());
        billingServiceClientListener.onProductDetailsFetched(productDetailsMap);
      }
    });
}
    واکشی ProductDetails ، پاسخی مشابه زیر به شما می‌دهد: 
    {
    "productId": "consumable_product_01",
    "type": "inapp",
    "title": "Shadow Coat (Yolo's Realm | Play Samples)",
    "name": "Shadow Coat",
    "description": "A sleek, obsidian coat for stealth and ambushes",
    "skuDetailsToken": "<---skuDetailsToken--->",
    "oneTimePurchaseOfferDetails": {},
    "oneTimePurchaseOfferDetailsList": [
        {
            "priceAmountMicros": 1990000,
            "priceCurrencyCode": "USD",
            "formattedPrice": "$1.99",
            "offerIdToken": "<--offerIdToken-->",
            "purchaseOptionId": "buy",
            "offerTags": []
        }
    ]
},
{
    "productId": "consumable_product_02",
    "type": "inapp",
    "title": "Emperor Den (Yolo's Realm | Play Samples)",
    "name": "Emperor Den",
    "description": "A fair lair glowing with molten rock and embers",
    "skuDetailsToken": "<---skuDetailsToken--->",
    "oneTimePurchaseOfferDetails": {},
    "oneTimePurchaseOfferDetailsList": [
        {
            "priceAmountMicros": 2990000,
            "priceCurrencyCode": "USD",
            "formattedPrice": "$2.99",
            "offerIdToken": "<--offerIdToken-->",
            "purchaseOptionId": "buy",
            "offerTags": []
        }
    ]
}
  5. جریان صورتحساب را راه اندازی کنید. 
    public void launchBillingFlow(String productId) {
ProductDetails productDetails = productDetailsMap.get(productId);
if (productDetails == null) {
  Log.e(
      TAG, "Cannot launch billing flow: ProductDetails not found for productId: " + productId);
  billingServiceClientListener.onBillingResponse(
      BillingResponseCode.ITEM_UNAVAILABLE,
      BillingResult.newBuilder().setResponseCode(BillingResponseCode.ITEM_UNAVAILABLE).build());
  return;
}
ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder().setProductDetails(productDetails).build());

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build();

billingClient.launchBillingFlow(activity, billingFlowParams);
}
  6. تشخیص و پردازش خریدها. به عنوان بخشی از این مرحله، شما باید:
    1. خرید را تأیید کنید
    2. اعطای حق دسترسی به کاربر
    3. به کاربر اطلاع دهید
    4. گوگل را از فرآیند خرید مطلع کنید
    از این موارد، مراحل الف، ب و ج باید در backend شما انجام شوند و از این رو خارج از محدوده این آزمایشگاه کد هستند. قطعه کد زیر نحوه اطلاع رسانی به گوگل برای یک محصول یکبار مصرف را نشان می‌دهد: 
    private void handlePurchase(Purchase purchase) {
// Step 1: Send the purchase to your secure backend to verify the purchase following
// https://developer.android.com/google/play/billing/security#verify

// Step 2: Update your entitlement storage with the purchase. If purchase is
// in PENDING state then ensure the entitlement is marked as pending and the
// user does not receive benefits yet. It is recommended that this step is
// done on your secure backend and can combine in the API call to your
// backend in step 1.

// Step 3: Notify the user using appropriate messaging.
if (purchase.getPurchaseState() == PurchaseState.PURCHASED) {
  for (String product : purchase.getProducts()) {
    Log.d(TAG, product + " purchased successfully! ");
  }
}

// Step 4: Notify Google the purchase was processed.
// For one-time products, acknowledge the purchase.
// This sample app (client-only) uses billingClient.acknowledgePurchase().
// For consumable one-time products, consume the purchase
// This sample app (client-only) uses billingClient.consumeAsync()
// If you have a secure backend, you must acknowledge purchases on your server using the
// server-side API.
// See https://developer.android.com/google/play/billing/security#acknowledge
if (purchase.getPurchaseState() == PurchaseState.PURCHASED && !purchase.isAcknowledged()) {

  if (shouldConsume(purchase)) {
    ConsumeParams consumeParams =
        ConsumeParams.newBuilder().setPurchaseToken(purchase.getPurchaseToken()).build();
    billingClient.consumeAsync(consumeParams, consumeResponseListener);

  } else {
    AcknowledgePurchaseParams acknowledgePurchaseParams =
        AcknowledgePurchaseParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build();
    billingClient.acknowledgePurchase(
        acknowledgePurchaseParams, acknowledgePurchaseResponseListener);
  }
 }
}

۵. تحلیل میزان انصراف از خرید

تاکنون در آزمایشگاه کد، پاسخ‌های Play Billing بر سناریوهای محدودی مانند پاسخ‌های USER_CANCELLED ، BILLING_UNAVAILABLE ، OK و ITEM_ALREADY_OWNED متمرکز بوده‌اند. با این حال، Play Billing می‌تواند ۱۳ کد پاسخ مختلف را برگرداند که می‌توانند توسط عوامل مختلف دنیای واقعی فعال شوند.

این بخش به بررسی دلایل بروز خطاهای USER_CANCELLED و BILLING_UNAVAILABLE می‌پردازد و اقدامات اصلاحی ممکنی را که می‌توانید پیاده‌سازی کنید، پیشنهاد می‌دهد.

کد خطای پاسخ USER_CANCELED

این کد پاسخ نشان می‌دهد که کاربر قبل از تکمیل خرید، رابط کاربری جریان خرید را رها کرده است.

علل احتمالی

چه اقداماتی می‌توانید انجام دهید؟

  • می‌تواند نشان‌دهنده کاربران کم‌توجهی باشد که به قیمت‌ها حساس هستند.
  • خرید در حال بررسی است یا پرداخت رد شده است.

کد خطای پاسخ BILLING_UNAVAILABLE

این کد پاسخ به این معنی است که خرید به دلیل مشکلی در ارائه دهنده پرداخت کاربر یا روش پرداخت انتخابی او، تکمیل نشده است. برای مثال، کارت اعتباری کاربر منقضی شده است یا کاربر در یک کشور پشتیبانی نشده است. این کد نشان دهنده خطایی در خود سیستم پرداخت Play نیست.

علل احتمالی

چه اقداماتی می‌توانید انجام دهید؟

  • برنامه Play Store در دستگاه کاربر قدیمی است.
  • کاربر در کشوری است که Play در آن پشتیبانی نمی‌شود.
  • کاربر، یک کاربر سازمانی است و مدیر سازمانی او، امکان خرید را برای کاربران غیرفعال کرده است.
  • گوگل پلی نمی‌تواند از روش پرداخت کاربر هزینه دریافت کند. برای مثال، ممکن است اعتبار کارت اعتباری کاربر منقضی شده باشد.
  • روند مشکلات سیستم و در مناطق خاص را زیر نظر داشته باشید
  • مهاجرت به PBL 8 را در نظر بگیرید زیرا از کد زیرپاسخ PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS با جزئیات بیشتر پشتیبانی می‌کند. اگر این کد پاسخ را دریافت کردید، به کاربران در مورد خطا اطلاع دهید یا روش‌های پرداخت جایگزینی را پیشنهاد دهید.
  • این کد پاسخ برای تلاش‌های مجدد طراحی شده است و به شما امکان می‌دهد استراتژی‌های مناسب برای تلاش مجدد را پیاده‌سازی کنید.
    بعید است که تلاش‌های مجدد خودکار در این مورد کمکی کنند. با این حال، اگر کاربر شرایطی را که باعث ایجاد مشکل شده است، برطرف کند، یک تلاش مجدد دستی می‌تواند مفید باشد. به عنوان مثال، اگر کاربر نسخه فروشگاه Play خود را به یک نسخه پشتیبانی شده به‌روزرسانی کند، تلاش مجدد دستی برای عملیات اولیه می‌تواند مؤثر باشد.

    اگر این کد پاسخ را زمانی دریافت کنید که کاربر در جلسه نیست، تلاش مجدد ممکن است منطقی نباشد. وقتی در نتیجه جریان خرید، پاسخ `BILLING_UNAVAILABLE` دریافت می‌کنید، به احتمال زیاد کاربر در طول فرآیند خرید از Google Play بازخورد دریافت کرده و ممکن است از مشکل پیش آمده آگاه باشد. در این حالت، می‌توانید یک پیام خطا نشان دهید که مشخص می‌کند مشکلی پیش آمده است و یک دکمه `Try again` ارائه دهید تا به کاربر امکان تلاش مجدد دستی پس از رفع مشکل را بدهید.

استراتژی‌های تلاش مجدد برای کدهای خطای پاسخ

استراتژی‌های مؤثر تلاش مجدد برای خطاهای قابل بازیابی از کتابخانه پرداخت Play (PBL) بسته به زمینه، مانند تعاملات کاربر در جلسه (مانند هنگام خرید) در مقابل عملیات پس‌زمینه (مانند جستجوی خریدها در رزومه برنامه)، متفاوت است. پیاده‌سازی این استراتژی‌ها مهم است زیرا مقادیر خاص BillingResponseCode نشان‌دهنده مشکلات موقتی هستند که می‌توانند با تلاش مجدد حل شوند، در حالی که برخی دیگر دائمی هستند و نیازی به تلاش مجدد ندارند.

برای خطاهایی که هنگام حضور کاربر در جلسه رخ می‌دهد، یک استراتژی تلاش مجدد ساده با حداکثر تعداد تلاش مشخص برای به حداقل رساندن اختلال در تجربه کاربر توصیه می‌شود. برعکس، برای عملیات پس‌زمینه مانند تأیید خریدهای جدید، که نیازی به اجرای فوری ندارند، روش بازگشت نمایی توصیه می‌شود.

برای اطلاعات دقیق در مورد کدهای پاسخ خاص و استراتژی‌های تلاش مجدد توصیه‌شده مربوط به آنها، به کدهای پاسخ Handle BillingResult مراجعه کنید.

۶. مراحل بعدی

اسناد مرجع

۷. تبریک می‌گویم!

تبریک! شما با موفقیت در کنسول گوگل پلی برای ایجاد یک محصول یکبار مصرف جدید، آزمایش کدهای پاسخ صورتحساب و تجزیه و تحلیل خریدهای انجام شده، پیمایش کردید.

نظرسنجی

بازخورد شما در مورد این آزمایشگاه کد بسیار ارزشمند است. چند دقیقه وقت بگذارید و نظرسنجی ما را تکمیل کنید.