Harici fırsatlar programı için uygulama içi entegrasyon kılavuzu

Bu kılavuzda, uygun uygulama ve bölgelerde dış kampanyaları desteklemek için API'lerle nasıl entegrasyon yapılacağı açıklanmaktadır. Uygunluk koşulları ve coğrafi kapsam dahil olmak üzere dış kampanya programı hakkında daha fazla bilgi edinmek için program şartları başlıklı makaleyi inceleyin.

Play Faturalandırma Kitaplığı kurulumu

Harici teklif API'lerini kullanmak için Android uygulamanıza Play Faturalandırma Kitaplığı bağımlılığının 8.2 veya sonraki bir sürümünü ekleyin. Daha önceki bir sürümden geçiş yapmanız gerekiyorsa harici teklifleri uygulamaya çalışmadan önce geçiş kılavuzundaki talimatları uygulayın.

Google Play'e bağlanma

Entegrasyon sürecindeki ilk adımlar, faturalandırma entegrasyon kılavuzunda açıklanan adımlarla aynıdır. Ancak BillingClient'ınızı başlatırken harici teklifleri kullanmak istediğinizi belirtmek için enableBillingProgram işlevini çağırmanız gerekir:

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

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

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

BillingClient başlatıldıktan sonra, entegrasyon kılavuzunda açıklandığı gibi Google Play'e bağlantı oluşturmanız gerekir.

Müsaitlik durumunu kontrol edin

Harici tekliflerin mevcut kullanıcı tarafından kullanılabilir olduğunu onaylamak için isBillingProgramAvailableAsync işlevini çağırın.

Bu API, harici teklifler varsa BillingResponseCode.OK değerini döndürür. 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ünü inceleyin.

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

Harici işlem jetonu hazırlama

Harici bir işlemi Google Play'e bildirmek için Play Faturalandırma Kitaplığı'ndan oluşturulmuş bir harici işlem jetonunuzun olması gerekir. Bu jetonu createBillingProgramReportingDetailsAsync API'sini çağırarak alabilirsiniz. Kullanıcıyı uygulama dışına yönlendirmeden hemen önce her harici teklif için yeni bir jeton oluşturulmalıdır. Jetonlar işlemler arasında önbelleğe alınmamalıdır.

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

Alternatif olarak, bir işleyici tanımlamanıza gerek kalmaması için askıya alma işlevini createBillingProgramReportingDetailsAsync Kotlin uzantılarıyla sorgulayabilirsiniz:

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

Harici teklif akışını başlatma

Harici teklif akışı başlatmak için uygun uygulamanız, uygulamanızın ana iş parçacığından launchExternalLink() API'sini çağırmalıdır. Bu API, LaunchExternalLinkParams nesnesinin girişini alır. LaunchExternalLinkParams nesnesi oluşturmak için LaunchExternalLinkParams.Builder sınıfını kullanın. Bu sınıfta aşağıdaki parametreler bulunur:

• linkUri: 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.
• linkType: Kullanıcıya sunulan içerik türü.
• launchMode: 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.
• billingProgram: Bunu BillingProgram.EXTERNAL_OFFER olarak ayarlayın.

launchExternalLink() işlevini çağırdığınızda, kullanıcı ayarlarına bağlı olarak kullanıcıya ek bilgi iletişim kutuları gösterilebilir. launchMode parametresine bağlı olarak Play, bağlantı URI'sini harici bir tarayıcıda başlatır veya URI'yi başlatmak için akışı uygulamanıza döndürür. Çoğu durumda, Play'in URI'yi sizin için başlatacağı LAUNCH_IN_EXTERNAL_BROWSER_OR_APP modunu kullanabilirsiniz. URI'yi bir web görünümünde başlatma veya URI'yi belirli bir tarayıcıda açma gibi daha özelleştirilmiş bir davranış istiyorsanız CALLER_WILL_LAUNCH_LINK modunu kullanabilirsiniz. Kullanıcı gizliliğini korumak için URI'de kimliği tanımlayabilecek bilgi (PII) iletilmediğinden emin olun.

// 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 değerini CALLER_WILL_LAUNCH_LINK olarak ayarlarsanız kullanıcıyı yalnızca onLaunchExternalLinkResponse, BillingResponseCode.OK sağladığında uygulama dışına yönlendirmelisiniz.

İşlemleri Google Play'e bildirme

Google Play Developer API'yi arka uçtan çağırarak tüm harici işlemleri Google Play'e bildirmeniz gerekir. Bir işlemi bildirirken createBillingProgramReportingDetailsAsync API'sinden alınan bir externalTransactionToken sağlamanız gerekir. Bir kullanıcı birden fazla satın alma işlemi yaparsa her satın alma işlemini bildirmek için aynı externalTransactionToken değerini kullanabilirsiniz. İşlem bildirme hakkında bilgi edinmek için arka uç entegrasyonu kılavuzuna bakın.

Yanıt işleme

Bir hata oluştuğunda isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() ve launchExternalLink() yöntemleri, BillingResponseCode.OK dışında yanıtlar döndürebilir. Bu yanıt kodlarını aşağıdaki gibi ele alabilirsiniz:

• ERROR: Bu bir dahili hatadır. İşleme devam etmeyin veya harici web sitesini açmayın. Kullanıcıyı uygulamanın dışına yönlendirmeyi bir sonraki denemenizde kullanıcıya bilgi iletişim kutusunu göstermek için launchExternalLink() numaralı telefonu arayarak yeniden deneyin.
• FEATURE_NOT_SUPPORTED: Harici teklif 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 bilgi iletişim kutusunu kullanıcıya göstermek için launchExternalLink() işlevini tekrar çağırın.
• BILLING_UNAVAILABLE: İşlem, harici teklifler için uygun değildir ve bu nedenle bu program kapsamında devam etmemelidir. 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. İkinci durum söz konusuysa Play Developer 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 teklifleri 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 uçunuzu entegre etmeye hazırsınız.