External Offers Program के लिए इन-ऐप्लिकेशन इंटिग्रेशन के दिशा-निर्देश

इस गाइड में, ज़रूरी शर्तें पूरी करने वाले ऐप्लिकेशन और देशों/इलाकों में बाहरी ऑफ़र दिखाने के लिए, एपीआई के साथ इंटिग्रेट करने का तरीका बताया गया है. External Offers Program के बारे में ज़्यादा जानने के लिए, प्रोग्राम की ज़रूरी शर्तें देखें. इसमें ज़रूरी शर्तें और भौगोलिक दायरा शामिल है.

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

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

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

इंटिग्रेशन की प्रोसेस के शुरुआती चरण, बिलिंग इंटिग्रेशन गाइड में बताए गए चरणों के जैसे ही होते हैं. हालांकि, आपको BillingClient को शुरू करते समय enableBillingProgram को कॉल करना होगा, ताकि यह पता चल सके कि आपको बाहरी ऑफ़र इस्तेमाल करने हैं:

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

Kotlin

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

Java

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

BillingClient को शुरू करने के बाद, आपको Google Play से कनेक्शन सेट अप करना होगा. इसके बारे में इंटिग्रेशन गाइड में बताया गया है.

उपलब्धता की जानकारी पाएं

यह पुष्टि करने के लिए कि बाहरी ऑफ़र, मौजूदा उपयोगकर्ता के लिए उपलब्ध हैं, isBillingProgramAvailableAsync को कॉल करें.

अगर बाहरी ऑफ़र उपलब्ध हैं, तो यह एपीआई BillingResponseCode.OK दिखाता है. आपका ऐप्लिकेशन अन्य रिस्पॉन्स कोड के लिए कैसे जवाब देगा, इस बारे में जानने के लिए रिस्पॉन्स हैंडलिंग देखें.

Kotlin


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingResult: BillingResult,
      billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails) {
        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.
      }
  })

Java


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        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 Billing Library से जनरेट किया गया बाहरी लेन-देन का टोकन होना चाहिए. createBillingProgramReportingDetailsAsync एपीआई को कॉल करके, यह टोकन पाया जा सकता है. उपयोगकर्ता को ऐप्लिकेशन से बाहर ले जाने से ठीक पहले, हर बाहरी ऑफ़र के लिए एक नया टोकन जनरेट किया जाना चाहिए. टोकन को लेन-देन के दौरान कैश मेमोरी में सेव नहीं किया जाना चाहिए.

Kotlin

val params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
    }
})

Java

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

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

  val createBillingProgramReportingDetailsResult =
    withContext(context) {
      billingClient
        .createBillingProgramReportingDetails(params)
    }
  // Process the result

बाहरी ऑफ़र का फ़्लो लॉन्च करें

ऐप्लिकेशन के बाहर ऑफ़र वगैरह प्रमोट करने की सुविधा का इस्तेमाल शुरू करने के लिए, ज़रूरी शर्तें पूरी करने वाले ऐप्लिकेशन को अपने ऐप्लिकेशन के मुख्य थ्रेड से launchExternalLink() एपीआई को कॉल करना होगा. यह एपीआई, LaunchExternalLinkParams ऑब्जेक्ट का इनपुट लेता है. LaunchExternalLinkParams ऑब्जेक्ट बनाने के लिए, LaunchExternalLinkParams.Builder क्लास का इस्तेमाल करें. इस क्लास में ये पैरामीटर शामिल हैं:

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

launchExternalLink() को कॉल करने पर, उपयोगकर्ता की सेटिंग के आधार पर उसे अतिरिक्त जानकारी वाले डायलॉग दिख सकते हैं. launchMode पैरामीटर के आधार पर, Play या तो लिंक यूआरआई को किसी बाहरी ब्राउज़र में लॉन्च करता है या यूआरआई लॉन्च करने के लिए, फ़्लो को आपके ऐप्लिकेशन पर वापस भेजता है. ज़्यादातर मामलों में, LAUNCH_IN_EXTERNAL_BROWSER_OR_APP मोड का इस्तेमाल किया जा सकता है. इस मोड में, Play आपके लिए यूआरआई लॉन्च करेगा. अगर आपको अपनी पसंद के मुताबिक ज़्यादा सुविधाएं चाहिए, जैसे कि वेबव्यू में यूआरआई लॉन्च करना या किसी खास ब्राउज़र में यूआरआई खोलना, तो CALLER_WILL_LAUNCH_LINK मोड का इस्तेमाल करें. उपयोगकर्ता की निजता की सुरक्षा के लिए, पक्का करें कि यूआरआई में व्यक्तिगत पहचान से जुड़ी कोई जानकारी (पीआईआई) न भेजी गई हो.

Kotlin


// An activity reference from which the external offers flow will be launched.
val activity = ...;

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    // You can pass along the external transaction token from
    // BillingProgramReportingDetails as a URL parameter in the URI
    .setLinkUri(yourLinkUri)
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
  LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(billingResult: BillingResult) {
    if (billingResult.responseCode == BillingResponseCode.OK) {
      // Proceed with the rest of the external offer flow. If the user
      // purchases an item, be sure to report the transaction to Google Play.
    } else {
      // Handle failures such as retrying due to network errors.
    }
  }
}

billingClient.launchExternalLink(activity, params, listener)

Java


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

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .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.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

अगर आपने LaunchMode को CALLER_WILL_LAUNCH_LINK पर सेट किया है, तो उपयोगकर्ता को ऐप्लिकेशन से बाहर सिर्फ़ तब रीडायरेक्ट करें, जब onLaunchExternalLinkResponse, BillingResponseCode.OK उपलब्ध कराए.

Google Play को लेन-देन की जानकारी देना

आपको सभी बाहरी लेन-देन की जानकारी Google Play को देनी होगी. इसके लिए, अपने बैकएंड से Google Play Developer API को कॉल करें. किसी लेन-देन की रिपोर्ट करते समय, आपको createBillingProgramReportingDetailsAsync API से मिला externalTransactionToken देना होगा. अगर कोई उपयोगकर्ता एक से ज़्यादा खरीदारी करता है, तो हर खरीदारी की जानकारी देने के लिए, एक ही externalTransactionToken का इस्तेमाल किया जा सकता है. किसी लेन-देन की शिकायत करने का तरीका जानने के लिए, बैकएंड इंटिग्रेशन गाइड देखें.

जवाब मैनेज करना

गड़बड़ी होने पर, isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync(), और launchExternalLink() तरीके, BillingResponseCode.OK के अलावा अन्य जवाब दे सकते हैं. इन रिस्पॉन्स कोड को इस तरह से मैनेज करें:

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

बाहरी ऑफ़र की जांच करना

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

अगले चरण

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