راهنمای ادغام درون برنامه ای برای برنامه پیشنهادات خارجی

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

راه‌اندازی کتابخانه صورت‌حساب Play

برای استفاده از APIهای پیشنهادات خارجی، نسخه 6.2.1 یا بالاتر از وابستگی Play Billing Library را به برنامه Android خود اضافه کنید . اگر نیاز به مهاجرت از نسخه قبلی دارید، قبل از اجرای پیشنهادات خارجی، دستورالعمل‌های راهنمای مهاجرت را دنبال کنید.

به Google Play متصل شوید

اولین مراحل در فرآیند یکپارچه سازی همان مراحلی است که در راهنمای یکپارچه سازی صورتحساب توضیح داده شده است، با چند تغییر در هنگام راه اندازی BillingClient :

• برای نشان دادن اینکه می‌خواهید از پیشنهادات خارجی استفاده کنید، باید یک روش جدید فراخوانی کنید: enableExternalOffer .

مثال زیر راه اندازی اولیه BillingClient با این تغییرات نشان می دهد:

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

پس از اینکه BillingClient مقداردهی اولیه کردید، باید همانطور که در راهنمای ادغام توضیح داده شده است ، با Google Play ارتباط برقرار کنید .

در دسترس بودن را بررسی کنید

برنامه شما باید با تماس با isExternalOfferAvailableAsync تأیید کند که پیشنهادات خارجی موجود است.

اگر پیشنهادات خارجی موجود باشد، این API BillingResponseCode.OK را برمی‌گرداند. برای جزئیات در مورد نحوه پاسخگویی برنامه شما به سایر کدهای پاسخ، به مدیریت پاسخ مراجعه کنید.

billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers unavailable, etc.
            return
        }

        // External offers are available. Continue with steps in the
        // guide.
})

billingClient.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }

});

یک توکن تراکنش خارجی آماده کنید

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

billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

گفتگوی اطلاعات برای کاربران

برای ادغام با پیشنهادات خارجی، برنامه واجد شرایط شما باید صفحه اطلاعاتی را نشان دهد که به کاربران کمک می کند بفهمند که خارج از برنامه به یک وب سایت خارجی هدایت می شوند. هر بار قبل از پیوند دادن به یک پیشنهاد خارجی، صفحه اطلاعات باید با تماس با showExternalOfferInformationDialog API به کاربران نشان داده شود.

// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

اگر این روش BillingResponseCode.OK را برگرداند، برنامه شما می‌تواند کاربر را به وب‌سایت خارجی هدایت کند. اگر روش BillingResponseCode.USER_CANCELED را برمی گرداند، برنامه شما نباید به باز کردن وب سایت ادامه دهد.

معاملات را به Google Play گزارش دهید

همه تراکنش‌های خارجی باید با تماس با Google Play Developer API از باطن خود به Google Play گزارش شوند. تراکنش‌های خارجی باید در حین ارائه یک externalTransactionToken که با استفاده از API createExternalOfferReportingDetailsAsync به دست آمده است، گزارش شود. اگر کاربری چندین خرید انجام دهد، می‌توانید از همان externalTransactionToken برای گزارش هر خرید استفاده کنید. برای آشنایی با نحوه گزارش یک تراکنش، به راهنمای ادغام باطن مراجعه کنید.

رسیدگی به پاسخ

هنگامی که خطایی رخ می دهد، روش های isExternalOfferAvailableAsync ، createExternalOfferReportingDetailsAsync ، و showExternalOfferInformationDialog ممکن است پاسخ هایی غیر از BillingResponseCode.OK برگردانند. مدیریت این کدهای پاسخ را به صورت زیر در نظر بگیرید:

• ERROR : این یک خطای داخلی است. تراکنش یا باز کردن وب سایت خارجی را ادامه ندهید. با فراخوانی showExternalOfferInformationDialog() دوباره سعی کنید تا دفعه بعد که سعی می‌کنید کاربر را به خارج از برنامه هدایت کنید، گفتگوی اطلاعات را به کاربر نمایش دهید.
• FEATURE_NOT_SUPPORTED : APIهای پیشنهادات خارجی توسط فروشگاه Play در دستگاه فعلی پشتیبانی نمی‌شوند. تراکنش یا باز کردن وب سایت خارجی را ادامه ندهید.
• USER_CANCELED : به باز کردن وب سایت خارجی ادامه ندهید. دوباره با showExternalOfferInformationDialog() تماس بگیرید تا دفعه بعد که سعی می کنید کاربر را به خارج از برنامه هدایت کنید، گفتگوی اطلاعات را به کاربر نمایش دهید.
• BILLING_UNAVAILABLE : تراکنش برای پیشنهادات خارجی واجد شرایط نیست و بنابراین نباید تحت این برنامه ادامه یابد. این به این دلیل است که کاربر در کشوری واجد شرایط برای این برنامه نیست یا حساب شما با موفقیت در برنامه ثبت نام نکرده است. اگر دومی است، وضعیت ثبت نام خود را در Play Developer Console بررسی کنید.
• DEVELOPER_ERROR : در درخواست خطایی وجود دارد. قبل از ادامه، از پیام اشکال زدایی برای شناسایی و تصحیح خطا استفاده کنید.
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE : اینها خطاهای گذرا هستند که باید با یک خط مشی امتحان مجدد مناسب مدیریت شوند. در مورد SERVICE_DISCONNECTED ، قبل از تلاش مجدد، دوباره با Google Play ارتباط برقرار کنید.

پیشنهادات خارجی را تست کنید

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

مراحل بعدی

هنگامی که یکپارچه سازی درون برنامه ای را به پایان رساندید، آماده ادغام باطن خود هستید.