Stripe ile ilk entegrasyon

Adapty, Stripe üzerinden yapılan web ödemelerini ve abonelikleri takip ederek web2app abonelik akışlarını destekler.

Bu entegrasyon, web üzerinden başlatılan satın almaları (Stripe Checkout, barındırılan ödeme sayfaları veya özel web akışları) kapsar ve bunları mobil uygulama erişimiyle ve analitiğiyle senkronize eder.

Aşağıdaki senaryolarda işe yarar:

• Web’den satın alma yapıp daha sonra uygulamayı yükleyen ve hesaplarına giriş yapan kullanıcılara ücretli özelliklere erişimi otomatik olarak sağlamak
• Tüm abonelik analitiğini tek bir Adapty Kontrol Paneli’nde görmek (kohortlar, tahminler ve diğer analitik araçlarımız dahil)

Web satın almaları uygulamalar için giderek daha popüler hale gelse de Apple App Store, dijital ürünler için yalnızca ABD’de uygulama içi satın almalardan farklı bir sisteme izin vermektedir. Web aboneliklerinizi diğer ülkelerdeki kullanıcılara uygulamanızın içinde tanıtmadığınızdan emin olun; aksi takdirde uygulamanız reddedilebilir veya yasaklanabilir.

Aşağıdaki adımlar Stripe entegrasyonunun nasıl yapılandırılacağını açıklamaktadır.

1. Stripe’ı Adapty’ye Bağlayın

Bu entegrasyon esas olarak Adapty’nin webhook aracılığıyla Stripe’tan abonelik verisi çekmesine dayanır. Bu nedenle, API Anahtarlarını sağlayarak ve Stripe’ta Adapty’nin webhook URL’sini kullanarak Adapty hesabınızı Stripe hesabınıza bağlamanız gerekir. Webhook’unuzu otomatik olarak yapılandırmak için Stripe’a Adapty uygulamasını yükleyin:

0. Stripe’ı test modunda mı yoksa canlı modda mı bağladığınıza karar verin. Başlangıçta test modunda yapıyorsanız, aşağıdaki adımları canlı mod için de tekrarlamanız gerekecektir.

1. Stripe App Marketplace’e gidin ve Adapty uygulamasını yükleyin. Sandbox modunun uygulama yüklemeyi desteklemediğine dikkat edin. Bunu yalnızca production veya test modunda yapabilirsiniz.

2. Uygulamaya gerekli izinleri verin. Bu, Adapty’nin abonelik verilerine ve geçmişine erişmesini sağlar. Ardından devam etmek için Continue to app settings butonuna tıklayın.

İzin açılır penceresinin alt kısmında uygulamayı canlı modda mı yoksa test modunda mı yüklemek istediğinizi seçebilirsiniz.

3. Açılır pencerede yeni bir kısıtlı anahtar oluşturun. E-postanız, Touch ID veya güvenlik anahtarınızı kullanarak kimliğinizi doğrulamanız gerekecektir. Anahtarı oluşturduktan sonra bir daha göremezsiniz; bu nedenle bir parola yöneticisinde veya gizli bir depoda güvenle saklayın.

4. Oluşturulan anahtarı açılır pencereden kopyalayın ve Adapty’nin App Settings → Stripe sayfasına gidin. Anahtarı modunuza göre Stripe App Restricted API Key bölümüne yapıştırın. Test ve canlı modlar için farklı anahtarlar oluşturmanız gerektiğini unutmayın.

Hepsi bu kadar! Şimdi Stripe’ta ürünlerinizi oluşturun ve onları Adapty’ye ekleyin.

Eski kurulum akışı

1. Stripe’ta Developers → API Keys bölümüne gidin:

2. Secret key başlığının yanındaki Reveal live (test) key button butonuna tıklayın, ardından kopyalayın ve Adapty’nin App Settings → Stripe sayfasına gidin. Anahtarı buraya yapıştırın:

3. Ardından Adapty’deki aynı sayfanın alt kısmından Webhook URL’sini kopyalayın. Stripe’ta Developers → Webhooks bölümüne gidin ve Add endpoint butonuna tıklayın:

4. Adapty’deki webhook URL’sini Endpoint URL alanına yapıştırın. Ardından webhook Version alanında Latest API version’ı seçin. Sonra aşağıdaki olayları seçin:

   • charge.refunded
   • customer.subscription.created
   • customer.subscription.deleted
   • customer.subscription.paused
   • customer.subscription.resumed
   • customer.subscription.updated
   • invoice.created
   • invoice.updated
   • payment_intent.succeeded

5. “Add endpoint” butonuna basın, ardından “Signing secret” altındaki “Reveal” butonuna basın. Bu, webhook verilerini Adapty tarafında çözmek için kullanılan anahtardır; görünür hale geldikten sonra kopyalayın:

6. Son olarak bu anahtarı Adapty’nin App Settings → Stripe bölümündeki “Stripe Webhook Secret” alanına yapıştırın:

2. Stripe’ta ürünler oluşturun

Stripe’ın Product catalog bölümüne gidin ve satmak istediğiniz ürünleri ve fiyatlandırma planlarını oluşturun. Stripe’ın her ürün için birden fazla fiyatlandırma planına izin verdiğine dikkat edin; bu, ek ürün oluşturmaya gerek kalmadan teklifinizi özelleştirmeniz için kullanışlıdır.

3. Stripe ürünlerini Adapty’ye ekleyin

Stripe’a App Store ve Google Play ile aynı şekilde davranıyoruz: sadece dijital ürünlerinizi sattığınız başka bir mağaza. Dolayısıyla benzer şekilde yapılandırılır: Stripe ürünlerini (product_id ve price_id) Adapty’nin Products bölümüne eklemeniz yeterlidir:

Stripe’taki ürün ID’leri prod_..., fiyat ID’leri ise price_... şeklinde görünür. Stripe’ın Product Catalog bölümünde herhangi bir ürünü açtığınızda bunları kolayca bulabilirsiniz:

Gerekli tüm ürünleri ekledikten sonra sıradaki adım, Stripe’a hangi kullanıcının satın alma yaptığını bildirmektir; böylece Adapty tarafından yakalanabilir!

4. Web’de yapılan satın almaları kullanıcı ID’nizle zenginleştirin

Adapty, kullanıcılara access level sağlamak ve güncellemek için tek bilgi kaynağı olarak Stripe’tan gelen webhook’lara dayanır. Ancak bu entegrasyonun düzgün çalışması için Stripe ile çalışırken kendi tarafınızdan ek bilgi sağlamanız gerekir.

Access level’ların platformlar arası (web veya mobil) tutarlı olması için, Adapty’nin webhook’lardan tanıyabileceği tek bir kullanıcı ID’sine dayanmanız gerekir. Bu, kullanıcının e-postası, telefon numarası veya kullandığınız yetkilendirme sistemindeki herhangi bir ID olabilir.

Kullanıcılarınızı tanımlamak için hangi ID’yi kullanmak istediğinizi belirleyin. Ardından Stripe üzerinden ödemeyi başlatan kod bölümünüze gidin ve bu kullanıcı ID’sini Stripe Subscription (sub_...) veya Checkout Session nesnesinin (ses_...) metadata objesine customer_user_id olarak şu şekilde ekleyin:

{'customer_user_id': "YOUR_USER_ID"}

Bu tek basit ekleme, kodunuzda yapmanız gereken tek şeydir. Bundan sonra Adapty, Stripe’tan aldığı tüm webhook’ları işleyecek, bu metadata’yı çıkaracak ve abonelikleri doğru şekilde müşterilerinizle ilişkilendirecektir.

5. Mobil kullanıcılara erişim sağlayın

Web’den gelen mobil kullanıcıların ücretli özelliklere erişebildiğinden emin olmak için Adapty.activate() veya Adapty.identify() çağrısını bir önceki adımda sağladığınız aynı customer_user_id ile yapın (daha fazla bilgi için bkz. Identifying users iOS, Android, React Native, Flutter ve Unity ).

6. Entegrasyonunuzu test edin

Yukarıdaki adımları hem Sandbox hem de Production için tamamladığınızdan emin olun. Stripe’ın Test modundan yapacağınız işlemler Adapty’de Sandbox olarak kabul edilecektir.

Profil oluşturma davranışı

Adapty, bir satın almayı mobilden erişilebilir kılmak için onu bir müşteri profiline bağlamak zorundadır; bu nedenle varsayılan olarak Stripe’tan webhook aldığında profil oluşturur. Adapty’de müşteri kullanıcı ID’si olarak ne kullanmak istediğinizi seçebilirsiniz:

1. Varsayılan ve önerilen: Yukarıdaki 4. adımda metadata’da sağladığınız customer_user_id
2. Stripe’ın Customer nesnesindeki email (bkz. Stripe dokümantasyonu)
3. Stripe’ın Session nesnesindeki client_reference_id (bkz. Stripe dokümantasyonu)

App Settings → Stripe bölümünden hangi ID’yi kullanmak istediğinizi yapılandırabilirsiniz.

Dördüncü bir seçenek olarak hiç profil oluşturmamayı da seçebilirsiniz, ancak yukarıdaki Analytics kısıtlamaları nedeniyle bu önerilmez.

Mevcut sınırlamalar

Yükseltme, düşürme ve orantılı hesaplama

Yükseltme veya düşürme gibi abonelik değişiklikleri orantılı ücretlere yol açabilir. Adapty bu ücretleri gelir hesaplamalarında dikkate almaz. Bu seçenekleri Stripe kontrol paneli üzerinden manuel olarak devre dışı bırakmanız en iyisi olacaktır. Ayrıca Stripe API’si üzerinden proration_behaviour öznitelik değerini none olarak ayarlayarak da devre dışı bırakabilirsiniz.

İptaller

Stripe’ın iki abonelik iptal seçeneği vardır:

1. Anlık iptal: Abonelik, orantılı hesaplama seçeneği olsun ya da olmasın anında iptal edilir
2. Dönem sonunda iptal: Abonelik, mevcut faturalama döneminin sonunda iptal edilir (uygulama mağazalarındaki uygulama içi aboneliklere benzer).

Adapty her iki seçeneği de destekler, ancak anlık iptal için gelir hesaplaması orantılı hesaplama seçeneğini dikkate almayacaktır.

Faturalama Sorunları ve Ek Süre

Bir müşteri ödemesinde sorunla karşılaştığında Adapty bir faturalama sorunu olayı oluşturur ve erişim iptal edilir. Stripe’ın ek süresini henüz desteklemiyoruz — bu gelecekteki sürümlerin bir parçası olacak.

Geri ödemeler

Adapty yalnızca tam geri ödemeleri takip eder. Orantılı veya kısmi geri ödemeler şu an için desteklenmemektedir.

İşlem ID’si benzersizliği

Adapty, profilleri ve işlemleri store_transaction_id ve store_original_transaction_id kullanarak eşleştirir. Bunların Test ve Production ortamları arasında benzersiz olması gerekir.

Bu neden önemli

Aynı işlem ID’si her iki ortamda da mevcutsa Adapty bunları tek bir işlem olarak değerlendirerek şunlara yol açar:

• Production satın almalarının Test access level’larını ve ürün ID’lerini devralması
• API yanıtlarında yanlış ürün ID’leri ve ortamlar
• Profil bağlantısının ve abonelik olaylarının bozulması

Benzersizliği nasıl sağlarsınız

Stripe fatura ID’leri Test ve Live ortamları arasında örtüşebilir. Ortamlar arası çakışmaları önlemek için şu yaklaşımlardan birini seçin:

Seçenek 1: Ortam önekleriyle hesap düzeyinde numaralandırma

Her ortam için önekleri ayrı ayrı yapılandırın:

1. Stripe Dashboard’da Test moduna geçin.
2. Settings → Billing → Invoices bölümüne gidin.
3. Invoice numbering değerini Sequentially across your account olarak ayarlayın.
4. Invoice prefix değerini TEST- olarak ayarlayın (veya test ortamına özgü başka bir önek).
5. Live moduna geçin ve 2-4 arasındaki adımları tekrarlayarak LIVE- (veya canlı ortama özgü başka bir önek) önekini kullanın.

Seçenek 2: Müşteri düzeyinde numaralandırma

Stripe settings -> Billing -> Invoices sekmesindeki Invoice numbering değerini Sequentially for each customer (customer-level) olarak ayarlayın.

Yukarıdaki yapılandırmayla bile bir faturayı silerseniz Stripe, aynı müşterinin yeni faturaları için bu ID’yi yeniden kullanabilir. Mümkün olduğunca fatura silmekten kaçınmak en iyisidir.

Stripe verilerinizden daha fazla yararlanın

Stripe ile entegre olduğunuzda Adapty hemen içgörüler sağlamaya hazırdır. Stripe verilerinizden en iyi şekilde yararlanmak için Stripe olaylarını iletmek üzere ek Adapty entegrasyonları kurabilirsiniz; böylece tüm abonelik analitiğinizi tek bir Adapty Kontrol Paneli’nde toplayabilirsiniz.

{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}

Stripe olaylarınızı iletmek ve analiz etmek için kullanabileceğiniz entegrasyonlar:

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

Desteklenen Stripe olayları

Adapty aşağıdaki Stripe olaylarını destekler:

• charge.refunded
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded