बाहरी कॉन्टेंट के लिंक के लिए, ऐप्लिकेशन में इंटिग्रेशन से जुड़े दिशा-निर्देश

इस दस्तावेज़ में, Play Billing Library API को इंटिग्रेट करने का तरीका बताया गया है, ताकि ज़रूरी शर्तें पूरी करने वाले ऐप्लिकेशन में बाहरी कॉन्टेंट के लिंक दिए जा सकें. इसमें अमेरिका में रहने वाले लोगों को Play पर मौजूद आपके ऐप्लिकेशन से बाहर किसी अन्य प्लैटफ़ॉर्म पर भेजने की सुविधा शामिल है. इससे लोगों को ऐप्लिकेशन में मौजूद डिजिटल कॉन्टेंट और ऐप्लिकेशन डाउनलोड करने के ऑफ़र दिए जा सकते हैं. इस प्रोग्राम के बारे में ज़्यादा जानने के लिए, प्रोग्राम की ज़रूरी शर्तें देखें.

Play Billing Library सेटअप करना

अपने Android ऐप्लिकेशन में Play Billing Library की डिपेंडेंसी जोड़ें. बाहरी लिंक वाले एपीआई इस्तेमाल करने के लिए, आपको 8.2 या इससे नया वर्शन इस्तेमाल करना होगा. अगर आपको किसी पुराने वर्शन से माइग्रेट करना है, तो बाहरी कॉन्टेंट के लिंक जोड़ने से पहले, माइग्रेशन गाइड में दिए गए निर्देशों का पालन करें.

बिलिंग क्लाइंट शुरू करना

बिलिंग क्लाइंट को शुरू करने के लिए, BillingClient को शुरू करें में बताया गया तरीका अपनाएं. हालांकि, इसमें ये बदलाव करें:

  • PurchasesUpdatedListener को चालू न करें - बाहरी कॉन्टेंट के लिंक के लिए, इस लिसनर की ज़रूरत नहीं है.
  • BillingProgram.EXTERNAL_CONTENT_LINK के साथ enableBillingProgram() को कॉल करें, ताकि यह पता चल सके कि आपका ऐप्लिकेशन बाहरी कॉन्टेंट के लिंक का इस्तेमाल करता है.

यहां दिए गए उदाहरण में, इन बदलावों के साथ BillingClient को शुरू करने का तरीका दिखाया गया है:

Kotlin

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

Java

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

Google Play से कनेक्ट करें

BillingClient को शुरू करने के बाद, Google Play से कनेक्ट करें में दिए गए तरीके से Google Play से कनेक्ट करें.

उपयोगकर्ता के लिए ज़रूरी शर्तें देखना

Google Play से कनेक्ट करने के बाद, आपको यह देखना होगा कि उपयोगकर्ता, बाहरी कॉन्टेंट पर ले जाने वाले लिंक के प्रोग्राम में शामिल होने की ज़रूरी शर्तें पूरी करता है या नहीं. इसके लिए, isBillingProgramAvailableAsync() तरीके का इस्तेमाल करें. अगर उपयोगकर्ता, बाहरी कॉन्टेंट लिंक करने के प्रोग्राम में शामिल होने की ज़रूरी शर्तें पूरी करता है, तो यह तरीका BillingResponseCode.OK दिखाता है. यहां दिए गए सैंपल में, बाहरी कॉन्टेंट पर ले जाने वाले लिंक की सुविधा इस्तेमाल करने की ज़रूरी शर्तें पूरी करने वाले उपयोगकर्ता की जांच करने का तरीका बताया गया है:

Kotlin

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.
      }
    })

Java

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.
      }

    });

अन्य रिस्पॉन्स कोड के लिए, आपका ऐप्लिकेशन किस तरह से जवाब देगा, इस बारे में जानने के लिए रिस्पॉन्स हैंडलिंग सेक्शन देखें. अगर Kotlin एक्सटेंशन का इस्तेमाल किया जा रहा है, तो Kotlin कोरूटीन का इस्तेमाल किया जा सकता है. इससे आपको अलग से लिसनर तय करने की ज़रूरत नहीं पड़ती.

बाहरी लेन-देन का टोकन तैयार करना

इसके बाद, आपको Play Billing Library से बाहरी लेन-देन का टोकन जनरेट करना होगा. जब भी उपयोगकर्ता, External Links API के ज़रिए किसी बाहरी वेबसाइट पर जाता है, तब एक नया बाहरी लेन-देन टोकन जनरेट किया जाना चाहिए. इसके लिए, createBillingProgramReportingDetailsAsync एपीआई को कॉल करें. टोकन को उपयोगकर्ता के लिंक आउट होने से ठीक पहले जनरेट किया जाना चाहिए.

ध्यान दें: बाहरी लेन-देन के टोकन को कभी भी कैश मेमोरी में सेव नहीं किया जाना चाहिए. साथ ही, जब भी उपयोगकर्ता को लिंक आउट किया जाता है, तब आपको एक नया टोकन जनरेट करना चाहिए.

Kotlin

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.
    }
  })

Java

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.
      }
  });

अगर Kotlin एक्सटेंशन का इस्तेमाल किया जा रहा है, तो Kotlin कोरूटीन का इस्तेमाल किया जा सकता है. इससे आपको अलग से लिसनर तय करने की ज़रूरत नहीं पड़ती.

बाहरी लिंक लॉन्च करना

बाहरी लेन-देन का टोकन तैयार होने के बाद, उपयोगकर्ता को ऐप्लिकेशन से बाहर किसी डिजिटल कॉन्टेंट के ऑफ़र या ऐप्लिकेशन डाउनलोड करने के लिए लिंक किया जा सकता है. इसके लिए, launchExternalLink तरीके को कॉल करें. इस एपीआई को कॉल करने पर, Google Play उपयोगकर्ता को अतिरिक्त जानकारी वाले डायलॉग दिखा सकता है. यह उपयोगकर्ता की सेटिंग पर निर्भर करता है.

launchExternalLink तरीके को कॉल करते समय, बाहरी लिंक की जानकारी LaunchExternalLinkParams के ज़रिए दी जानी चाहिए. इस क्लास में ये पैरामीटर शामिल हैं:

  • लिंक यूआरआई - यह उस बाहरी वेबसाइट का लिंक होता है जहां डिजिटल कॉन्टेंट या ऐप्लिकेशन डाउनलोड करने का विकल्प दिया जाता है. ऐप्लिकेशन डाउनलोड करने के लिए, इस लिंक को Play Console में रजिस्टर करना होगा. साथ ही, इसे मंज़ूरी मिलनी चाहिए.
  • लिंक का टाइप - उपयोगकर्ता को किस तरह का कॉन्टेंट ऑफ़र किया जा रहा है.
  • लॉन्च मोड - इससे पता चलता है कि लिंक को कैसे लॉन्च किया जाता है. ऐप्लिकेशन डाउनलोड के लिए, आपको इसे LAUNCH_IN_EXTERNAL_BROWSER_OR_APP पर सेट करना होगा.
  • बिलिंग प्रोग्राम - इसे BillingProgram.EXTERNAL_CONTENT_LINK पर सेट करें.

Kotlin

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)

Java

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.OK के अलावा कोई दूसरा BillingResponseCode दे सकते हैं. इन रिस्पॉन्स कोड को इस तरह से हैंडल करें:

  • ERROR: यह एक इंटरनल गड़बड़ी है. लेन-देन या बाहरी वेबसाइट खोलने की प्रोसेस को आगे न बढ़ाएं. एपीआई को फिर से कॉल करके या launchExternalLink() को कॉल करके फिर से कोशिश करें. ऐसा तब करें, जब आपको उपयोगकर्ता को ऐप्लिकेशन से बाहर ले जाना हो.
  • FEATURE_NOT_SUPPORTED: बाहरी कॉन्टेंट के लिंक वाले एपीआई, इस डिवाइस पर Play Store के साथ काम नहीं करते. लेन-देन या बाहरी वेबसाइट खोलने की प्रोसेस को आगे न बढ़ाएं.
  • USER_CANCELED: बाहरी वेबसाइट को खोलने की प्रोसेस को आगे न बढ़ाएं. जब आपको उपयोगकर्ता को ऐप्लिकेशन से बाहर रीडायरेक्ट करना हो, तब launchExternalLink() को फिर से कॉल करें.
  • BILLING_UNAVAILABLE: यह लेन-देन, बाहरी कॉन्टेंट के लिंक दिखाने की सुविधा के लिए ज़रूरी शर्तें पूरी नहीं करता. इसलिए, इस प्रोग्राम के तहत आगे नहीं बढ़ा जा सकता. ऐसा इसलिए हो सकता है, क्योंकि उपयोगकर्ता उस देश में नहीं है जहां यह प्रोग्राम उपलब्ध है. इसके अलावा, ऐसा भी हो सकता है कि आपका खाता इस प्रोग्राम में रजिस्टर न हुआ हो. अगर ऐसा है, तो Play Console में जाकर देखें कि आपने प्रोग्राम में रजिस्टर किया है या नहीं.
  • DEVELOPER_ERROR: अनुरोध में कोई गड़बड़ी है. आगे बढ़ने से पहले, गड़बड़ी की पहचान करने और उसे ठीक करने के लिए, डीबग मैसेज का इस्तेमाल करें.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: ये कुछ समय के लिए होने वाली गड़बड़ियां हैं. इन्हें फिर से कोशिश करने की सही नीति के साथ ठीक किया जाना चाहिए. SERVICE_DISCONNECTED के मामले में, फिर से कोशिश करने से पहले Google Play से कनेक्शन फिर से बनाएं.

बाहरी कॉन्टेंट के लिंक की जांच करना

बाहरी ऑफ़र के इंटिग्रेशन की जांच करने के लिए, लाइसेंस टेस्टर का इस्तेमाल किया जाना चाहिए. लाइसेंस टेस्टर खातों से किए गए लेन-देन के लिए, आपको इनवॉइस नहीं भेजा जाएगा. लाइसेंस टेस्टर को कॉन्फ़िगर करने के बारे में ज़्यादा जानने के लिए, ऐप्लिकेशन का लाइसेंस देने के साथ इन-ऐप्लिकेशन बिलिंग की जांच करना लेख पढ़ें.

अगले चरण

ऐप्लिकेशन में इंटिग्रेशन पूरा करने के बाद, बैकएंड को इंटिग्रेट किया जा सकता है.