چندین گزینه خرید و پیشنهاد ویژه برای محصولات یک‌باره

این سند جزئیات ادغام محصولات یک‌باره (OTPs) با «کتابخانه خدمات صورت‌حساب Play» را شرح می‌دهد. همچنین نحوه ادغام گزینه‌های خرید و پیشنهادهای ویژه مختلف مربوط به محصولات یک‌باره را توضیح می‌دهد.

می‌توانید چندین گزینه خرید و پیشنهاد ویژه برای محصولات یک‌باره خود پیکربندی کنید. برای مثال، می‌توانید گزینه خرید و پیشنهاد ویژه پیش‌سفارش را برای یک محصول یک‌باره پیکربندی کنید.

پیش‌نیازها

برای پیکربندی چندین پیشنهاد ویژه برای محصولات یک‌باره، باید از queryProductDetailsAsync() API استفاده کنید. میانای برنامه‌سازی کاربردی querySkuDetailsAsync() منسوخ پشتیبانی نمی‌شود. برای اطلاعات درباره نحوه استفاده از queryProductDetailsAsync() و نسخه launchBillingFlow() که ProductDetailsParams را به‌عنوان ورودی می‌گیرد، مراحل انتقال را ببینید.

پرس‌وجو درباره جزئیات محصول

اگر چندین پیشنهاد ویژه یا گزینه خرید برای محصول یک‌باره‌تان پیکربندی کرده‌اید، شیء ProductDetails که توسط روش queryProductDetailsAsync() برگردانده می‌شود می‌تواند بیش‌از یک گزینه خرید و (یا) اجاره دردسترس برای هر محصول یک‌باره داشته باشد. برای دریافت فهرست همه پیشنهادهای ویژه واجدشرایط برای هر شیء ProductDetails، از روش getOneTimePurchaseOfferDetailsList() استفاده کنید. فقط پیشنهادهای ویژه و گزینه‌های خریدی که کاربر برای آن‌ها واجدشرایط است به‌عنوان بخشی از این فهرست برگردانده خواهند شد. کد شما در روش onProductDetailsResponse() باید از عهده پیشنهادهای ویژه برگشتی برآید.

راه‌اندازی جریان صورت‌حساب

برای شروع درخواست خرید از برنامه‌تان، launchBillingFlow() روش را از رشته اصلی برنامه‌تان فراخوانی کنید. این روش مرجعی را به یک BillingFlowParams شیء که حاوی شیء ProductDetails مربوطه است که از فراخوانی queryProductDetailsAsync() به‌دست آمده است می‌گیرد. برای ایجاد شیء BillingFlowParams، از کلاس BillingFlowParams.Builder استفاده کنید. توجه داشته باشید که هنگام ایجاد شیء BillingFlowParams باید نشان پیشنهاد ویژه مربوط به پیشنهاد ویژه انتخاب‌شده توسط کاربر را تنظیم کنید.

نمونه زیر نحوه راه‌اندازی جریان خرید برای محصول یک‌باره با چند پیشنهاد ویژه را نشان می‌دهد:

جاوا

    
// An activity reference from which the billing flow will launch.
Activity activity = ...;
ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for productDetails by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // to get an offer token, call
            // ProductDetails.getOneTimePurchaseOfferDetailsList() 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);

offerToken را می‌توانید به‌عنوان بخشی از OneTimePurchaseOfferDetails پیدا کنید. وقتی پیشنهاد ویژه را به کاربر نشان می‌دهید، حتماً پارامترهای جاری‌سازی صورت‌حساب را با نمودار پیشنهاد ویژه صحیح که می‌توانید از روش oneTimePurchaseOfferDetails.getOfferToken() دریافت کنید پیکربندی کنید.

گزینه‌های خرید و پیشنهادهای ویژه

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

‫Google Play از گزینه‌های خرید زیر برای محصولات یک‌باره پشتیبانی می‌کند:

  • خرید گزینه خرید
  • گزینه اجاره

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

‫Google Play از پیشنهادهای خرید زیر برای محصولات یک‌باره پشتیبانی می‌کند:

  • پیشنهاد ویژه پیش‌سفارش (فقط برای گزینه خرید پشتیبانی می‌شود)
  • پیشنهاد ویژه تخفیف (برای هر دو گزینه خرید و اجاره پشتیبانی می‌شود)

خرید گزینه خرید

گزینه خرید نشان‌دهنده یک خرید استاندارد و کامل برای محصول یک‌باره است. این فیلد اختیاری legacyCompatible دارد که نشان می‌دهد آیا این گزینه خرید در جریان‌های قدیمی «کتابخانه خدمات صورت‌حساب Play» (نسخه ۷ یا قدیمی‌تر) که از مدل جدید پشتیبانی نمی‌کنند دردسترس خواهد بود یا نه. برای سازگاری با نسخه‌های قدیمی، حداقل یک گزینه خرید باید به‌عنوان سازگار با نسخه‌های قدیمی علامت‌گذاری شود.

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

گزینه خرید اجاره

گزینه خرید اجاره به کاربران امکان می‌دهد برای مدت زمان مشخصی به محصولات یک‌باره دسترسی داشته باشند. می‌توانید دوره اجاره و انقضای آن را مشخص کنید. این سند مراحل ادغام گزینه خرید اجاره با «کتابخانه خدمات صورت‌حساب Play» ‏ (PBL) را شرح می‌دهد.

ادغام گزینه اجاره با PBL

این بخش نحوه ادغام کردن گزینه خرید اجاره‌ای با «کتابخانه خدمات صورت‌حساب Play» ‏ (PBL) را شرح می‌دهد. فرض بر این است که با مراحل اولیه ادغام PBL آشنا هستید، مثلاً افزودن وابستگی PBL به برنامه، مقداردهی اولیه BillingClient، و اتصال به Google Play. این بخش بر جنبه‌های یکپارچه‌سازی PBL که مختص گزینه خرید اجاره‌ای است تمرکز دارد.

برای پیکربندی محصولات دردسترس برای اجاره، باید از سرویس جدید monetization.onetimeproducts Play Developer API یا واسط کاربر «کنسول توسعه‌دهنده» Play استفاده کنید. برای استفاده از این سرویس، می‌توانید مستقیماً REST API را فراخوانی کنید یا از کتابخانه کارخواه Java استفاده کنید.

جریان خرید را برای گزینه اجاره راه‌اندازی کنید

برای راه‌اندازی جریان خرید برای پیشنهاد اجاره، مراحل زیر را انجام دهید:

  1. فراداده گزینه خرید اجاره را بااستفاده از روش ProductDetails.oneTimePurchaseOfferDetails.getRentalDetails() واکشی کنید.

    نمونه زیر نحوه دریافت فراداده خرید اجاره را نشان می‌دهد:

    جاوا

    billingClient.queryProductDetailsAsync(
queryProductDetailsParams,
new ProductDetailsResponseListener() {
  public void onProductDetailsResponse(
      BillingResult billingResult, QueryProductDetailsResult productDetailsResult) {
    // check billingResult
    // …
    // process productDetailsList returned by QueryProductDetailsResult
    for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
      for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
          productDetails.getOneTimePurchaseOfferDetailsList()) {
        // Checks if the offer is a rent purchase option.
        if (oneTimePurchaseOfferDetails.getRentalDetails() != null) {
          // process the returned RentalDetails
          OneTimePurchaseOfferDetails.RentalDetails rentalDetails =
              oneTimePurchaseOfferDetails.getRentalDetails();
          // Get rental period in ISO 8601 format.
          String rentalPeriod = rentalDetails.getRentalPeriod();
          // Get rental expiration period in ISO 8601 format, if present.
          if (rentalDetails.getRentalExpirationPeriod() != null) {
            String rentalExpirationPeriod = rentalDetails.getRentalExpirationPeriod();
          }
          // Get offer token
            String offerToken = oneTimePurchaseOfferDetails.getOfferToken();
          // Get the associated purchase option ID
          if (oneTimePurchaseOfferDetails.getPurchaseOptionId() != null) {
            String purchaseOptionId = oneTimePurchaseOfferDetails.getPurchaseOptionId();
          }
        }
      }
    }
  }
});

  2. جریان صورت‌حساب را راه‌اندازی کنید.

    برای شروع درخواست خرید از برنامه‌تان، روش launchBillingFlow() را از رشته اصلی برنامه‌تان فراخوانی کنید. این روش ارجاعی به شیء BillingFlowParams می‌گیرد که حاوی شیء ProductDetails مربوطه است که ازطریق فراخوانی queryProductDetailsAsync() به‌دست آمده است. برای ایجاد شیء BillingFlowParams، از کلاس BillingFlowParams.Builder استفاده کنید. توجه داشته باشید که هنگام ایجاد شیء BillingFlowParams باید نشان پیشنهاد ویژه مربوط به پیشنهاد ویژه انتخاب‌شده توسط کاربر را تنظیم کنید. اگر کاربری برای گزینه خرید اجاره‌ای واجدشرایط باشد، پیشنهادی با RentalDetails و offerId در queryProductDetailsAsync() دریافت خواهد کرد.

    نمونه زیر نحوه راه‌اندازی جریان صورت‌حساب را نشان می‌دهد:

    کاتلین

    // 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);

    offerToken را می‌توان به‌عنوان بخشی از OneTimePurchaseOfferDetails پیدا کرد. وقتی پیشنهاد ویژه را به کاربر نشان می‌دهید، مطمئن شوید که پارامترهای جریان صدور صورت‌حساب را با کد تخفیف صحیح که می‌توانید از روش oneTimePurchaseOfferDetails.getOfferToken() دریافت کنید پیکربندی کرده باشید.

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

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

این سند مراحل ادغام پیشنهاد ویژه خرید پیش‌سفارش با «کتابخانه خدمات صورت‌حساب Play» ‏ (PBL) را شرح می‌دهد.

ادغام پیشنهاد ویژه پیش‌سفارش با PBL

این بخش نحوه ادغام پیشنهاد ویژه پیش‌سفارش با «کتابخانه خدمات صورت‌حساب Play» ‏ (PBL) را توضیح می‌دهد. فرض بر این است که با مراحل اولیه ادغام PBL آشنا هستید، مثلاً افزودن وابستگی PBL به برنامه، مقداردهی اولیه BillingClient، و اتصال به Google Play. این بخش بر جنبه‌های یکپارچه‌سازی PBL که مختص پیشنهاد پیش‌سفارش است تمرکز دارد.

راه‌اندازی جریان خرید برای پیشنهاد ویژه پیش‌سفارش

برای راه‌اندازی جریان خرید برای پیشنهاد ویژه پیش‌سفارش، مراحل زیر را انجام دهید:

  1. فراداده پیشنهاد پیش‌سفارش را بااستفاده از ProductDetails.oneTimePurchaseOfferDetails.getPreorderDetails() روش واکشی کنید. نمونه زیر نحوه دریافت فراداده پیشنهاد ویژه پیش‌سفارش را نشان می‌دهد:

    جاوا

    billingClient.queryProductDetailsAsync(
queryProductDetailsParams,
new ProductDetailsResponseListener() {
  public void onProductDetailsResponse(
      BillingResult billingResult, QueryProductDetailsResult productDetailsResult) {
    // check billingResult
    // …
    // 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();
          }
        }
      }
    }
  }
});

  2. جریان صورت‌حساب را راه‌اندازی کنید.

    برای شروع درخواست خرید از برنامه‌تان، launchBillingFlow() روش را از رشته اصلی برنامه‌تان فراخوانی کنید. این روش ارجاعی به شیء BillingFlowParams می‌گیرد که حاوی شیء ProductDetails مربوطه است که از فراخوانی queryProductDetailsAsync()‎ به‌دست آمده است. برای ایجاد شیء BillingFlowParams، از BillingFlowParams.Builder class استفاده کنید. توجه داشته باشید که هنگام ایجاد شیء BillingFlowParams باید توکن پیشنهاد مربوط به پیشنهاد انتخاب‌شده توسط کاربر را تنظیم کنید. اگر کاربری برای پیشنهاد ویژه پیش‌سفارش واجدشرایط باشد، پیشنهادی با PreorderDetails و offerId در queryProductDetailsAsync() دریافت خواهد کرد.

    نمونه زیر نحوه راه‌اندازی جریان صورت‌حساب را نشان می‌دهد:

    جاوا

    // An activity reference from which the billing flow will launch.
Activity activity = ...;
ImmutableList productDetailsParamsList =
    ImmutableList.of(
    ProductDetailsParams.newBuilder()
         // retrieve a value for productDetails by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // to get an offer token, call
        // ProductDetails.getOneTimePurchaseOfferDetailsList() 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);

    offerToken را می‌توانید به‌عنوان بخشی از OneTimePurchaseOfferDetails پیدا کنید. وقتی پیشنهاد را به کاربر نشان می‌دهید، مطمئن شوید که پارامترهای جریان صورت‌حساب را با کد پیشنهاد صحیح که می‌توانید از روش oneTimePurchaseOfferDetails.getOfferToken() دریافت کنید پیکربندی کرده‌اید.

پیشنهاد ویژه تخفیف

این بخش توضیح می‌دهد که چگونه می‌توانید پیشنهادهای ویژه تخفیف را برای محصولات یک‌باره خود پیکربندی کنید.

چهار پارامتر مختلف وجود دارد که می‌توانید در پیشنهاد تخفیف محصول یک‌باره پیکربندی کنید:

  • قیمت پیشنهاد ویژه تخفیف‌دار: جزئیات مربوط به تخفیف درصدی یا تخفیف قیمت مطلق از قیمت اصلی را مشخص می‌کند.

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

  • محدودیت خرید (اختیاری): به شما امکان می‌دهد تعیین کنید کاربر چند بار می‌تواند پیشنهاد ویژه یکسانی را پس‌خرید کند. اگر کاربری از حد خرید فراتر برود، کاربر برای پیشنهاد ویژه واجدشرایط نخواهد بود.

  • زمان محدود (اختیاری): دوره زمانی‌ای را که پیشنهاد ویژه دردسترس است مشخص می‌کند. خارج از این دوره زمانی، پیشنهاد ویژه برای خرید واجدشرایط نیست.

بازیابی اطلاعات قیمت پیشنهاد ویژه تخفیف‌گرفته

برای پیشنهاد ویژه تخفیف‌گرفته، می‌توانید درصد تخفیف یا تخفیف قطعی ارائه‌شده را بازیابی کنید.

مثال ۱: بازیابی تخفیف درصدی پیشنهاد ویژه تخفیف‌دار

نمونه زیر نشان می‌دهد که چگونه قیمت کامل اصلی پیشنهاد ویژه تخفیف‌دار و درصد تخفیف آن را دریافت کنید. توجه داشته باشید که اطلاعات تخفیف درصدی فقط برای پیشنهادهای ویژه تخفیف‌گرفته برگردانده می‌شود.

جاوا

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
      public void onProductDetailsResponse(
          BillingResult billingResult, QueryProductDetailsResult productDetailsResult){
        // check billingResult
        // …
        // process productDetailsList returned by QueryProductDetailsResult
        for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
          for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
              productDetails.getOneTimePurchaseOfferDetailsList()) {
            long discountedOfferPriceMicros =
                oneTimePurchaseOfferDetails.getPriceAmountMicros();
            // process the returned fullPriceMicros and percentageDiscount.
            if (oneTimePurchaseOfferDetails.getFullPriceMicros() != null) {
              long fullPriceMicros = oneTimePurchaseOfferDetails.getFullPriceMicros();
            }
            if (oneTimePurchaseOfferDetails.getDiscountDisplayInfo() != null) {
              long percentageDiscount =
                  oneTimePurchaseOfferDetails
                      .getDiscountDisplayInfo()
                      .getPercentageDiscount();
            }
            // …
          }
        }
      }
    });
مثال ۲: دریافت تخفیف قطعی پیشنهاد ویژه تخفیف‌گرفته

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

جاوا

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
      public void onProductDetailsResponse(
          BillingResult billingResult, QueryProductDetailsResult productDetailsResult) {
        // check billingResult
        // …
        // process productDetailsList returned by QueryProductDetailsResult
        for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
          for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
              productDetails.getOneTimePurchaseOfferDetailsList()) {
            long discountedOfferPriceMicros =
                oneTimePurchaseOfferDetails.getPriceAmountMicros();
            // process the returned fullPriceMicros and absolute DiscountAmountMicros.
            if (oneTimePurchaseOfferDetails.getFullPriceMicros() != null) {
              long fullPriceMicros = oneTimePurchaseOfferDetails.getFullPriceMicros();
            }
            if (oneTimePurchaseOfferDetails.getDiscountDisplayInfo() != null) {
              long discountAmountMicros =
                  oneTimePurchaseOfferDetails
                      .getDiscountDisplayInfo()
                      .getDiscountAmount()
                      .getDiscountAmountMicros();
            }
            // …
          }
        }
      }
    });

دریافت بازه زمانی معتبر پیشنهاد ویژه

می‌توانید از روش OneTimePurchaseOfferDetails.getValidTimeWindow() برای دریافت بازه زمانی معتبر برای پیشنهاد ویژه استفاده کنید. این شیء حاوی زمان شروع و پایان پنجره زمانی برحسب میلی‌ثانیه است.

نمونه زیر نشان می‌دهد که چگونه می‌توان پنجره زمانی معتبر یک پیشنهاد ویژه را دریافت کرد:

جاوا

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
      public void onProductDetailsResponse(
          BillingResult billingResult, QueryProductDetailsResult productDetailsResult) {
        // check billingResult
        // …
        // process productDetailsList returned by QueryProductDetailsResult
        for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
          for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
              productDetails.getOneTimePurchaseOfferDetailsList()) {
            if (oneTimePurchaseOfferDetails.getValidTimeWindow() != null) {
              // process the returned startTimeMillis and endTimeMillis.
              ValidTimeWindow validTimeWindow =
                  oneTimePurchaseOfferDetails.getValidTimeWindow();
              long startTimeMillis = validTimeWindow.getStartTimeMillis();
              long endTimeMillis = validTimeWindow.getEndTimeMillis();
              // …
            }
          }
        }
      }
    });

تعداد محدود در سطح پیشنهاد تخفیف

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

  1. Super screensavers دو پیشنهاد ویژه برای محصول محافظ صفحه‌نمایش دارد: گزینه خرید محافظ صفحه‌نمایش و محافظ صفحه‌نمایش تخفیف‌دار.
    1. برای محافظ صفحه‌نمایش گزینه خرید، تعداد محدودی تنظیم نشده است.
    2. تعداد حداکثر مجاز سطح پیشنهاد ویژه در محافظ صفحه‌نمایش تخفیف‌دار روی ۳ تنظیم شده است.
  2. محصول محافظ صفحه‌نمایش حداکثر مقدار مجاز در سطح محصول ندارد، بنابراین کاربران می‌توانند مقادیر نامحدودی از این محصول را خریداری کنند.
  3. کاربر ۱ محافظ صفحه‌نمایش تخفیف‌دار دارد و قصد دارد محافظ صفحه‌نمایش تخفیف‌دار دیگری بخرد.
  4. هنگام بازیابی پیشنهادهای ویژه دردسترس، مقدار LimitedQuantityInfo برای محافظ صفحه‌نمایش گزینه خرید صفر است و مقدار تعداد باقی‌مانده برای محافظ صفحه‌نمایش تخفیف ۲ است.

نمونه زیر نحوه دریافت تعداد محدود در سطح پیشنهاد ویژه تخفیف را نشان می‌دهد:

جاوا

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
      public void onProductDetailsResponse(
          BillingResult billingResult, QueryProductDetailsResult productDetailsResult) {
        // check billingResult
        // …
        // process productDetailsList returned by QueryProductDetailsResult
        for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
          for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
              productDetails.getOneTimePurchaseOfferDetailsList()) {
            if (oneTimePurchaseOfferDetails.getLimitedQuantityInfo() != null) {
              // process the returned maximumQuantity and remainingQuantity.
              LimitedQuantityInfo limitedQuantityInfo =
                  oneTimePurchaseOfferDetails.getLimitedQuantityInfo();
              int maximumQuantity = limitedQuantityInfo.getMaximumQuantity();
              int remainingQuantity = limitedQuantityInfo.getRemainingQuantity();
              // …
            }
          }
        }
      }
    });

وقتی کاربران از حداکثر تعداد پس‌خرید برای یک پیشنهاد استفاده می‌کنند، پیشنهاد توسط روش getOneTimePurchaseOfferDetailsList() برگردانده نمی‌شود.

محاسبه حد پس‌خرید

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

‫Google Play مقدار باقی‌مانده را با کم کردن مقدار تحت مالکیت کاربر از حداکثر مقدار مجاز که تنظیم کرده‌اید محاسبه می‌کند. هنگام شمارش تعداد موارد تحت مالکیت کاربر، Google Play خریدهای مصرف‌شده یا خریدهای معلقه را درنظر می‌گیرد. خریدهایی که لغو، مسترد یا استراداد وجه شده‌اند در تعداد دارایی‌های کاربر محاسبه نمی‌شوند. برای مثال:

  1. محافظ‌های صفحه عالی پیشنهاد تخفیف با حداکثر مقدار مجاز یک راه‌اندازی می‌کنند، بنابراین کاربران می‌توانند حداکثر یک محافظ صفحه تخفیف‌دار خریداری کنند.

  2. کاربر یکی از محافظ‌های صفحه‌نمایش تخفیف‌دار را می‌خرد. اگر کاربر سپس سعی کند محافظ صفحه‌نمایش دوم را با تخفیف بخرد، خطا رخ می‌دهد و PurchasesUpdatedListener کد پاسخ ITEM_UNAVAILABLE را دریافت می‌کند.

  3. کاربر برای محافظ صفحه‌نمایش تخفیف‌خورده‌ای که در ابتدا خریداری کرده است درخواست استرداد مبلغ می‌کند و استرداد مبلغ را باموفقیت دریافت می‌کند. کاربر سعی می‌کند یکی از محافظ‌های صفحه‌نمایش تخفیف‌دار را بخرد و خرید موفق خواهد بود.

واجدشرایط بودن کشور و منطقه

می‌توانید کشورها یا مناطقی را که پیشنهاد ویژه گزینه خرید یا پیشنهاد ویژه تخفیف در آن‌ها برای کاربران دردسترس خواهد بود انتخاب کنید. ‫Google Play واجدشرایط بودن کاربر را براساس کشور Play ارزیابی می‌کند. وقتی دردسترس بودن منطقه‌ای را برای پیشنهاد ویژه‌ای پیکربندی می‌کنید، فقط درصورتی به‌عنوان بخشی از getOneTimePurchaseOfferDetailsList() برگردانده می‌شود که کاربر در کشور یا منطقه موردهدف باشد، درغیراین‌صورت وقتی queryProductDetailsAsync() را فراخوانی می‌کنید، بخشی از فهرست پیشنهادهای ویژه برگردانده‌شده نخواهد بود.

برچسب‌های پیشنهاد

نمونه زیر نحوه بازیابی برچسب‌های پیشنهاد ویژه منسوب به یک پیشنهاد ویژه را نشان می‌دهد.

جاوا

    
billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
      public void onProductDetailsResponse(
          BillingResult billingResult, QueryProductDetailsResult productDetailsResult) {
        // check billingResult
        // …
        // process productDetailsList returned by QueryProductDetailsResult
        for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
          for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
              productDetails.getOneTimePurchaseOfferDetailsList()) {
            // process the returned offer tags.
            ImmutableList<String> offerTags =
                oneTimePurchaseOfferDetails.getOfferTagsList();
            // …
          }
        }
      }
    });

ارث‌بری برچسب‌های پیشنهاد ویژه

می‌توانید برچسب‌های پیشنهاد ویژه را برای محصول، گزینه خرید، یا پیشنهاد تخفیف تنظیم کنید. پیشنهادهای ویژه تخفیف برچسب‌های پیشنهاد ویژه را از پیشنهاد ویژه گزینه خرید خود به ارث می‌برند. به‌طور مشابه، اگر برچسب‌های پیشنهاد ویژه در سطح محصول مشخص شده باشند، هم پیشنهاد ویژه گزینه خرید و هم پیشنهادهای ویژه تخفیف برچسب‌های پیشنهاد ویژه محصول را به ارث می‌برند.

برای مثال، «محافظ صفحه‌نمایش عالی» دو پیشنهاد برای محصول محافظ صفحه‌نمایش دارد: محافظ صفحه‌نمایش با گزینه خرید و محافظ صفحه‌نمایش با تخفیف.

  • محافظ صفحه‌نمایش عالی برچسب پیشنهاد محصول SSProductTag را دارد.
  • محافظ صفحه گزینه خرید دارای برچسب پیشنهاد ویژه SSPurchaseOptionTag است.
  • محافظ صفحه‌نمایش تخفیف‌دار برچسب پیشنهاد ویژه SSDiscountOfferTag را دارد.

در این مثال، روش oneTimePurchaseOfferDetails.getOfferTagsList() برای پیشنهاد ویژه گزینه خرید SSProductTag و SSPurchaseOptionTag را برمی‌گرداند. برای پیشنهاد ویژه تخفیف، این روش SSProductTag، SSPurchaseOptionTag، و SSDiscountOfferTag را برمی‌گرداند.