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

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

Play Faturalandırma Kitaplığı kurulumu

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

Google Play'e bağlan

Entegrasyon sürecindeki ilk adımlar, fatura entegrasyonu kılavuzunda açıklananlarla aynıdır. Yalnızca BillingClient öğenizi başlatırken birkaç değişiklik yapmanız gerekir:

• Harici teklifleri kullanmak istediğinizi belirtmek için yeni bir yöntemi çağırmanız gerekir: enableExternalOffer.

Aşağıdaki örnek, bu değişikliklerle bir BillingClient öğesinin başlatılmasını göstermektedir:

Kotlin

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

BillingClient uygulamasını başlattıktan sonra, entegrasyon kılavuzunda açıklandığı gibi Google Play ile bağlantı kurmanız gerekir.

Müsaitlik durumunu kontrol etme

Uygulamanız, isExternalOfferAvailableAsync numaralı telefonu arayarak harici tekliflerin kullanılabilir olduğunu onaylamalıdır.

Harici teklifler varsa bu API, 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üne bakın.

Kotlin

billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        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.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        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 bir işlem jetonu hazırlayın

Harici bir işlemi Google Play'e bildirmek için Play Faturalandırma Kitaplığı'ndan oluşturulmuş bir harici işlem jetonunuz olmalıdır. Kullanıcı harici teklifler API'si üzerinden harici bir web sitesini her ziyaret ettiğinde yeni bir harici işlem jetonu oluşturulmalıdır. Bunu, createExternalOfferReportingDetailsAsync API'yi çağırarak yapabilirsiniz. Bu jeton, kullanıcı uygulama dışına yönlendirilmeden hemen önce oluşturulmalıdır. Hiçbir zaman önbelleğe alınmamalı ve kullanıcı uygulama dışına her yönlendirildiğinde yeni bir jeton oluşturulmalıdır.

Kotlin

billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

Java

billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

Kullanıcılar için bilgi iletişim kutusu

Harici tekliflerle entegrasyon için uygun uygulamanızın, kullanıcıların uygulama dışından harici bir web sitesine yönlendirilmek üzere olduklarını anlamalarına yardımcı olan bir bilgi ekranı göstermesi gerekir. Her seferinde harici bir teklife bağlantı oluşturmadan önce, showExternalOfferInformationDialog API çağrısı yapılarak kullanıcılara bilgi ekranı gösterilmelidir.

Kotlin

// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

Java

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

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

Bu yöntem BillingResponseCode.OK değerini döndürürse uygulamanız, kullanıcıyı harici web sitesine yönlendirme işlemine devam edebilir. Yöntem BillingResponseCode.USER_CANCELED sonucunu döndürürse uygulamanız web sitesini açmaya devam etmemelidir.

İşlemleri Google Play'e bildirme

Not: İşlem raporlama şartları için Harici teklifler programına kaydolma konusuna bakın.

Tüm harici işlemler, arka ucunuzdan Google Play Developer API'yi çağırarak Google Play'e bildirilmelidir. Harici işlemler, createExternalOfferReportingDetailsAsync API kullanılarak elde edilen bir externalTransactionToken sağlanırken bildirilmelidir. Bir kullanıcı birden fazla satın alma işlemi gerçekleştirirse her bir satın alma işlemini raporlamak için aynı externalTransactionToken değerini kullanabilirsiniz. Bir işlemi nasıl bildireceğinizi öğrenmek için arka uç entegrasyon kılavuzuna bakın.

Yanıtları işleme

Bir hata oluştuğunda isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync ve showExternalOfferInformationDialog yöntemleri BillingResponseCode.OK dışında yanıtlar döndürebilir. Bu yanıt kodlarını aşağıdaki gibi ele almayı düşünebilirsiniz:

• ERROR: Bu dahili bir hatadır. İşleme devam etmeyin veya harici web sitesini açmayın. Kullanıcıyı uygulamanın dışına bir sonraki yönlendirmenizde, bilgi iletişim kutusunun gösterilmesi için showExternalOfferInformationDialog() yöntemini çağırarak tekrar deneyin.
• FEATURE_NOT_SUPPORTED: Harici teklif API'leri, mevcut cihazda 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 tekrar denediğinizde kullanıcıya bilgi iletişim kutusunun gösterilmesi için showExternalOfferInformationDialog() numaralı telefonu tekrar arayın.
• BILLING_UNAVAILABLE: İşlem, harici teklifler için uygun olmadığından bu program kapsamında yapılmamalıdır. Bunun nedeni, kullanıcının bu program için uygun bir ülkede olmaması veya hesabınızın programa başarılı bir şekilde kaydedilmemiş olmasıdır. İkinci durum geçerliyse Play Console'da kayıt durumunuzu kontrol edin.
• DEVELOPER_ERROR: İstekle ilgili bir hata var. Devam etmeden önce hatayı tanımlayıp 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 söz konusuysa tekrar denemeden önce Google Play ile yeniden bağlantı kurun.

Harici teklifleri test edin

Lisans test kullanıcıları, harici teklifler entegrasyonunuzu test etmek için kullanılmalıdır. Lisans test kullanıcısı hesaplarıyla 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 edinmek için Uygulama içi faturalandırmayı uygulama lisanslama ile test etme bölümüne bakın.

Sonraki adımlar

Uygulama içi entegrasyonu tamamladıktan sonra, arka ucunuzu entegre etmeye hazır olursunuz.