বাহ্যিক অফার প্রোগ্রামের জন্য ইন-অ্যাপ ইন্টিগ্রেশন নির্দেশিকা

এই নির্দেশিকায় যোগ্য অ্যাপ এবং অঞ্চলগুলিতে বাহ্যিক অফার সমর্থন করার জন্য এপিআই (API)-এর সাথে কীভাবে ইন্টিগ্রেট করতে হয় তা বর্ণনা করা হয়েছে। যোগ্যতার শর্তাবলী এবং ভৌগোলিক পরিধি সহ বাহ্যিক অফার প্রোগ্রাম সম্পর্কে আরও জানতে , প্রোগ্রামের প্রয়োজনীয়তা দেখুন।

প্লে বিলিং লাইব্রেরি সেটআপ

এক্সটার্নাল অফার এপিআই ব্যবহার করতে, আপনার অ্যান্ড্রয়েড অ্যাপে প্লে বিলিং লাইব্রেরি ডিপেন্ডেন্সির ভার্সন ৮.২.১ বা তার উচ্চতর সংস্করণ যোগ করুন । যদি আপনাকে পূর্ববর্তী কোনো সংস্করণ থেকে মাইগ্রেট করতে হয়, তবে এক্সটার্নাল অফার প্রয়োগ করার চেষ্টা করার আগে মাইগ্রেশন গাইডের নির্দেশাবলী অনুসরণ করুন।

Google Play-এর সাথে সংযোগ করুন

ইন্টিগ্রেশন প্রক্রিয়ার প্রথম ধাপগুলো বিলিং ইন্টিগ্রেশন গাইডে বর্ণিত ধাপগুলোর মতোই, তবে আপনার BillingClient ইনিশিয়ালাইজ করার সময় এক্সটার্নাল অফার ব্যবহার করতে চান তা বোঝানোর জন্য আপনাকে অবশ্যই enableBillingProgram কল করতে হবে।

নিম্নলিখিত উদাহরণটি এই পরিবর্তনগুলি সহ একটি BillingClient ইনিশিয়ালাইজ করার পদ্ধতি প্রদর্শন করে:

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

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

BillingClient ইনিশিয়ালাইজ করার পর, ইন্টিগ্রেশন গাইডে বর্ণিত পদ্ধতি অনুযায়ী আপনাকে Google Play-এর সাথে একটি সংযোগ স্থাপন করতে হবে।

উপলব্ধতা যাচাই করুন

বর্তমান ব্যবহারকারীর জন্য বাহ্যিক অফারগুলি উপলব্ধ আছে কিনা তা নিশ্চিত করতে, isBillingProgramAvailableAsync কল করুন।

বাহ্যিক অফার উপলব্ধ থাকলে এই API-টি BillingResponseCode.OK রিটার্ন করে। অন্যান্য রেসপন্স কোডের ক্ষেত্রে আপনার অ্যাপ কীভাবে সাড়া দেবে, সে সম্পর্কে বিস্তারিত জানতে রেসপন্স হ্যান্ডলিং দেখুন।

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

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-তে কোনো বাহ্যিক লেনদেন রিপোর্ট করতে, আপনার অবশ্যই প্লে বিলিং লাইব্রেরি থেকে তৈরি করা একটি বাহ্যিক লেনদেন টোকেন থাকতে হবে। আপনি createBillingProgramReportingDetailsAsync API কল করে এই টোকেনটি পেতে পারেন। প্রতিটি বাহ্যিক অফারের জন্য ব্যবহারকারীকে অ্যাপের বাইরে পাঠানোর ঠিক আগে একটি নতুন টোকেন তৈরি করতে হবে। টোকেনগুলো একাধিক লেনদেনের জন্য ক্যাশ করে রাখা যাবে না।

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

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

বিকল্পভাবে, আপনি কোটলিন এক্সটেনশন ব্যবহার করে createBillingProgramReportingDetailsAsync সাসপেন্ড ফাংশনটি কোয়েরি করতে পারেন, যাতে আপনার কোনো লিসেনার সংজ্ঞায়িত করার প্রয়োজন না হয়:

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

বাহ্যিক অফার প্রবাহ চালু করুন

একটি এক্সটার্নাল অফার ফ্লো শুরু করতে, আপনার যোগ্য অ্যাপটিকে অবশ্যই তার মেইন থ্রেড থেকে launchExternalLink() API-টি কল করতে হবে। এই API-টি ইনপুট হিসেবে একটি LaunchExternalLinkParams অবজেক্ট গ্রহণ করে। একটি LaunchExternalLinkParams অবজেক্ট তৈরি করতে, LaunchExternalLinkParams.Builder ক্লাসটি ব্যবহার করুন। এই ক্লাসে নিম্নলিখিত প্যারামিটারগুলো রয়েছে:

• linkUri - বাহ্যিক ওয়েবসাইটের লিঙ্ক, যেখান থেকে ডিজিটাল কন্টেন্ট বা অ্যাপ ডাউনলোডের সুযোগ দেওয়া হয়। অ্যাপ ডাউনলোডের ক্ষেত্রে, এই লিঙ্কটি প্লে ডেভেলপার কনসোলে অবশ্যই নিবন্ধিত এবং অনুমোদিত হতে হবে।
• লিঙ্কটাইপ - ব্যবহারকারীকে যে ধরনের কন্টেন্ট অফার করা হচ্ছে।
• launchMode - লিঙ্কটি কীভাবে চালু হবে তা নির্দিষ্ট করে। অ্যাপ ডাউনলোডের জন্য, আপনাকে এটি অবশ্যই LAUNCH_IN_EXTERNAL_BROWSER_OR_APP এ সেট করতে হবে।
• billingProgram - এটিকে BillingProgram.EXTERNAL_OFFER এ সেট করুন।

যখন আপনি launchExternalLink() কল করেন, তখন এটি ব্যবহারকারীর সেটিংসের উপর ভিত্তি করে অতিরিক্ত তথ্য ডায়ালগ দেখাতে পারে। launchMode প্যারামিটারের উপর নির্ভর করে, Play হয় লিঙ্ক URI-টি একটি বাহ্যিক ব্রাউজারে চালু করে অথবা URI-টি চালু করার জন্য ফ্লো-টি আপনার অ্যাপে ফেরত পাঠায়। বেশিরভাগ ক্ষেত্রে, আপনি LAUNCH_IN_EXTERNAL_BROWSER_OR_APP মোড ব্যবহার করতে পারেন, যেখানে Play আপনার জন্য URI-টি চালু করে দেবে। আপনি যদি আরও কাস্টমাইজড আচরণ চান, যেমন একটি ওয়েবভিউতে URI-টি চালু করা বা একটি নির্দিষ্ট ব্রাউজারে URI-টি খোলা, তাহলে আপনি CALLER_WILL_LAUNCH_LINK মোড ব্যবহার করতে পারেন। ব্যবহারকারীর গোপনীয়তা রক্ষা করার জন্য, নিশ্চিত করুন যে URI-এর মাধ্যমে কোনো ব্যক্তিগতভাবে শনাক্তযোগ্য তথ্য (PII) পাঠানো হচ্ছে না।

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

// 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 Developer API কল করে সমস্ত বাহ্যিক লেনদেন Google Play-কে রিপোর্ট করতে হবে। যখন আপনি একটি লেনদেন রিপোর্ট করবেন, তখন আপনাকে অবশ্যই createBillingProgramReportingDetailsAsync API থেকে প্রাপ্ত একটি externalTransactionToken প্রদান করতে হবে। যদি কোনো ব্যবহারকারী একাধিক কেনাকাটা করেন, তবে আপনি প্রতিটি কেনাকাটা রিপোর্ট করার জন্য একই externalTransactionToken ব্যবহার করতে পারেন। কীভাবে একটি লেনদেন রিপোর্ট করতে হয় তা জানতে, ব্যাকএন্ড ইন্টিগ্রেশন গাইড দেখুন।

প্রতিক্রিয়া পরিচালনা

যখন কোনো ত্রুটি ঘটে, তখন isBillingProgramAvailableAsync() , createBillingProgramReportingDetailsAsync() , এবং launchExternalLink() মেথডগুলো BillingResponseCode.OK ছাড়া অন্য রেসপন্স রিটার্ন করতে পারে। এই রেসপন্স কোডগুলো নিম্নলিখিতভাবে হ্যান্ডেল করার কথা বিবেচনা করুন:

• ERROR : এটি একটি অভ্যন্তরীণ ত্রুটি। লেনদেনটি সম্পন্ন করবেন না বা বাহ্যিক ওয়েবসাইটটি খুলবেন না। পরবর্তীবার যখন আপনি ব্যবহারকারীকে অ্যাপের বাইরে পাঠাতে চেষ্টা করবেন, তখন তথ্য ডায়ালগটি দেখানোর জন্য launchExternalLink() কল করে পুনরায় চেষ্টা করুন।
• FEATURE_NOT_SUPPORTED : বর্তমান ডিভাইসের প্লে স্টোর বাহ্যিক অফার এপিআই সমর্থন করে না। লেনদেনটি সম্পন্ন করবেন না বা বাহ্যিক ওয়েবসাইটটি খুলবেন না।
• USER_CANCELED : বাহ্যিক ওয়েবসাইটটি খোলার প্রক্রিয়া থেকে বিরত থাকুন। পরবর্তী বার যখন আপনি ব্যবহারকারীকে অ্যাপের বাইরে পাঠাতে চেষ্টা করবেন, তখন তথ্য ডায়ালগটি দেখানোর জন্য launchExternalLink() আবার কল করুন।
• BILLING_UNAVAILABLE : লেনদেনটি বাহ্যিক অফারের জন্য যোগ্য নয় এবং তাই এই প্রোগ্রামের অধীনে এটি সম্পন্ন করা উচিত নয়। এর কারণ হলো, হয় ব্যবহারকারী এই প্রোগ্রামের জন্য যোগ্য কোনো দেশে নেই অথবা আপনার অ্যাকাউন্টটি প্রোগ্রামে সফলভাবে নথিভুক্ত করা হয়নি। যদি দ্বিতীয় কারণটি সত্যি হয়, তাহলে প্লে ডেভেলপার কনসোলে আপনার নথিভুক্তির অবস্থা পরীক্ষা করুন।
• DEVELOPER_ERROR : অনুরোধে একটি ত্রুটি রয়েছে। এগিয়ে যাওয়ার আগে ত্রুটিটি শনাক্ত ও সংশোধন করতে ডিবাগ বার্তাটি ব্যবহার করুন।
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE : এগুলো ক্ষণস্থায়ী ত্রুটি, যা একটি উপযুক্ত পুনঃপ্রচেষ্টা নীতির মাধ্যমে সমাধান করা উচিত। SERVICE_DISCONNECTED এর ক্ষেত্রে, পুনরায় চেষ্টা করার আগে Google Play-এর সাথে সংযোগ পুনঃস্থাপন করুন।

বাহ্যিক অফার পরীক্ষা করুন

আপনার এক্সটার্নাল অফার ইন্টিগ্রেশন পরীক্ষা করার জন্য লাইসেন্স টেস্টার ব্যবহার করা উচিত। লাইসেন্স টেস্টার অ্যাকাউন্ট দ্বারা শুরু করা লেনদেনের জন্য আপনাকে কোনো ইনভয়েস পাঠানো হবে না। লাইসেন্স টেস্টার কনফিগার করার বিষয়ে আরও তথ্যের জন্য ‘অ্যাপ্লিকেশন লাইসেন্সিংয়ের মাধ্যমে ইন-অ্যাপ বিলিং পরীক্ষা করুন’ দেখুন।

পরবর্তী পদক্ষেপ

একবার আপনি অ্যাপের ভেতরের ইন্টিগ্রেশন শেষ করে ফেললে, আপনার ব্যাকএন্ড ইন্টিগ্রেট করার জন্য আপনি প্রস্তুত।