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'lerin nasıl entegre edileceği 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 kullanmak için 5.2 veya sonraki bir sürümü kullanmanız gerekir. Daha eski bir sürümden taşıma yapmanız gerekiyorsa alternatif faturalandırmayı uygulamaya çalışmadan önce taşıma kılavuzundaki talimatları uygulayın.

Google Play'e bağlanma

Entegrasyon sürecindeki ilk adımlar, Google Play Faturalandırma entegrasyon kılavuzunda açıklanan adımlarla aynıdır. Ancak BillingClient'ınızı başlatırken birkaç değişiklik yapmanız gerekir:

  • Kullanıcıya faturalandırma seçenekleri sunmak istediğinizi belirtmek için yeni bir yöntem çağırmanız gerekir: enableUserChoiceBilling.
  • Kullanıcının alternatif faturalandırmayı seçtiği durumları yönetmek için UserChoiceBillingListener kaydetmeniz gerekir.

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

Kotlin

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

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

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

Java

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 başlatıldıktan sonra, entegrasyon kılavuzunda açıklandığı gibi Google Play'e bağlantı oluşturmanız gerekir.

Kullanılabilir ürünleri gösterme

Kullanıcılara sunulan ürünleri Google Play Faturalandırma Sistemi entegrasyonunda olduğu gibi gösterebilirsiniz. Kullanıcınız satın alınabilecek ürünleri gördükten ve satın almak için bir ürün seçtikten sonra, aşağıdaki bölümde açıklandığı şekilde kullanıcı tercihine göre faturalandırma akışını başlatın.

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

launchBillingFlow() işlevini çağırarak kullanıcı tercihine göre faturalandırma akışını başlatın. Bu, Google Play Faturalandırma Sistemi entegrasyonuyla satın alma akışı başlatmaya benzer şekilde çalışır: Kullanıcının edinmek istediği ürün ve teklife karşılık gelen bir ProductDetails örneği ve 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() işlevini çağırdığında Google Play faturalandırma sistemi aşağıdaki kontrolü yapar:

  • Sistem, kullanıcının Google Play ülkesinin, kullanıcı tercihine göre alternatif faturalandırmayı destekleyen bir ülke olup olmadığını (yani desteklenen bir ülke olup olmadığını) kontrol eder. Kullanıcının Google Play ülkesi destekleniyorsa Google Play, BillingClient yapılandırmasına göre alternatif faturalandırmanın etkinleştirilip etkinleştirilmediğini kontrol eder.
    • Kullanıcıya tercih seçeneği sunulan alternatif faturalandırma etkinleştirilmişse satın alma akışında kullanıcı tercihi kullanıcı deneyimi gösterilir.
    • Kullanıcı tercihine göre faturalandırma etkinleştirilmediyse satın alma akışında, kullanıcı tercihine göre faturalandırma 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 akışında, kullanıcı tercihi olmadan standart Google Play faturalandırma sistemi kullanıcı deneyimi gösterilir.

Kullanıcının Play'deki ülkesi desteklenen bir ülke olmalıdır.

Kullanıcının Play ülkesi desteklenen bir ülke değil

BillingClient kurulumu sırasında enableUserChoiceBilling çağrılıyor

Kullanıcı, kullanıcı tercihi kullanıcı deneyimini görür.

Kullanıcı, standart Google Play faturalandırma sistemi kullanıcı deneyimini görür.

BillingClient kurulumu sırasında enableUserChoiceBilling çağrılmıyor

Kullanıcı, standart Google Play faturalandırma sistemi kullanıcı deneyimini görür.

Kullanıcı, standart Google Play faturalandırma sistemi kullanıcı deneyimini görür.

Kullanıcı seçimini işleme

Satın alma sürecinin geri kalanını nasıl ele alacağınız, kullanıcının Google Play'in faturalandırma sistemini mi yoksa alternatif bir 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, uygulamaya alternatif faturalandırma sisteminde satın alma akışını başlatması gerektiğini bildirmek için UserChoiceBillingListener işlevini çağırır. Ö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 girme tercihinin imzasını temsil eder. Bu jetonu, arka uç entegrasyonu kılavuzunda açıklandığı gibi bu seçimden kaynaklanan tüm işlemleri bildirmek için kullanın.

UserChoiceBillingListener aşağıdaki işlemleri yapmalıdır:

  • Kullanıcı tarafından satın alınan ürünleri, alternatif faturalandırma sistemindeki satın alma akışında gösterilebilmeleri için alın.
  • Harici işlem jetonu olarak alınan dizeyi toplayın ve kalıcı hale getirmek için arka uçunuza gönderin. Bu bilgi, kullanıcı bu satın alma işlemini tamamlarsa daha sonra 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 işlemi 24 saat içinde arka uçtan Google Play Developer API'yi çağırarak Google Play'e bildirmeniz ve externalTransactionToken ile ek işlem ayrıntılarını sağlamanız gerekir. Daha ayrıntılı bilgi için arka uç entegrasyonu kılavuzuna bakın.

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

Kotlin

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

Java

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 satın alma işlemine Google Play üzerinden devam eder.

  • Google Play'in faturalandırma sistemi üzerinden yapılan yeni uygulama içi satın alma işlemlerinin 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 bilgiler için abonelik yönetimi kılavuzundaki Yeni abonelikler bölümüne bakın.

Abonelikteki değişiklikleri ele alma

Kullanıcı tercihine göre alternatif faturalandırma kullanan geliştiriciler için satın alma işlemlerinin, kullanıcının tercihine bağlı olarak Google Play'in faturalandırma sistemi üzerinden işlenmesi veya externalTransactionId ile bildirilmesi gerekir. Kullanıcı tercihi akışı üzerinden işlenen mevcut aboneliklerdeki değişiklikler, abonelik 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.

Sürüm yükseltme ve düşürme akışları

Abonelik planı değişiklikleri (ör. yükseltme ve düşürme) aboneliğin ilk olarak Google Play'in faturalandırma sistemiyle mi yoksa alternatif bir faturalandırma sistemiyle mi satın alındığına bağlı olarak farklı şekilde ele alınmalıdır.

Mevcut bir aboneliğe bağlı olan, aynı ödeme yöntemini kullanan ve yinelenen ödemeleri aynı zamanda yapılan eklentiler, yükseltme olarak değerlendirilir. Diğer eklentilerde ise kullanıcılar, hangi faturalandırma sistemini kullanmak istediklerini seçebilmelidir. Kullanıcı tercihine göre faturalandırma sürecini başlatma başlıklı makalede açıklandığı gibi launchBillingFlow() kullanarak yeni bir satın alma deneyimi başlatın.

Alternatif faturalandırma sistemiyle satın alınan abonelikler

Başlangıçta kullanıcının tercihi doğrultusunda geliştiricinin alternatif faturalandırma sistemi üzerinden satın alınan aboneliklerde, yükseltme veya alt sürüme geçme isteğinde bulunan kullanıcılar, kullanıcı tercihi deneyimini tekrar yaşamadan geliştiricinin alternatif faturalandırma sistemi üzerinden devam etmelidir.

Bunu yapmak için kullanıcı yükseltme veya alt sürüme geçme isteğinde bulunduğunda launchBillingFlow() işlevini çağırın. Parametrelerde SubscriptionUpdateParams nesnesi belirtmek yerine, orijinal satın alma işlemi için harici işlem kimliğini sağlayan setOriginalExternalTransactionId kullanın. Orijinal satın alma işleminde kullanıcının yaptığı seçim yükseltme ve düşürme işlemlerinde korunduğu için bu işlemde kullanıcı tercihi ekranı gösterilmez. Bu durumda launchBillingFlow() çağrısı, geri çağırmadan alabileceğiniz işlem için yeni bir harici işlem jetonu oluşturur.

Kotlin

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

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

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

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

Java

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

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using 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 yükseltme veya düşürme işlemi tamamlandığında, önceki çağrı aracılığıyla edinilen harici işlem jetonunu kullanarak yeni bir işlem bildirmeniz gerekir.

Google Play'in faturalandırma sistemiyle satın alınan abonelikler

Benzer şekilde, mevcut aboneliklerini kullanıcı tercihi sonrasında Google Play'in faturalandırma sistemi üzerinden satın alan kullanıcılara Google Play'in faturalandırma sisteminde yükseltme veya düşürme 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:

    Kotlin

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

    Java

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

  2. Yeni satın alma işlemini işlemek için Google Play'in faturalandırma sistemine doğru bilgileri gönderin. Mevcut aboneliğin satın alma jetonu da bu bilgilere dahildir:

    Kotlin

    val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            listOf(
                BillingFlowParams.ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
                )
        )
        .setSubscriptionUpdateParams(
            BillingFlowParams.SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                .build()
        )
        .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

    Java

    BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
            )
        )
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.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 gerçekleşir ve uygulamanız, satın alma işleminin sonucuyla birlikte 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 uç sisteminiz SUBSCRIPTION_PURCHASED anlık geliştirici bildirimi alır. Yeni satın alma işleminin durumunu çekerken linkedPurchaseToken özelliği, eski abonelik satın alma işlemine bağlanır. Böylece, eski abonelik satın alma işlemini önerildiği şekilde kullanımdan kaldırabilirsiniz.

Abonelik iptalleri ve geri yüklemeleri

Kullanıcılar, aboneliklerini diledikleri zaman iptal edebilmelidir. Bir kullanıcı aboneliği iptal ettiğinde, hakların feshi ücretli dönem sona erene kadar ertelenebilir. Örneğin, bir kullanıcı aylık aboneliği ayın ortasında iptal ederse erişimi kaldırılana kadar hizmete yaklaşık 2 hafta boyunca erişmeye devam edebilir. Bu süre zarfında abonelik teknik olarak etkin kalır ve kullanıcı hizmeti kullanmaya devam edebilir.

Kullanıcıların bu etkin dönemde iptali geri almaya karar vermesi yaygın bir durumdur. Bu kılavuzda bu işleme geri yükleme adı verilir. Aşağıdaki bölümlerde, alternatif faturalandırma API'nizle entegrasyonunuzda geri yükleme senaryolarının nasıl ele alınacağı açıklanmaktadır.

Alternatif faturalandırma sistemiyle satın alınan abonelikler

İptal edilen bir abonelik için harici işlem kimliğiniz varsa aboneliği geri yüklemek üzere launchBillingFlow() numaralı telefonu aramanız gerekmez. Bu nedenle, bu tür bir etkinleştirme için kullanılmamalıdır. Kullanıcı, iptal edilen aboneliğin etkin olduğu dönemde aboneliğini geri yüklerse o sırada herhangi bir işlem gerçekleşmez. Yalnızca mevcut dönem sona erdiğinde ve bir sonraki yenileme gerçekleştiğinde yenilemeleri bildirmeye devam edebilirsiniz. Kullanıcının aboneliğini geri yükleme kapsamında kredi veya özel yenileme fiyatı aldığı durumlar (ör. kullanıcıyı aboneliğini devam ettirmeye teşvik etmek için yapılan bir promosyon) bu kapsamda yer alır.

Google Play'in faturalandırma sistemiyle satın alınan abonelikler

Genellikle kullanıcılar, Google Play'in faturalandırma sistemindeki abonelikleri geri yükleyebilir. Google Play'in faturalandırma sistemi üzerinden satın alınan ve iptal edilen aboneliklerde kullanıcı, abonelik Google Play'in Yeniden abone ol özelliği aracılığıyla etkin olduğu sürece iptal işlemini geri alabilir. Bu durumda, arka uçta SUBSCRIPTION_RESTARTEDanlık geliştirici bildirimiSUBSCRIPTION_RESTARTED alırsınız ve yeni bir satın alma jetonu verilmez. Aboneliğe devam etmek için orijinal jeton kullanılır. Google Play'in faturalandırma sisteminde geri yükleme işlemlerini nasıl yöneteceğinizi öğrenmek için abonelik yönetimi kılavuzundaki Geri yükleme işlemleri bölümüne bakın.

Ayrıca, launchBillingFlow() işlevini çağırarak Google Play'in faturalandırma sisteminde uygulamadan geri yükleme işlemini tetikleyebilirsiniz. Bunun nasıl yapılacağıyla ilgili açıklamayı Abonelik süresi dolmadan önce - uygulama içi bölümünde bulabilirsiniz. İlk satın alma işlemi için kullanıcı tercihi akışını tamamlayan (iptal edilmiş ancak hâlâ etkin olan) kullanıcılar söz konusu olduğunda sistem, kullanıcının seçimini otomatik olarak algılar ve bu satın alma işlemlerini geri yüklemek için kullanıcı arayüzünü gösterir. Kullanıcılardan, Google Play üzerinden aboneliği yeniden satın aldıklarını onaylamaları istenir ancak kullanıcı tercihi akışını tekrar uygulamaları gerekmez. Bu durumda kullanıcı için yeni bir satın alma jetonu verilir. Arka uç sisteminiz SUBSCRIPTION_PURCHASED anlık geliştirici bildirimi alır ve linkedPurchaseToken yeni satın alma işleminin değeri durumu, iptal edilen aboneliğin eski satın alma jetonuyla birlikte yükseltme veya düşürme işleminde olduğu gibi ayarlanır.

Yeniden abonelikler

Abonelik, iptal veya ödeme reddi nedeniyle tamamen sona ererse (süresi dolmuş hesap askıya alma) kullanıcı, haklarını yeniden başlatmak için yeniden abone olmalıdır.

Yeniden abonelik, standart bir kayda benzer şekilde işlenerek uygulama üzerinden de etkinleştirilebilir. Kullanıcılar, hangi faturalandırma sistemini kullanmak istediklerini seçebilmelidir. Bu durumda, Kullanıcının tercihine göre faturalandırma akışını başlatma başlıklı makalede açıklandığı gibi launchBillingFlow() çağrılabilir.

Alternatif faturalandırmayı test etme

Alternatif faturalandırma 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.