Harici ödemeler için uygulama içi entegrasyon rehberi

Bu belgede, uygun uygulamalarda harici ödemeler sunmak için Play Faturalandırma Kitaplığı API'lerinin nasıl entegre edileceği açıklanmaktadır. Bu program hakkında daha fazla bilgi edinmek için program şartlarını inceleyin.

Play Faturalandırma Kitaplığı kurulumu

Android uygulamanıza Play Faturalandırma Kitaplığı bağımlılığını ekleyin. Harici ödeme API'lerini kullanmak için 8.3 veya sonraki bir sürümü kullanmanız gerekir. Daha eski bir sürümden taşıma yapmanız gerekiyorsa entegrasyonunuza başlamadan önce yükseltmek için taşıma kılavuzundaki talimatları uygulayın.

Fatura istemcisini başlatma

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:

Aşağıdaki örnekte, BillingClient'ın bu değişikliklerle başlatılması gösterilmektedir:

Kotlin

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

val developerProvidedBillingListener =
    DeveloperProvidedBillingListener { details ->
        // Handle user selection for developer provided billing option.
    }

val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build()

Java

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

private DeveloperProvidedBillingListener developerProvidedBillingListener =
    new DeveloperProvidedBillingListener() {
        @Override
        public void onUserSelectedDeveloperBilling(
            DeveloperProvidedBillingDetails details) {
            // Handle user selection for developer provided billing option.
        }
    };

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build();

Google Play'e bağlanma

BillingClient cihazını başlattıktan sonra Google Play'e bağlanma bölümünde açıklandığı şekilde Google Play'e bağlanın.

Kullanıcı uygunluğunu kontrol etme

Google Play'e bağlandıktan sonra isBillingProgramAvailableAsync() yöntemini çağırarak kullanıcının harici ödeme programına uygun olup olmadığını kontrol edebilirsiniz. Bu yöntem, kullanıcı uygunsa BillingResponseCode.OK değerini döndürür. Aşağıdaki örnekte uygunluk durumunun nasıl kontrol edileceği gösterilmektedir:

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return
        }

        // External payments are available. Can proceed with generating an
        // external transaction token.
})

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return;
        }

        // External payments are available. Can proceed with generating an external transaction token.
      }

    });

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 uzantılarını kullanıyorsanız ayrı bir dinleyici tanımlamanıza gerek kalmaması için Kotlin eşzamanlı rutinlerini kullanabilirsiniz.

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örüp birini satın almak için seçtiğinde Harici ödeme akışını başlatma bölümünde açıklandığı şekilde harici ödeme akışını başlatın.

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. Kullanıcı, harici ödeme API'si aracılığıyla harici bir web sitesini veya uygulamayı her ziyaret ettiğinde yeni bir harici işlem jetonu oluşturulmalıdır. Bu işlem, createBillingProgramReportingDetailsAsync API'si çağrılarak yapılabilir. Jeton, launchBillingFlow çağrılmadan hemen önce oluşturulmalıdır.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .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 external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
    }
})

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .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 external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
      }
});

Kotlin uzantılarını kullanıyorsanız ayrı bir dinleyici tanımlamanıza gerek kalmaması için Kotlin eşzamanlı rutinlerini kullanabilirsiniz.

Harici ödeme akışını başlatma

launchBillingFlow() işlevini çağırarak harici ödeme akışını başlatın. Bu işlem, Google Play Faturalandırma Sistemi entegrasyonuyla satın alma akışı başlatmaya benzer ancak ek bir parametre içerir. DeveloperBillingOptionParams Bu parametre, uygulamanızın bu satın alma işlemi için harici ödeme akışını etkinleştirmek istediğini belirtir.

DeveloperBillingOptionParams şunları içermelidir:

Uygulamanız launchBillingFlow() işlevini DeveloperBillingOptionParams sağlanmış şekilde çağırdığında Google Play Faturalandırma Sistemi aşağıdaki kontrolü yapar:

  • Sistem, kullanıcının Google Play ülkesinin harici ödemeleri destekleyen bir ülke (yani desteklenen bir ülke) olup olmadığını kontrol eder. Kullanıcının Google Play ülkesi destekleniyorsa Google Play, BillingClient'ın yapılandırmasına ve DeveloperBillingOptionParams sağlanıp sağlanmadığına göre harici ödemelerin etkin olup olmadığını kontrol eder.
    • Harici ödemeler etkinleştirilmişse satın alma akışında kullanıcı seçimi kullanıcı deneyimi gösterilir.
    • Harici ödemeler etkinleştirilmemişse satın alma akışında, kullanıcı tercihine göre faturalandırma seçeneği sunulmadan 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

Harici ödemeler etkinleştirilmiş olmalıdır (BillingClient kurulumu ve launchBillingFlow).

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.

Harici ödemeler etkinleştirilmedi (BillingClient kurulumu sırasında etkinleştirilmedi veya launchBillingFlow için DeveloperBillingOptionParams sağlanmadı)

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.

Aşağıdaki snippet'te DeveloperBillingOptionParams nasıl oluşturulacağı gösterilmektedir:

Kotlin

val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("https://www.example.com/external/purchase")
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build()

Java

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("https://www.example.com/external/purchase")
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build();

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 web sitenizde ödeme yapmayı mı seçtiğine bağlı olarak değişir.

Kullanıcı, web sitenizde veya bir ödeme uygulamasında ödeme yapmayı seçtiğinde

Kullanıcı web sitenizde ödeme yapmayı seçerse Google Play, kullanıcının web sitenizde veya bir ödeme uygulamasında ödeme yapmayı seçtiğini uygulamaya bildirmek için DeveloperProvidedBillingListener yöntemini çağırır. Özellikle onUserSelectedDeveloperBilling() yöntemi çağrılır.

Uygulamanız launchMode değerini LAUNCH_IN_EXTERNAL_BROWSER_OR_APP olarak ayarlarsa Google Play bağlantıyı başlatır. launchMode, CALLER_WILL_LAUNCH_LINK olarak ayarlanmışsa bağlantıyı başlatmak uygulamanızın sorumluluğundadır. Kullanıcıları bir ödeme uygulamasına bağlarken kullanıcının cihazında ödeme uygulamasının yüklü olup olmadığını kontrol etmek sizin sorumluluğunuzdadır.

Bu seçimin sonucu olan işlemleri arka uç entegrasyon kılavuzunda açıklandığı şekilde bildirmek için bu jetonu kullanın.

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 işleneceği 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 rehberindeki Yeni abonelikler bölümüne bakın.

Abonelikteki değişiklikleri ele alma

Harici ödemeleri kullanan geliştiriciler için satın alma işlemleri, kullanıcının seçimine bağlı olarak Google Play'in faturalandırma sistemi üzerinden işlenmeli veya externalTransactionId ile bildirilmelidir. Geliştiricinin web sitesi ü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, abonelik değişikliğiyle ilgili bazı yaygın senaryoları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 akışları), aboneliğin ilk olarak Google Play'in faturalandırma sistemi üzerinden mi yoksa geliştiricinin web sitesi üzerinden 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ı olan eklentiler, yükseltme olarak değerlendirilir. Diğer eklentiler için kullanıcılar hangi faturalandırma sistemini kullanmak istediklerini seçebilmelidir. Harici ödeme akışını başlatma bölümünde açıklandığı gibi launchBillingFlow() kullanarak yeni bir satın alma deneyimi başlatın.

Geliştiricinin web sitesi veya bir ödeme uygulaması üzerinden satın alınan abonelikler

Başlangıçta geliştiricinin web sitesi veya kullanıcı tercihi sonrasında bir ödeme uygulaması üzerinden satın alınan aboneliklerde, yükseltme veya düşürme isteğinde bulunan kullanıcılar, kullanıcı tercihi deneyimini tekrar yaşamadan geliştiricinin web sitesi ya da bir ödeme uygulaması ü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. SubscriptionUpdateParams nesnesi altında diğer parametreleri belirtmek yerine, orijinal satın alma işlemi için harici işlem kimliğini sağlayan setOriginalExternalTransactionId() öğesini kullanın.

Bu görüşmede DeveloperBillingOptionParams da sağlanmalıdır. Bu işlem, orijinal satın alma işleminde kullanıcının yaptığı seçim yükseltme ve düşürme işlemleri için geçerli olduğundan kullanıcı seçim ekranını göstermez. Burada açıklandığı şekilde bu işlem için yeni bir harici işlem jetonu oluşturmanız gerekir.

Yükseltme veya düşürme işlemi geliştiricinin web sitesi ya da bir ödeme uygulaması kullanılarak tamamlandığında, yeni abonelik satın alma işlemi için önceki çağrı aracılığıyla alınan 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ı tercihinden sonra Google Play'in faturalandırma sistemi üzerinden satın alan kullanıcılara standart Google Play Billing akışı gösterilmelidir. DeveloperBillingOptionParams, launchBillingFlow çağrısında ayarlanmamalıdır.

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 yaklaşık 2 hafta boyunca hizmete erişmeye devam edebilir. Bu süre boyunca abonelik teknik olarak etkin kalır ve kullanıcı hizmeti kullanabilir.

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, harici ödeme API'si entegrasyonunuzda geri yükleme senaryolarının nasıl ele alınacağı açıklanmaktadır.

Geliştiricinin web sitesinden satın alınan abonelikler

İptal edilen bir abonelik için harici bir 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. Bu kapsamda, kullanıcının 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 promosyonlar) yer alır.

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

Genellikle kullanıcılar, Google Play'in faturalandırma sisteminde abonelikleri geri yükleyebilir. Başlangıçta Google Play'in faturalandırma sistemi üzerinden satın alınan iptal edilmiş aboneliklerde kullanıcı, abonelik Google Play'in Yeniden abone ol özelliği aracılığıyla etkin durumdayken iptal işlemini geri alabilir. Bu durumda, arka uçta SUBSCRIPTION_RESTARTED anlık geliştirici bildirimi alırsınız ve yeni bir satın alma jetonu verilmez. Aboneliği devam ettirmek için orijinal jeton 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 Geri yüklemeler bölümüne bakın.

Ayrıca, launchBillingFlow() işlevini çağırarak Google Play'in faturalandırma sisteminde geri yükleme işlemini tetikleyebilirsiniz. Bunun nasıl yapılacağıyla ilgili açıklama için Abonelik süresi dolmadan önce - uygulama içi başlıklı makaleyi inceleyin. İ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, bu kullanıcıların tercihlerini 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 Real Time Developer Notification (Gerçek Zamanlı Geliştirici Bildirimi) alır ve yeni satın alma durumu için linkedPurchaseToken değeri, 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 ödemenin kurtarma olmadan reddedilmesi (süresi dolmuş hesap askıya alınma durumu) nedeniyle tamamen sona ererse kullanıcının haklarını yeniden başlatmak için yeniden abone olması gerekir.

Yeniden abone olma işlemi, standart bir kayıt işlemine benzer şekilde işlenerek uygulama üzerinden de etkinleştirilebilir. Kullanıcılar, hangi faturalandırma sistemini kullanmak istediklerini seçebilmelidir. Bu durumda, harici ödeme akışını başlatma bölümünde açıklandığı gibi launchBillingFlow() çağrılabilir.

Yanıt işleme

Bir hata oluştuğunda isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync(), launchBillingFlow() yöntemleri BillingResponseCode.OK dışında bir BillingResponseCode sağlayabilir. Bu yanıt kodlarını aşağıdaki gibi işlemeyi düşünebilirsiniz:

  • BillingResponseCode.ERROR: Bu bir dahili hatadır. İşleme veya harici web sitesini açmaya devam etmeyin. API'yi tekrar çağırarak yeniden deneyin.
  • BillingResponseCode.FEATURE_NOT_SUPPORTED: Harici ödeme API'leri, mevcut cihazda Play Store tarafından desteklenmiyor. İşleme veya harici web sitesini açmaya devam etmeyin.
  • BillingResponseCode.DEVELOPER_ERROR: İsteğinizde hata var. Devam etmeden önce hatayı belirlemek ve düzeltmek için hata ayıklama mesajını kullanın.
  • BillingResponseCode.USER_CANCELED: Harici web sitesini veya uygulamayı açma işlemine devam etmeyin. Kullanıcıyı uygulamanın dışına yönlendirmeyi bir sonraki denemenizde bilgi iletişim kutusunu göstermek için launchBillingFlow() işlevini tekrar çağırın.
  • BillingResponseCode.BILLING_UNAVAILABLE: İşlem, harici ödemeler için uygun değildir. Bu nedenle, bu program kapsamında geliştirici faturalandırması kullanılamaz. Bunun nedeni, kullanıcının bu program için uygun bir ülkede olmaması veya hesabınızın programa başarıyla kaydedilmemiş olmasıdır. İkinci durum söz konusuysa Play Console'daki kayıt durumunuzu kontrol edin.
  • BillingResponseCode.NETWORK_ERROR, BillingResponseCode.SERVICE_DISCONNECTED, BillingResponseCode.SERVICE_UNAVAILABLE: Bunlar geçici hatalardır ve uygun bir yeniden deneme politikasıyla ele alınmalıdır. SERVICE_DISCONNECTED durumunda, yeniden denemeden önce Google Play ile bağlantıyı yeniden kurun.

Harici ödeme bağlantılarını test etme

Harici ödeme 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ç entegrasyonuna başlayabilirsiniz.