Sürüm 4 veya 5'ten Google Play Faturalandırma Kitaplığı 6'ya geçiş

Bu belgede, Google Play Faturalandırma Kitaplığı 4 veya 5'ten Google Play Faturalandırma Kitaplığı 6'ya nasıl geçiş yapılacağı ve yeni abonelik özelliklerinin nasıl kullanılacağı açıklanmaktadır.

6.0.0 sürümündeki değişikliklerin tam listesi için sürüm notlarına bakın.

Genel Bakış

Google Play Faturalandırma Kitaplığı 6, 5. sürümde sunulan yeni abonelik özelliklerini temel alır ve birkaç iyileştirme daha ekler. Bu özellikler, abonelikleri daha fazla yöntemle satmanıza olanak tanır. Böylece, sürekli artan sayıda SKU oluşturma ve yönetme ihtiyacını ortadan kaldırarak işletme maliyetlerini azaltır.

Play Faturalandırma Kitaplığı 5 ile sunulan yeni özellikler hakkında daha fazla bilgi için Play Console'da aboneliklerle ilgili son değişiklikler bölümüne bakın.

Geriye dönük uyumlu Google Play Faturalandırma Kitaplığı yükseltmesi

Mevcut tüm abonelik ürünleri, Mayıs 2022'de Play Faturalandırma Kitaplığı 5 ve yeni abonelik platformunun kullanıma sunulmasıyla birlikte otomatik olarak bu yeni modele dönüştürüldü. Bu sayede, Play Faturalandırma Kitaplığı'nın yeni sürümleriyle uyumlu bir kataloğa sahip olmak için abonelik ürünü yapılandırmasında herhangi bir değişiklik yapmanız gerekmez. Abonelik SKU'larının geriye dönük uyumlu aboneliklere nasıl dönüştürüldüğü hakkında daha fazla bilgi için Play Console Yardım makalesindeki Eski aboneliklerle çalışma bölümüne bakın.

Uygulamanızın önceki sürümleri çalışmaya devam eder.

Geriye dönük uyumlu bir abonelik kataloğunuz varsa uygulamanızın mevcut tüm sürümleri bu ürünler için amaçlandığı gibi çalışmaya devam eder. Tek seferlik ürün satın alma işlemleri de önceki sürümlerde sorunsuz bir şekilde çalışmaya devam etmelidir.

Uygulamanızın, desteği sonlandırılmış yöntemleri (ör. querySkuDetailsAsync()) kullanan sürümleri, geriye dönük uyumlu olmayan temel planları veya teklifleri satamaz. Geriye dönük uyumlu fırsatlar hakkında bilgiyi ilgili Play Console Yardım Merkezi makalesinde bulabilirsiniz.

Google Play Faturalandırma Kitaplığı 5 veya 6'ya yükseltme

Google Play Faturalandırma Kitaplığı 5 ve 6, faturalandırma akışı parametresi olarak SkuDetails alan, desteği sonlandırılmış querySkuDetailsAsync ve BillingFlowParams.Builder.setSkuDetails yöntemlerini içerir. Bu sayede, geçişin farklı aşamalarını planlayarak Google Play Faturalandırma Kitaplığı 6'ya kademeli olarak geçebilirsiniz.

Geçişin ilk adımı olarak kitaplık sürümünü güncelleyebilir, kataloğunuzu ve arka ucunuzu olduğu gibi bırakabilir ve uygulamanızı, desteği sonlandırılan yöntemleri kullanmaya devam ederken test edebilirsiniz. queryPurchases, launchPriceChangeFlow veya setVrPurchaseFlow kullanmıyorsanız da amaçlandığı gibi çalışmaya devam edecektir. Ardından, Mayıs 2022'de kullanıma sunulan yeni abonelik özelliklerini tam olarak benimsemek için yineleme yapabilirsiniz.

Bu özellikleri daha önce Google Play Faturalandırma Kitaplığı 5'e geçiş yaparak kullandıysanız doğrudan Google Play Faturalandırma Kitaplığı'nı güncelleme ve Kullanıcının abonelik satın alma işlemlerini değiştirme etiketli bölümlere geçebilirsiniz. Daha eski bir sürümden başlıyorsanız veya yeni özellikleri henüz tam olarak kullanmaya başlamadıysanız bunları nasıl kullanacağınızı öğrenmek için aşağıdaki tam taşıma adımlarını okuyabilirsiniz.

Tam taşıma adımları

Arka uç ürün kataloğunuzda yeni abonelikler oluşturma

Google Play Console'u veya Google Play Developer API'yi kullanarak artık birden fazla temel plan içeren tek bir abonelik yapılandırabilir, bu planların her birinde çeşitli fırsatlar sunabilirsiniz. Abonelik fırsatları için esnek fiyatlandırma modelleri ve uygunluk seçenekleri geçerlidir. Otomatik yenilenen ve ön ödemeli plan çeşitlerini kullanarak abonelik yaşam döngüsü boyunca fırsatlar oluşturabilirsiniz.

Uygulamanızı taşımadan önce Play Faturalandırma Kitaplığı 6 entegrasyonunuz için yeni abonelik platformundaki varlık yapısını izleyerek yeni ürünler oluşturmanızı öneririz. Eski kataloğunuzda aynı hak avantajlarını temsil eden yinelenen ürünleri tek bir abonelik altında birleştirebilir ve sunmak istediğiniz tüm seçenekleri temsil etmek için temel plan ve fırsat yapılandırmalarını kullanabilirsiniz. Bu öneri hakkında daha fazla bilgi için Play Console Yardım makalesinin Eski aboneliklerle çalışma bölümüne bakın.

Dönüştürülen abonelik ürünlerini Mayıs 2022 sürümünden sonra değiştirmeden bırakın. Böylece, desteği sonlandırılan yöntemleri (ör. querySkuDetailsAsync()) kullanan uygulama sürümleri, bu derlemeleri etkilemeden bunları satmaya devam edebilir.

Dönüşüm süreci, mevcut entegrasyonunuzda sorunlara yol açabilecek yanlışlıkla yapılan değişiklikleri önlemek için Mayıs 2022'den önce kataloğunuzda bulunan abonelik ürünlerini salt okunur hale getirdi. Bu aboneliklerde değişiklik yapmak mümkündür ancak ön uç ve arka uç entegrasyonlarınızı etkileyebilecek sonuçlar doğurabilir:

  • Ön uçta, abonelik ürünü ayrıntılarını almak için querySkuDetailsAsync() kullanan uygulama sürümleri yalnızca geriye dönük uyumlu temel planları ve teklifleri satabilir. Ayrıca, yalnızca bir adet geriye dönük uyumlu temel plan ve teklif kombinasyonu olabilir. Bu nedenle, dönüştürülen aboneliklere yeni planlar veya teklifler eklerseniz yeni ek temel planlar ya da teklifler uygulamanızın bu önceki sürümlerinde satılamaz.

  • Arka uçta, dönüştürülen aboneliklerinizi Google Play Console kullanıcı arayüzünde düzenlerseniz bu amaçla çağırıyor olsanız bile inappproducts uç noktasıyla yönetemezsiniz. Eski satın alma durumu uç noktası (purchases.subscriptions.get) yalnızca geriye dönük uyumlu temel planları ve fırsat satın alma işlemlerini yönetmek için gereken verileri döndürdüğünden, bu aboneliklerin satın alma işlemlerini yönetmek için yeni abonelik satın alma durumu uç noktasına (purchases.subscriptionsv2.get) geçmeniz gerekir. Daha fazla bilgi için Abonelik satın alma durumunu yönetme bölümünü okuyun.

Yeni API ile arka uç abonelik kataloğunuzu yönetme

Abonelik ürünü kataloğunuzu Google Play Developer API ile otomatik olarak yönetiyorsanız abonelikleri, temel planları ve fırsatları oluşturup yönetmek için yeni abonelik ürünü tanımı uç noktalarını kullanmanız gerekir. Bu sürümdeki ürün kataloğu API değişiklikleri hakkında daha fazla bilgi edinmek için Mayıs 2022 abonelik özellikleri kılavuzunu okuyun.

Google Play Faturalandırma abonelikleri için otomatik ürün kataloğu yönetim modülünü taşımak istiyorsanız abonelik kataloğunuzu yönetmek ve yayınlamak için inappproducts API'yi yeni Subscription Publishing API ile değiştirin. Üç yeni uç nokta vardır:

Bu yeni uç noktalar, kataloğunuzdaki tüm yeni özelliklerden (temel plan ve fırsat etiketleri, bölgesel hedefleme, ön ödemeli planlar vb.) yararlanmak için gereken tüm işlevlere sahiptir.

Tek seferlik satın alma ürünleri için uygulama içi ürün kataloğunuzu yönetmek üzere inappproducts API'yi kullanmaya devam etmeniz gerekir.

Uygulamanızın, desteği sonlandırılmış yöntemleri (ör. querySkuDetailsAsync()) kullanan sürümleri, geriye dönük uyumlu olmayan temel planları veya teklifleri satamaz. Geriye dönük uyumlu teklifler hakkında bilgi edinmek için Play Console Yardım makalesini okuyabilirsiniz.

Google Play Faturalandırma Kitaplığı'nı güncelleme

Yeni abonelik ürünleri kataloğunuzu oluşturduktan sonra uygulamanızı Google Faturalandırma Kitaplığı 5'e taşıyabilirsiniz. Mevcut Play Faturalandırma Kitaplığı bağımlılığını, uygulamanızın build.gradle dosyasındaki güncellenmiş sürümle değiştirin.

dependencies {
    def billingVersion = "6.0.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

Yöntem çağrılarında herhangi bir değişiklik yapmamış olsanız bile projeniz hemen derlenir. Play Faturalandırma Kitaplığı 6, geriye dönük uyumludur. SKU kavramı kullanımdan kaldırılmış olarak kabul edilir ancak uygulamaları taşıma işlemini daha basit ve aşamalı bir süreç haline getirmek için hâlâ mevcuttur.

Faturalandırma İstemcisi'ni ilk kullanıma hazırlama ve Google Play ile bağlantı kurma

Android uygulamasından satın alma işlemlerini başlatmanın ilk adımları aynıdır:

Satın alınabilecek ürünleri göster

Bir kullanıcının satın almaya uygun olduğu tüm teklifleri almak için:

  • SkuDetailsParams yerine QueryProductDetailsParams koyun
  • BillingClient.queryProductDetailsAsync() kullanmak için BillingClient.querySkuDetailsAsync() görüşmesine geçin

Sorgu sonuçlarının artık SkuDetails yerine ProductDetails olduğunu unutmayın. Her ProductDetails öğesi, ürünle ilgili bilgileri (kimlik, başlık, tür vb.) içerir. Abonelik ürünleri için ProductDetails, abonelik teklifi ayrıntılarının listesi olan bir List<ProductDetails.SubscriptionOfferDetails> içerir. Tek seferlik satın alma ürünleri için ProductDetails, ProductDetails.OneTimePurchaseOfferDetails içerir. Bunlar, kullanıcılara hangi tekliflerin gösterileceğine karar vermek için kullanılabilir.

Aşağıdaki örnekte, bu değişiklikleri yapmadan önce ve yaptıktan sonra uygulamanızın nasıl görünebileceği gösterilmektedir:

Önce

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS).build()

billingClient.querySkuDetailsAsync(params) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

Java

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS).build();

billingClient.querySkuDetailsAsync(params,
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

Sonra

Kotlin

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList).build()

billingClient.queryProductDetailsAsync(params) {
    billingResult,
    productDetailsList ->
    // Process the result
}

Java

ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
                                            .setProductId("up_basic_sub")
                                            .setProductType(ProductType.SUBS)
                                            .build());

QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
    .setProductList(productList)
    .build();

billingClient.queryProductDetailsAsync(
        params,
        new ProductDetailsResponseListener() {
                public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
                    // Process the result
                }
        }
);

queryProductDetailsAsync için geri çağırma, List<ProductDetails> döndürür. Her ProductDetails öğesi, ürünle ilgili bilgileri (kimlik, başlık, tür vb.) içerir. Temel fark, abonelik ürünlerinin artık kullanıcıya sunulan tüm fırsatları içeren bir List<ProductDetails.SubscriptionOfferDetails> da içermesidir.

Play Faturalandırma Kitaplığı'nın önceki sürümleri yeni nesneleri (abonelikler, temel planlar, fırsatlar vb.) desteklemediğinden yeni sistem, her abonelik SKU'sunu geriye dönük uyumlu tek bir temel plana ve fırsata dönüştürür. Kullanılabilir tek seferlik satın alma ürünleri de ProductDetails nesnesine taşınır. Tek seferlik satın alma ürününün teklif ayrıntılarına getOneTimePurchaseOfferDetails() yöntemiyle erişilebilir.

Nadir durumlarda, genellikle Google Play Hizmetleri'nin eski sürümleri nedeniyle bazı cihazlar ProductDetails ve queryProductDetailsAsync()'i destekleyemez. Bu senaryonun düzgün şekilde desteklenmesi için queryProductDetailsAsync işlevini çağırmadan önce PRODUCT_DETAILS özelliği için isFeatureSupported() işlevini çağırın. Yanıt OK ise cihaz bu özelliği destekliyordur ve queryProductDetailsAsync() çağrısı yaparak devam edebilirsiniz. Yanıt FEATURE_NOT_SUPPORTED ise bunun yerine querySkuDetailsAsync() ile geriye dönük uyumlu ürünlerin listesini isteyebilirsiniz. Geriye dönük uyumluluk özelliklerini kullanma hakkında daha fazla bilgi edinmek için Mayıs 2022 abonelik özellikleri kılavuzuna bakın.

Teklif satın alma sürecini başlatma

Bir teklif için satın alma süreci başlatmak, SKU için süreç başlatmaya çok benzer. 6. sürümü kullanarak satın alma isteği başlatmak için aşağıdakileri yapın:

  • BillingFlowParams için SkuDetails yerine ProductDetailsParams kullanın.
  • Teklif numarası ve temel plan kimliği gibi teklif ayrıntıları SubscriptionOfferDetails nesnesi kullanılarak alınabilir.

Kullanıcının seçtiği teklifle bir ürün satın almak için seçilen teklifin offerToken değerini alın ve ProductDetailsParams nesnesine iletin.

BillingFlowParams nesnesi oluşturduktan sonra faturalandırma akışını BillingClient ile başlatma işlemi aynı kalır.

Aşağıdaki örnekte, bu değişiklikleri yapmadan önce ve yaptıktan sonra uygulamanızın nasıl görünebileceği gösterilmektedir:

Önce

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
                            .setSkuDetails(skuDetails)
                            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setSkuDetails(skuDetails)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Sonra

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // For One-time product, "setOfferToken" method shouldn't be called.
        // For subscriptions, to get the offer token corresponding to the selected
        // offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // For one-time products, "setOfferToken" method shouldn't be called.
            // For subscriptions, to get the offer token corresponding to the selected
            // offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken()
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Satın alma işlemlerini işleme

Google Play Faturalandırma Kitaplığı 6 ile satın alma işlemlerini işleme süreci, önceki sürümlere benzer şekilde devam eder.

Kullanıcıya ait tüm etkin satın alma işlemlerini almak ve yeni satın alma işlemleri için sorgu yapmak üzere aşağıdakileri yapın:

  • queryPurchasesAsync() için BillingClient.SkuType değeri iletmek yerine BillingClient.ProductType değeri içeren bir QueryPurchasesParams nesnesi iletin.

Aşağıdaki örnekte, bu değişiklikleri yapmadan önce ve yaptıktan sonra uygulamanızın nasıl görünebileceği gösterilmektedir:

Önce

Kotlin

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

Java

billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // process the result
        }
    }
);

Sonra

Kotlin

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

Uygulama dışı satın alma işlemlerini ve bekleyen işlemleri yönetme adımları değişmemiştir.

Arka ucunuzdaki yeni API ile abonelik satın alma durumunu yönetme

Önceki adımlarda oluşturulan yeni ürünlerin satın alma işlemlerini gerçekleştirmeye hazır olmak için arka ucunuzdaki abonelik satın alma durumu yönetimi bileşenini taşımanız gerekir. Mevcut abonelik satın alma durumu yönetimi bileşeniniz, Mayıs 2022 lansmanından önce tanımladığınız dönüştürülmüş abonelik ürünleri için her zamanki gibi çalışır ve geriye dönük uyumlu tekliflerin satın alma işlemlerini yönetmek için yeterli olur ancak yeni işlevlerin hiçbirini desteklemez.

Arka ucunuzda satın alma durumunu kontrol eden ve Google Play Faturalandırma abonelik haklarını yöneten abonelik satın alma durumu yönetim modülünüz için yeni Subscription Purchases API'yi uygulamanız gerekir. API'nin eski sürümü, yeni platformda satın alma işlemlerini yönetmek için gereken tüm ayrıntıları döndürmez. Önceki sürümlerde yapılan değişikliklerle ilgili ayrıntılı bilgi için Mayıs 2022 yeni abonelik özellikleri kılavuzuna bakın.

Satın alma durumu yönetimi modülünüzü taşırken:

Bu yeni uç nokta, tüm abonelik ürünlerinizin ve tüm satın alma işlemlerinizin durumunu döndürür. Bu durum, ürünlerin satıldığı uygulamanın sürümünden ve ürünün ne zaman tanımlandığından (Mayıs 2022 sürümünden önce veya sonra) bağımsızdır. Bu nedenle, taşıma işleminden sonra abonelik satın alma durumu yönetim modülünüzün yalnızca bu sürümüne ihtiyacınız olacaktır.

Kullanıcının abonelik satın alma işlemlerini değiştirme

Google Play Faturalandırma Kitaplığı 5 ve önceki sürümlerde, kullanıcının abonelik satın alma işlemlerinde yapılan değişiklikleri (ör. yükseltme veya düşürme) uygulamak için ProrationMode kullanılıyordu. Bu, kullanımdan kaldırıldı ve 6. sürümde ReplacementMode ile değiştirildi.

Abonelik fiyatı değişikliklerini yönetme

Daha önce desteği sonlandırılan launchPriceConfirmationFlow API, Google Play Faturalandırma Kitaplığı 6'dan kaldırıldı. Alternatifler için fiyat değişiklikleri kılavuzuna bakın.

Google Play Faturalandırma Kitaplığı hatalarını işleme

Play Faturalandırma Kitaplığı 6'da, kullanıcının cihazı ile Google Play sistemi arasındaki ağ bağlantısıyla ilgili sorunları belirtmek için yeni bir NETWORK_ERROR kodu eklendi. SERVICE_TIMEOUT ve SERVICE_UNAVAILABLE kodlarında da değişiklikler yapıldı. Daha fazla bilgi için BillingResult yanıt kodlarını işleme başlıklı makaleyi inceleyin.

Bekleyen işlemleri yönetme

Play Faturalandırma Kitaplığı, 6.0.0 sürümünden itibaren bekleyen satın alma işlemleri için sipariş kimliği oluşturmaz. Bu satın alma işlemlerinde, satın alma işlemi PURCHASED durumuna taşındıktan sonra sipariş kimliği doldurulur. Entegrasyonunuzun yalnızca bir işlem tamamen tamamlandıktan sonra sipariş kimliği beklediğinden emin olun. Satın alma jetonunu kayıtlarınız için kullanmaya devam edebilirsiniz. Bekleyen satın alma işlemlerini yönetme hakkında daha fazla bilgi için Google Play Faturalandırma Kitaplığı entegrasyon kılavuzunu ve satın alma yaşam döngüsü yönetimi kılavuzunu inceleyin.