پیشنهادهای پیش‌سفارش برای محصولات یکبار مصرف اضافه کنید

۱. مقدمه

در این آزمایشگاه کد، شما بر ایجاد یک محصول یکبار مصرف (OTP) تمرکز خواهید کرد و یک پیشنهاد پیش‌سفارش برای محصول اضافه خواهید کرد.

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

مخاطب

این آزمایشگاه کدنویسی برای توسعه‌دهندگان برنامه‌های اندروید طراحی شده است که با محصولات یکبار مصرف آشنا هستند و می‌خواهند نحوه اضافه کردن پیشنهادهای پیش‌سفارش به محصولات یکبار مصرف خود را بیاموزند.

پیش‌نیاز

اگر در استفاده از محصولات یکبار مصرف تازه‌کار هستید، توصیه می‌شود که فرم «باز کردن بازارهای جدید با قیمت‌گذاری منطقه‌ای محصول» (Open new markets with regional product pricing codelab) را تکمیل کنید.

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

  • نحوه استفاده از کنسول گوگل پلی برای ایجاد پیشنهادهای پیش‌سفارش برای محصولات یکبار مصرف شما.
  • نحوه استفاده از APIهای کتابخانه پرداخت Play برای جستجوی محصولات یکبار مصرف و جزئیات پیشنهاد پیش‌سفارش مربوطه.

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

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

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

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

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

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

پیش‌نیازها

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

ساختن

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

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

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

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

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

۳. ایجاد رمز یکبار مصرف (OTP) با پیش‌سفارش در کنسول پلی

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

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

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

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

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

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

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

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

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

حالا، محصولی را که می‌خواهید کاربران فقط یک بار خریداری کنند، ایجاد کنید.

  1. برنامه نمونه را در کنسول گوگل پلی باز کنید و به مسیر Monetize with Play > Products > One-time products بروید.
  2. روی ایجاد محصول یکبار مصرف کلیک کنید.
  3. جزئیات محصول زیر را وارد کنید:
    • شناسه محصول: یک شناسه منحصر به فرد وارد کنید. برای مثال، upcoming_movie_1 .
    • (اختیاری) برچسب‌ها: برچسب‌های مرتبط اضافه کنید.
    • نام: نام محصول را وارد کنید. برای مثال، Product Movie .
    • توضیحات: توضیحات محصول را وارد کنید. برای مثال، Product Description .
    • (اختیاری) افزودن تصویر آیکون: آیکونی را که نمایانگر محصول شماست، بارگذاری کنید.
    توجه: برای اهداف این آزمایشگاه کد، می‌توانید از پیکربندی بخش مالیات، انطباق و برنامه‌ها صرف نظر کنید.
  4. روی بعدی کلیک کنید.
  5. یک گزینه خرید اضافه کنید و دسترسی منطقه‌ای آن را پیکربندی کنید. یک محصول یکبار مصرف حداقل به یک گزینه خرید نیاز دارد که نحوه اعطای حق، قیمت آن و دسترسی منطقه‌ای را تعریف می‌کند. برای این codelab، گزینه استاندارد خرید را برای محصول اضافه خواهیم کرد. در بخش گزینه خرید ، جزئیات زیر را وارد کنید:
    • شناسه گزینه خرید: یک شناسه منحصر به فرد وارد کنید. برای مثال، buy-movie .
    • نوع خرید: گزینه خرید را انتخاب کنید.
    • (اختیاری) برچسب‌ها: برچسب‌های مخصوص این گزینه خرید را اضافه کنید.
    • (اختیاری) برای پیکربندی گزینه‌های پیشرفته ، روی گزینه‌های پیشرفته کلیک کنید. برای اهداف این آزمایشگاه کد، می‌توانید از پیکربندی گزینه‌های پیشرفته صرف نظر کنید.
  6. در مرحله بعد، باید دسترسی منطقه‌ای و قیمت را برای گزینه خرید پیکربندی کنید. در بخش دسترسی منطقه‌ای، مناطقی را که محصول شما در آنها در دسترس است، از جمله مناطقی که برنامه شما هنوز منتشر نشده است، مشخص خواهید کرد. به طور پیش‌فرض، گزینه خرید در همه مناطق در دسترس خواهد بود. در بخش دسترسی و قیمت‌گذاری ، روی ویرایش دسترسی و دسترسی کلیک کنید.
    1. تنظیم روی «ناموجود» را انتخاب کنید.
    توجه داشته باشید که همه مناطق به طور خودکار انتخاب شده و روی Available تنظیم شده‌اند.
    1. فقط کشور United States را انتخاب نکنید و سپس روی «تنظیم به حالت غیرقابل دسترس» کلیک کنید. اکنون محصول یک‌بار مصرف فقط در United States در دسترس خواهد بود.
    2. در منوی کشویی «همه مناطق» ، «کشورها و مناطق موجود» را انتخاب کنید. شما باید فقط United States را ببینید.
    3. روی نماد قیمت کلیک کنید. این یک کادر محاوره‌ای برای تنظیم قیمت نمایش می‌دهد.
    4. 10 دلار آمریکا را وارد کنید و سپس روی ذخیره کلیک کنید.
  7. روی ذخیره به عنوان پیش‌نویس کلیک کنید.

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

پیشنهاد پیش‌سفارش اضافه کنید

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

افزودن پیشنهاد پیش‌سفارش شامل ۲ مرحله زیر است:

  1. گزینه خرید را برای پیشنهاد پیش‌سفارش آماده کنید.
  2. پیشنهاد پیش‌سفارش را برای گزینه خرید اضافه کنید.

گزینه خرید را برای پیشنهاد پیش‌سفارش آماده کنید

  1. برنامه نمونه را در کنسول گوگل پلی باز کنید و به مسیر Monetize with Play > Products > One-time products بروید.
  2. در صفحه محصولات یکبار مصرف ، روی پیکان سمت راست محصول خود ( upcoming_movie_1 ) کلیک کنید. این کار صفحه ویرایش محصول یکبار مصرف را باز می‌کند.
  3. روی پیکان سمت راست گزینه خرید buy-movie که قبلاً ایجاد کرده‌اید کلیک کنید. این کار صفحه ویرایش گزینه خرید را باز می‌کند.
  4. روی ویرایش دسترسی و موجود بودن کلیک کنید و سپس تنظیم به موجود بودن را انتخاب کنید و به کاربران اجازه دهید پیش‌سفارش دهند .
  5. از منوی کشویی « همه مناطق» ، «کشورها و مناطق موجود» را انتخاب کنید. این باید فقط United States که قبلاً پیکربندی کرده‌اید، نشان دهد.
  6. کشور را انتخاب کنید و سپس روی «تنظیم به فقط برای پیش‌سفارش موجود است» کلیک کنید.
  7. روی ذخیره کلیک کنید.

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

پیشنهاد پیش‌سفارش اضافه کنید

  1. برنامه نمونه را در کنسول گوگل پلی باز کنید و به مسیر Monetize with Play > Products > One-time products بروید.
  2. در صفحه محصولات یکبار مصرف ، روی افزودن پیشنهاد > پیش‌سفارش برای محصول خود ( upcoming_movie_1 ) کلیک کنید. این کار صفحه افزودن پیش‌سفارش را باز می‌کند.
  3. جزئیات پیش‌سفارش را وارد کنید:
    • شناسه پیش‌سفارش: preorder-offer-1 را وارد کنید.
    • (اختیاری) افزودن تخفیف: می‌توانید هیچ ، درصد یا تخفیف مطلق را انتخاب کنید. برای اهداف این آزمایشگاه کد، هیچ را انتخاب کنید.
    • (اختیاری) برچسب‌ها: برچسب‌های مرتبط اضافه کنید.
    • تاریخ و زمان شروع: تاریخی را حداقل ۳ روز آینده تعیین کنید.
    • تاریخ و زمان پایان: تاریخی را حداقل ۲۴ ساعت پس از تاریخ شروع تعیین کنید.
    • موجودی پس از پیش‌سفارش: انتخاب کنید که آیا محصول بلافاصله پس از دوره پیش‌سفارش یا در تاریخ/زمان مشخصی در دسترس قرار گیرد.
    • (اختیاری) تضمین قیمت پایین‌تر: اگر می‌خواهید کاربران کمترین قیمت بین قیمت پیش‌سفارش و قیمت زمان انتشار را دریافت کنند، این گزینه را انتخاب کنید. این می‌تواند یک انگیزه قوی برای خریداران اولیه باشد.
  4. روی ذخیره کلیک کنید.
  5. صفحه ویرایش محصول یکبار مصرف را برای محصول یکبار مصرف خود (upcoming_movie_1) باز کنید.
  6. برای گزینه خرید ( buy-movie ) روی فعال‌سازی کلیک کنید.
  7. برای فعال کردن پیشنهاد پیش‌سفارش ( preorder-offer-1 ) در زیر گزینه خرید، روی فعال‌سازی کلیک کنید. این کار پیشنهاد پیش‌سفارش را فعال می‌کند و آن را در تاریخی که قبلاً در جزئیات پیش‌سفارش پیکربندی کرده‌اید، فعال می‌کند.

ویدیوی ایجاد پیشنهاد پیش‌سفارش

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

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

برای ادغام برنامه خود با کتابخانه پرداخت Play (PBL) ، مراحل زیر را انجام دهید:

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

implementation("com.android.billingclient:billing-ktx:$billing_version")
}
  2. BillingClient را مقداردهی اولیه کنید. BillingClient، SDK کلاینت است که در برنامه شما قرار دارد و با کتابخانه Play Billing ارتباط برقرار می‌کند. قطعه کد زیر نحوه مقداردهی اولیه کلاینت صورتحساب را نشان می‌دهد. 
    private BillingClient createBillingClient() {
return BillingClient.newBuilder(activity)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    // For one-time products, add a listener to process and acknowledge the purchases. This will notify
    // Google the purchase was processed.
    // For client-only apps, use billingClient.acknowledgePurchase().
    // 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
    // In this sample snippet purchases aren't processed. You must
    // implement your business logic to process and acknowledge the purchases.
    .setListener((billingResult, purchases) -> {})
    .enableAutoServiceReconnection()
    .build();
 }
  3. اتصال به گوگل پلی. قطعه کد زیر نحوه اتصال به گوگل پلی را نشان می‌دهد. 
    /**
* Starts the billing connection with Google Play. This method should be called exactly once
* before any other methods in this class.
*
* @param productList The list of products to query for after the connection is established.
*/
public void startBillingConnection(List<Product> productList) {
    billingClient.startConnection(
        new BillingClientStateListener() {
        @Override
        public void onBillingSetupFinished(BillingResult billingResult) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            Log.d(TAG, "Billing Client Connection Successful");
            queryProductDetails(productList);
            } else {
            Log.e(TAG, "Billing Client Connection Failed: " + billingResult.getDebugMessage());
            listener.onBillingSetupFailed(billingResult); // Propagate the error to the listener to show a message to the user.
            }
        }

        @Override
        public void onBillingServiceDisconnected() {
            Log.e(TAG, "Billing Client Connection Lost");
            listener.onBillingError("Billing Connection Lost");
        }
        });
}
  4. جزئیات محصول یکبار مصرف را دریافت کنید. پس از ادغام برنامه خود با PBL، باید جزئیات محصول یکبار مصرف را در برنامه خود دریافت کنید. قطعه کد زیر نحوه دریافت جزئیات محصول یکبار مصرف را در برنامه شما نشان می‌دهد.
    private void queryProductDetails(List<Product> productList) {
    QueryProductDetailsParams queryProductDetailsParams =
        QueryProductDetailsParams.newBuilder().setProductList(productList).build();

    billingClient.queryProductDetailsAsync(
        queryProductDetailsParams,
        new ProductDetailsResponseListener() {
        @Override
        public void onProductDetailsResponse(
            BillingResult billingResult, QueryProductDetailsResult productDetailsResponse) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            List<ProductDetails> productDetailsList =
                productDetailsResponse.getProductDetailsList();
                listener.onProductDetailsResponse(productDetailsList);
            } else {
            Log.e(TAG, "QueryProductDetailsAsync Failed: " + billingResult.getDebugMessage());
            listener.onBillingError("Query Products Failed: " + billingResult.getResponseCode());
            }
        }
        });
}
    دریافت محصول یک‌بار مصرف (در این مثال upcoming_movie_1 ) در ProductDetails ، پاسخی مشابه موارد زیر به شما می‌دهد:
    {
    "productId": "upcoming_movie_1",
    "type": "inapp",
    "title": "Purrfect Mayhem: The Final Playback (Movies All Day | Play Samples)",
    "name": "Purrfect Mayhem: The Final Playback",
    "description": "Yolo and Thorne must reach the original broadcasting site to initiate the \"Final Playback\" and save the timeline. Follow them through their race against the Clockinators.",
    "skuDetailsToken": "<---skuDetailsToken--->",
    "oneTimePurchaseOfferDetails": {},
    "oneTimePurchaseOfferDetailsList": [
        {
            "priceAmountMicros": 8500000,
            "priceCurrencyCode": "USD",
            "formattedPrice": "$8.50",
            "offerIdToken": "<---offerIdToken--->",
            "offerId": "preorder",
            "purchaseOptionId": "buy-option",
            "offerTags": [],
            "validTimeWindow": {
                "startTimeMillis": 1756771200000,
                "endTimeMillis": 1785542400000
            },
            "preorderDetails": {
                "preorderReleaseTimeMillis": 1785542400000,
                "preorderPresaleEndTimeMillis": 1785542400000
            }
        }
    ]
}
    توجه داشته باشید که جزئیات پیشنهاد پیش‌سفارش در oneTimePurchaseOfferDetailsList موجود است. این لیست دارای ۱ گزینه خرید ( buy-option ) است که پیشنهاد پیش‌سفارش برای آن در Play Console پیکربندی شده است. می‌توانید هر گزینه خرید را به‌طور منحصربه‌فرد با offerIdToken آن شناسایی کنید.
  5. توکن پیشنهاد را به همراه جزئیات پیشنهاد پیش‌سفارش دریافت کنید. برای شروع جریان پرداخت در مرحله ۶ به توکن پیشنهاد نیاز دارید. 
    @Override
public void onProductDetailsResponse(List<ProductDetails> productDetailsList) {

if (productDetailsList != null && !productDetailsList.isEmpty()) {

// Process productDetailsList returned by QueryProductDetailsResult
for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
  for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
      productDetails.getOneTimePurchaseOfferDetailsList()) {
    // Checks if the offer is a preorder offer.
    if (oneTimePurchaseOfferDetails.getPreorderDetails() != null) {
      // Process the returned PreorderDetails
      OneTimePurchaseOfferDetails.PreorderDetails preorderDetails =
          oneTimePurchaseOfferDetails.getPreorderDetails();
      // Get preorder release time in millis.
      long preorderReleaseTimeMillis = preorderDetails.getPreorderReleaseTimeMillis();
      // Get preorder presale end time in millis.
      long preorderPresaleEndTimeMillis = preorderDetails.getPreorderPresaleEndTimeMillis();
      // Get offer ID
        String offerId = oneTimePurchaseOfferDetails.getOfferId();
      // Get the associated purchase option ID
      if (oneTimePurchaseOfferDetails.getPurchaseOptionId() != null) {
        String purchaseOptionId = oneTimePurchaseOfferDetails.getPurchaseOptionId();
      }
    }
  }
  }
  } else {
        Log.e(TAG, "No product details found for " + productId);
    }
}
  6. جریان صورتحساب را راه اندازی کنید. 
    /**
 * Launches the billing flow for the product with the given offer token.
*
* @param activity The activity instance from which the billing flow will be launched.
* @param productDetails The product details of the product to purchase.
* @param offerToken The offer token of the product to purchase.
* @return The result of the billing flow.
*/
public void launchPurchase(Activity activity, ProductDetails productDetails, String offerToken) {
    ImmutableList<BillingFlowParams.ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetails)
                .setOfferToken(offerToken)
                .build());
    BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build();
    billingClient.launchBillingFlow(activity, billingFlowParams);
}

۵. گزینه‌های خرید را امتحان کنید

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

برای درک اینکه چگونه می‌توانید گزینه‌های خرید خود را با استفاده از Play Billing Lab آزمایش کنید، به بخش «باز کردن بازارهای جدید با کدلاب قیمت‌گذاری منطقه‌ای محصول» مراجعه کنید.

۶. مراحل بعدی

اسناد مرجع

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

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

نظرسنجی

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