Kullanıcının tercihine göre alternatif faturalandırma için uygulama içi entegrasyon kılavuzu

Bu kılavuzda, uygulamanızda kullanıcı tercihine göre alternatif faturalandırma sunmak için API'leri nasıl entegre edeceğiniz açıklanmaktadır.

Play Faturalandırma Kitaplığı kurulumu

Android uygulamanıza Play Faturalandırma Kitaplığı bağımlılığını ekleyin. Alternatif faturalandırma API'lerini kullanabilmek için 5.2 veya sonraki bir sürümü kullanmanız gerekir. Önceki bir sürümden geçiş yapmanız gerekiyorsa alternatif faturalandırmayı uygulamaya çalışmadan önce taşıma kılavuzundaki talimatları uygulayın.

Google Play'e bağlan

Entegrasyon sürecindeki ilk adımlar Google Play Faturalandırma entegrasyonu kılavuzunda açıklananlarla aynıdır, ancak BillingClient hesabınızı başlatırken birkaç değişiklik yapılmıştır:

• Kullanıcıya bir faturalandırma seçeneği sunmak istediğinizi belirtmek için yeni bir yöntemi çağırmanız gerekir: enableUserChoiceBilling.
• Kullanıcının alternatif faturalandırmayı seçtiği destek kayıtlarını ele almak için bir UserChoiceBillingListener kaydettirmeniz gerekir.

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

val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // Handle new Google Play purchase.
   }

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

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

Kullanılabilir ürünleri göster

Tıpkı Google Play faturalandırma sistemi entegrasyonunda olduğu gibi kullanılabilir ürünleri kullanıcıya gösterebilirsiniz. Kullanıcı satın alınabilecek ürünleri gördüğünde ve satın almak üzere birini seçtiğinde, aşağıdaki bölümde açıklandığı şekilde kullanıcının tercihine göre faturalandırma akışını başlatın.

Kullanıcı tercihine göre faturalandırma akışını başlatma

launchBillingFlow() numaralı telefonu arayarak kullanıcı tercihine göre faturalandırma akışını başlatın. Bu işlem, Google Play faturalandırma sistemi entegrasyonuyla satın alma akışı başlatma ile aynı şekilde işler: Ürüne ve kullanıcının edinmek istediği teklife karşılık gelen bir ProductDetails örneği ile bir offerToken sağlarsınız. Kullanıcı Google Play'in faturalandırma sistemini seçerse bu bilgiler satın alma akışına devam etmek için kullanılır.

Geliştiriciler launchBillingFlow() çağırdığında Google Play faturalandırma sistemi aşağıdaki kontrolü gerçekleştirir:

• Sistem, kullanıcının Google Play ülkesinin kullanıcının tercihine göre alternatif faturalandırmayı destekleyen bir ülke (ör. desteklenen bir ülke) olup olmadığını kontrol eder. Kullanıcının Google Play ülkesi destekleniyorsa Google Play, BillingClient yapılandırmasına bağlı olarak alternatif faturalandırmanın etkinleştirilip etkinleştirilmediğini kontrol eder.
  • Kullanıcı tercihine göre alternatif faturalandırma etkinleştirildiyse satın alma akışında kullanıcının tercih ettiği kullanıcı deneyimi gösterilir.
  • Kullanıcı tercihine göre alternatif faturalandırma özelliği etkinleştirilmemişse satın alma sürecinde kullanıcı seçimi olmadan standart Google Play faturalandırma sistemi kullanıcı deneyimi gösterilir.
• Kullanıcının Google Play ülkesi desteklenen bir ülke değilse satın alma sürecinde kullanıcının seçimi olmadan standart Google Play faturalandırma sistemi kullanıcı deneyimi gösterilir.

Kullanıcı seçimini yönetin

Satın alma akışının geri kalanını nasıl yöneteceğiniz, kullanıcının Google Play'in faturalandırma sistemini mi yoksa alternatif faturalandırma sistemini mi seçtiğine bağlı olarak değişir.

Kullanıcı alternatif bir faturalandırma sistemi seçtiğinde

Kullanıcı alternatif faturalandırma sistemini seçerse Google Play, UserChoiceBillingListener numaralı telefonu çağırarak uygulamaya alternatif faturalandırma sisteminde satın alma akışını başlatması gerektiğini bildirir. Özellikle userSelectedAlternativeBilling() yöntemi çağrılır.

UserChoiceDetails nesnesinde sağlanan harici işlem jetonu, kullanıcının alternatif faturalandırma akışına girmeyi tercih ettiği bir imzayı temsil eder. Arka uç entegrasyon kılavuzunda açıklandığı gibi, bu seçimden kaynaklanan işlemleri bildirmek için bu jetonu kullanın.

UserChoiceBillingListener aşağıdaki işlemleri gerçekleştirmesi gerekir:

• Kullanıcı tarafından satın alınan ürün veya ürünlerin, alternatif faturalandırma sistemindeki satın alma akışında gösterilebilmelerini sağlayın.
• Alınan dizeyi harici işlem jetonu olarak toplayın ve kalıcı olması için arka ucunuza gönderin. Bu, daha sonra kullanıcı belirli bir satın alma işlemini tamamlarsa harici işlemi Google Play'e bildirmek için kullanılır.
• Geliştiricinin alternatif satın alma akışını başlatın.

Kullanıcı satın alma işlemini alternatif faturalandırma sistemini kullanarak tamamlarsa 24 saat içinde arka uçunuzdan Google Play Developer API'yi çağırarak işlemi Google Play'e bildirmeniz gerekir ve externalTransactionToken bilgilerini ve ek işlem ayrıntılarını sağlayın. Daha fazla bilgi için arka uç entegrasyon kılavuzuna bakın.

Aşağıdaki örnekte UserChoiceBillingListener öğesinin nasıl uygulanacağı gösterilmektedir:

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

Kullanıcı, Google Play'in faturalandırma sistemini seçtiğinde

Kullanıcı Google Play'in faturalandırma sistemini seçerse Google Play üzerinden satın alma işlemine devam eder.

• Yeni uygulama içi satın alma işlemlerinin Google Play'in faturalandırma sistemi kullanılarak nasıl ele alınacağı hakkında daha fazla bilgi için kitaplık entegrasyon kılavuzundaki Satın alma işlemlerini işleme bölümüne bakın.
• Abonelik satın alma işlemleriyle ilgili ek rehberlik için abonelik yönetimi kılavuzundaki Yeni abonelikler bölümüne bakın.

Abonelikteki değişiklikleri ele alın

Kullanıcının tercihine göre alternatif faturalandırma kullanan geliştiriciler için satın alma işlemlerinin kullanıcının seçimine bağlı olarak Google Play'in faturalandırma sistemi üzerinden işlenmesi veya externalTransactionId ile bildirilmesi gerekir. Kullanıcı seçim akışı aracılığıyla işlenen mevcut aboneliklerde yapılan değişiklikler, geçerlilik süresi sona erene kadar aynı faturalandırma sistemi üzerinden yapılabilir.

Bu bölümde, bazı yaygın abonelik değişikliği senaryolarının nasıl ele alınacağı açıklanmaktadır.

Yeni sürüme ve eski sürüme geçiş akışları

Yükseltme ve düşürme akışları dahil olmak üzere abonelik planı değişiklikleri, aboneliğin ilk olarak Google Play'in faturalandırma sisteminden mi yoksa alternatif faturalandırma sistemi üzerinden mi satın alındığına bağlı olarak farklı şekilde ele alınmalıdır.

Mevcut bir aboneliği temel alan, aynı ödeme yöntemini paylaşan ve yinelenen ödemeleri uyumlu hâle getiren eklentiler yükseltme olarak ele alınır. Kullanıcılar, diğer eklentiler için kullanmak istedikleri faturalandırma sistemini seçebilmelidir. Kullanıcı tercihine göre faturalandırma akışını başlatma bölümünde açıklandığı gibi, launchBillingFlow() kullanarak yeni bir satın alma deneyimi başlatın.

Alternatif faturalandırma sistemi aracılığıyla satın alınan abonelikler

Kullanıcı tercihine göre başlangıçta geliştiricinin alternatif faturalandırma sistemi üzerinden satın alınan aboneliklerde sürüm yükseltme veya düşürme talebinde bulunan kullanıcılar, kullanıcının tercihine göre deneyimi tekrar yaşamadan geliştiricinin alternatif faturalandırma sistemini kullanmalıdır.

Bunu yapmak için, kullanıcı yeni sürüme veya eski sürüme geçirme isteğinde bulunduğunda launchBillingFlow() numaralı telefonu arayın. Parametrelerde bir SubscriptionUpdateParams nesnesi belirtmek yerine, orijinal satın alma işlemi için harici işlem kimliğini sağlayarak setOriginalExternalTransactionId kullanın. Bu durumda, kullanıcı seçimi ekranı gösterilmez. Çünkü orijinal satın alma işlemi için kullanıcı tercihi, yükseltme ve eski sürüme geçişlerde korunur. Bu durumda launchBillingFlow() çağrısı, işlem için geri çağırmadan alabileceğiniz yeni bir harici işlem jetonu oluşturur.

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync.
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails
                        .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    .setOriginalExternalTransactionId(externalTransactionId)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Alternatif faturalandırma sisteminde yeni veya eski sürüme geçme işlemi tamamlandığında, yeni abonelik satın alma işlemi için önceki çağrı üzerinden alınan harici işlem jetonunu kullanarak yeni bir işlem bildirmeniz gerekir.

Google Play'in faturalandırma sistemi üzerinden satın alınan abonelikler

Benzer şekilde, kullanıcı seçiminden sonra mevcut aboneliklerini Google Play'in faturalandırma sistemi üzerinden satın alan kullanıcılara Google Play'in faturalandırma sisteminde üst veya alt sürüme geçme akışı gösterilmelidir. Aşağıdaki talimatlarda, Google Play'in faturalandırma sistemi üzerinden yükseltme veya düşürme için satın alma akışını nasıl başlatacağınız açıklanmaktadır:

1. Yeni plan için seçilen teklifin offerToken değerini belirleyin:

val offerTokenNewPlan = productDetailsNewPlan
             .getSubscriptionOfferDetails(selectedOfferIndex)
             .getOfferToken()

String offerTokenNewPlan = productDetailsNewPlan
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();

1. Mevcut aboneliğin satın alma jetonu da dahil olmak üzere yeni satın alma işleminin gerçekleştirilmesi için Google Play'in faturalandırma sistemine doğru bilgileri gönderin:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Bu satın alma işlemi, Google Play'in faturalandırma sisteminde devam eder ve uygulamanız, satın alma işleminin sonucunda PurchasesUpdatedListener.onPurchaseUpdated çağrısını alır. Satın alma işlemi başarılı olursa onPurchaseUpdated() yöntemi de yeni satın alma bilgilerini alır ve arka ucunuza SUBSCRIPTION_PURCHASED Gerçek Zamanlı Geliştirici Bildirimi gönderilir. Yeni satın alma işleminin durumu alınırken linkedPurchaseToken özelliği, eski abonelik satın alma işlemine bağlantı verir. Böylece aboneliği önerilen şekilde kullanımdan kaldırabilirsiniz.

Abonelik iptalleri ve geri yükleme işlemleri

Kullanıcılar aboneliklerini diledikleri zaman iptal edebilir. Bir kullanıcı aboneliği iptal ettiğinde yararlanma hakkının feshi, ödemesi ödenen süre sona erene kadar ertelenebilir. Örneğin, bir kullanıcı aylık aboneliğini ayın ortasında iptal ederse erişimi kaldırılana kadar yaklaşık 2 hafta boyunca hizmete erişmeye devam edebilir. Bu süre zarfında abonelik teknik olarak hâlâ etkin olduğundan kullanıcı hizmeti kullanabilir.

Bu etkin süre içinde kullanıcıların iptal işlemini geri almaya karar vermeleri yaygın olarak görülen bir durumdur. Bu kılavuzda bu işleme restorasyon adı verilmektedir. Aşağıdaki bölümlerde, alternatif faturalandırma API'si entegrasyonunuzdaki geri yükleme senaryolarını nasıl ele alacağınız açıklanmaktadır.

Alternatif faturalandırma sistemi aracılığıyla satın alınan abonelikler

İptal edilen bir aboneliğe ilişkin harici bir işlem kimliğiniz varsa aboneliği geri yüklemek için launchBillingFlow() yöntemini çağırmanız gerekmez. Dolayısıyla bu kimlik, bu tür etkinleştirme işlemleri için kullanılmamalıdır. Bir kullanıcı, iptal edilmiş bir aboneliğin etkin dönemindeyken aboneliğini geri yüklerse, o anda hiçbir işlem gerçekleşmez. Yalnızca geçerli döngünün süresi dolduğunda ve bir sonraki yenileme gerçekleştiğinde yenilemeleri bildirmeye devam edebilirsiniz. Buna, yenileme kapsamında kullanıcının kredi veya özel yenileme fiyatı aldığı durumlar da dahildir (örneğin, kullanıcıyı aboneliğine devam etmeye teşvik eden bir promosyon).

Google Play'in faturalandırma sistemi üzerinden satın alınan abonelikler

Kullanıcılar genellikle abonelikleri Google Play'in faturalandırma sisteminde geri yükleyebilirler. Başlangıçta Google Play'in faturalandırma sisteminde satın alınan iptal edilmiş aboneliklerde kullanıcı, abonelik etkin durumdayken Google Play'in Yeniden abone olma özelliğini kullanarak iptal işlemini geri alabilir. Bu durumda, arka uçunuzda bir SUBSCRIPTION_RESTARTED Gerçek Zamanlı Geliştirici Bildirimi alırsınız ve yeni bir satın alma jetonu yayınlanmaz. Orijinal jeton, aboneliğe devam etmek için kullanılır. Google Play'in faturalandırma sisteminde geri yüklemeyi nasıl yöneteceğinizi öğrenmek için abonelik yönetimi kılavuzundaki Restorasyonlar bölümüne bakın.

Ayrıca launchBillingFlow() numaralı telefonu arayarak uygulama üzerinden Google Play'in faturalandırma sisteminde geri yükleme işlemini tetikleyebilirsiniz. Bunun nasıl yapılacağını öğrenmek için Abonelik süresi bitmeden önce - uygulama içi bölümüne bakın. Orijinal satın alma işlemi için (iptal edilmiş ancak hâlâ etkin olan) kullanıcı seçim akışından geçen kullanıcılar olması durumunda, sistem kullanıcının seçimini otomatik olarak algılar ve satın alınan bu satın alma işlemlerini geri yüklemek için kullanıcı arayüzünü görüntüler. Kullanıcıdan, aboneliği Google Play üzerinden yeniden satın aldığını onaylamaları istenir ancak kullanıcı seçim akışından tekrar geçmeleri gerekmez. Bu durumda, kullanıcı için yeni bir satın alma jetonu verilir. Arka ucunuz SUBSCRIPTION_PURCHASED Gerçek Zamanlı Geliştirici Bildirimi alır ve yeni satın alma durumu için linkedPurchaseToken değeri, yükseltme veya düşürme durumunda olduğu gibi iptal edilen aboneliğin eski satın alma jetonuyla ayarlanır.

Yeniden abonelikler

Bir abonelik tamamen sona ererse (kurtarma sağlanmadan iptal veya ödeme reddi (hesap askıya alma süresinin sona ermesi) nedeniyle olsun, kullanıcının yararlanma hakkını yeniden başlatmak istemesi durumunda yeniden abone olması gerekir.

Standart kaydolma işlemine benzer şekilde işlenerek yeniden abonelik uygulama üzerinden de etkinleştirilebilir. Kullanıcılar kullanmak istedikleri faturalandırma sistemini seçebilmelidir. Bu durumda launchBillingFlow(), Kullanıcı tercihine göre faturalandırma akışını başlatma bölümünde açıklandığı gibi çağrılabilir.

Alternatif faturalandırmayı test etme

Lisans test kullanıcıları, alternatif faturalandırma 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.