Harici içerik bağlantıları için uygulama içi entegrasyon rehberi

Bu belgede, uygun uygulamalarda harici içerik bağlantıları sunmak için Play Faturalandırma Kitaplığı API'lerinin nasıl entegre edileceği açıklanmaktadır. Buna, ABD'deki kullanıcıları Play uygulamanızın dışına bağlayarak uygulama içi dijital içerik ve uygulama indirme teklifleri sunma özelliği de dahildir. Bu program hakkında daha fazla bilgi edinmek için program şartlarını inceleyin.

Play Faturalandırma Kitaplığı kurulumu

Android uygulamanıza Play Faturalandırma Kitaplığı bağımlılığını ekleyin. Harici bağlantılar API'lerini kullanmak için 8.2 veya daha yeni bir sürüm kullanmanız gerekir. Daha eski bir sürümden geçiş yapmanız gerekiyorsa harici içerik bağlantılarını eklemeden önce taşıma rehberindeki talimatları uygulayın.

Fatura istemcisini başlatma

Faturalandırma istemcisini başlatmak için BillingClient başlatma bölümünde açıklanan adımları uygulayın. Ancak aşağıdaki değişiklikleri yapın:

  • PurchasesUpdatedListener öğesini etkinleştirmeyin. Bu dinleyici, harici içerik bağlantıları için gerekli değildir.
  • Uygulamanızın harici içerik bağlantılarını kullandığını belirtmek için enableBillingProgram() ile BillingProgram.EXTERNAL_CONTENT_LINK işlevini çağırın.

Aşağıdaki örnekte, bu değişikliklerle bir BillingClient başlatma işlemi gösterilmektedir:

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'e bağlanma

BillingClient cihazını başlattıktan sonra Google Play'e bağlanma başlıklı makalede açıklandığı şekilde Google Play'e bağlanın.

Kullanıcı uygunluğunu kontrol etme

Google Play'e bağlandıktan sonra isBillingProgramAvailableAsync() yöntemini çağırarak kullanıcının harici içerik bağlantıları programına uygun olup olmadığını kontrol etmeniz gerekir. Bu yöntem, kullanıcı harici içerik bağlantıları programına uygunsa BillingResponseCode.OK değerini döndürür. Aşağıdaki örnekte, harici içerik bağlantıları için kullanıcı uygunluğunun nasıl kontrol edileceği gösterilmektedir:

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

    });

Uygulamanızın diğer yanıt kodlarına nasıl yanıt vermesi gerektiğiyle ilgili ayrıntılar için yanıt işleme bölümüne bakın. Kotlin uzantılarını kullanıyorsanız ayrı bir dinleyici tanımlamanıza gerek kalmaması için Kotlin eşzamanlı rutinlerini kullanabilirsiniz.

Harici işlem jetonu hazırlama

Ardından, Play Billing Library'den harici bir işlem jetonu oluşturmanız gerekir. Kullanıcı, harici bağlantılar API'si aracılığıyla harici bir web sitesini her ziyaret ettiğinde yeni bir harici işlem jetonu oluşturulmalıdır. Bu işlem, createBillingProgramReportingDetailsAsync API'si çağrılarak yapılabilir. Kullanıcı bağlantısı kaldırılmadan hemen önce jeton oluşturulmalıdır.

Not: Harici işlem jetonu hiçbir zaman önbelleğe alınmamalıdır ve kullanıcı her yönlendirildiğinde yeni bir jeton oluşturmanız gerekir.

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 uzantılarını kullanıyorsanız ayrı bir dinleyici tanımlamanıza gerek kalmaması için Kotlin eşzamanlı rutinlerini kullanabilirsiniz.

Harici bağlantıyı başlatma

Harici işlem jetonu hazır olduktan sonra kullanıcı, launchExternalLink yöntemi çağrılarak uygulama dışında dijital içerik teklifine veya uygulama indirme işlemine yönlendirilebilir. Bu API'yi çağırdığınızda Google Play, kullanıcı ayarlarına bağlı olarak kullanıcıya ek bilgi iletişim kutuları gösterebilir.

launchExternalLink yöntemi çağrıldığında, harici bağlantının ayrıntıları LaunchExternalLinkParams aracılığıyla sağlanmalıdır. Bu sınıf aşağıdaki parametreleri içerir:

  • Bağlantı URI'si: Dijital içeriğin veya uygulama indirme işleminin sunulduğu harici web sitesinin bağlantısı. Uygulama indirmeleri için bu bağlantının Play Console'da kaydedilip onaylanması gerekir.
  • Bağlantı Türü: Kullanıcıya sunulan içerik türü.
  • Başlatma Modu: Bağlantının nasıl başlatılacağını belirtir. Uygulama indirme işlemlerinde bu değeri LAUNCH_IN_EXTERNAL_BROWSER_OR_APP olarak ayarlamanız gerekir.

  • Faturalandırma Programı: Bunu BillingProgram.EXTERNAL_CONTENT_LINK olarak ayarlayın.

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

Yanıt işleme

Bir hata oluştuğunda isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() ve onLaunchExternalLinkResponse() yöntemleri BillingResponseCode.OK dışında bir BillingResponseCode sağlayabilir. Bu yanıt kodlarını aşağıdaki şekilde ele alabilirsiniz:

  • ERROR: Bu bir dahili hatadır. İşleme devam etmeyin veya harici web sitesini açmayın. API'yi tekrar çağırarak veya kullanıcıyı uygulamanın dışına yönlendirmeyi bir sonraki denemenizde launchExternalLink() çağırarak yeniden deneyin.
  • FEATURE_NOT_SUPPORTED: Harici içerik bağlantısı API'leri, mevcut cihazdaki Play Store tarafından desteklenmiyor. İşleme devam etmeyin veya harici web sitesini açmayın.
  • USER_CANCELED: Harici web sitesini açma işlemine devam etmeyin. Kullanıcıyı uygulamanın dışına yönlendirmeyi bir sonraki denemenizde tekrar arayın.launchExternalLink()
  • BILLING_UNAVAILABLE: İşlem, harici içerik bağlantıları için uygun değildir ve bu nedenle bu program kapsamında devam etmez. Bunun nedeni, kullanıcının bu programa uygun bir ülkede olmaması veya hesabınızın programa başarıyla kaydedilmemiş olmasıdır. Bu durum söz konusuysa Play Console'da kayıt durumunuzu kontrol edin.
  • DEVELOPER_ERROR: İstekle ilgili bir hata var. Devam etmeden önce hatayı belirlemek ve düzeltmek için hata ayıklama mesajını kullanın.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: Bunlar, uygun bir yeniden deneme politikasıyla ele alınması gereken geçici hatalardır. SERVICE_DISCONNECTED durumunda, yeniden denemeden önce Google Play ile bağlantıyı yeniden kurun.

Harici içerik bağlantılarını test etme

Harici teklif entegrasyonunuzu test etmek için lisans test kullanıcıları kullanılmalıdır. Lisans test edici hesapları tarafından başlatılan işlemler için faturalandırılmazsınız. Lisans test kullanıcılarını yapılandırma hakkında daha fazla bilgi için Uygulama içi faturalandırmayı uygulama lisanslama ile test etme başlıklı makaleyi inceleyin.

Sonraki adımlar

Uygulama içi entegrasyonu tamamladıktan sonra arka ucunuzu entegre etmeye hazırsınızdır.