راهنمای ادغام درون برنامه‌ای برای لینک‌های محتوای خارجی

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

راه‌اندازی کتابخانه پرداخت بازی

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

کلاینت صورتحساب را مقداردهی اولیه کنید

برای مقداردهی اولیه کلاینت صورتحساب، همان مراحل توضیح داده شده در «مقداردهی اولیه BillingClient را با تغییرات زیر دنبال کنید:

  • PurchasesUpdatedListener فعال نکنید - این شنونده برای لینک‌های محتوای خارجی مورد نیاز نیست.
  • فراخوانی enableBillingProgram() به همراه BillingProgram.EXTERNAL_CONTENT_LINK برای نشان دادن اینکه برنامه شما از لینک‌های محتوای خارجی استفاده می‌کند.

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

کاتلین

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
  .build()

جاوا

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .build();

اتصال به گوگل پلی

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

بررسی صلاحیت کاربر

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

کاتلین

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return
        }

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

جاوا

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare an external
        // transaction token.
      }

    });

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

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

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

نکته : توکن تراکنش خارجی هرگز نباید ذخیره شود و شما باید هر بار که کاربر به بیرون لینک می‌شود، یک توکن جدید ایجاد کنید.

کاتلین

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
    }
  })

جاوا

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

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

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

لینک خارجی را راه اندازی کنید

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

هنگام فراخوانی متد launchExternalLink ، جزئیات لینک خارجی باید از طریق LaunchExternalLinkParams ارائه شود. این کلاس شامل پارامترهای زیر است:

  • لینک یوآرآی - لینک به وب‌سایت خارجی که محتوای دیجیتال یا دانلود برنامه در آن ارائه می‌شود. برای دانلود برنامه، این لینک باید در کنسول توسعه‌دهندگان پلی ثبت و تأیید شود.
  • نوع لینک - نوع محتوایی که به کاربر ارائه می‌شود.
  • حالت راه‌اندازی - نحوه‌ی راه‌اندازی لینک را مشخص می‌کند. برای دانلود برنامه‌ها، باید این را روی LAUNCH_IN_EXTERNAL_BROWSER_OR_APP تنظیم کنید.
  • برنامه‌ی پرداخت - این را روی BillingProgram.EXTERNAL_CONTENT_LINK تنظیم کنید.

کاتلین

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

جاوا

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

مدیریت پاسخ

وقتی خطایی رخ می‌دهد، متدهای isBillingProgramAvailableAsync() و createBillingProgramReportingDetailsAsync() و onLaunchExternalLinkResponse() ممکن است BillingResponseCode دیگری غیر از BillingResponseCode.OK ارائه دهند. مدیریت این کدهای پاسخ را به صورت زیر در نظر بگیرید:

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

آزمایش لینک‌های محتوای خارجی

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

مراحل بعدی

پس از اتمام یکپارچه‌سازی درون‌برنامه‌ای، آماده یکپارچه‌سازی backend خود هستید.