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 yapan ancak daha sonra uygulamayı yükleyip hesabına giriş yapan kullanıcılara ücretli özelliklere otomatik olarak erişim sağlamak
• Tüm abonelik analitiğini tek bir Adapty Kontrol Paneli’nde toplamak (kohortlar, tahminler ve diğer analitik araçlarımız dahil)

Web üzerinden satın almalar uygulamalar için giderek daha popüler hale gelse de Apple App Store, yalnızca ABD’de dijital ürünler için uygulama içi satın alımlardan farklı bir sisteme izin vermektedir. Diğer ülkelerde web aboneliklerinizi uygulamanız 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çıklar.

1. Stripe’ı Adapty’ye bağlama

Bu entegrasyon, esas itibarıyla Adapty’nin webhook aracılığıyla Stripe’tan abonelik verilerini ç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 yapılandırmanızı otomatikleştirmek için Stripe’a Adapty uygulamasını yükleyin:

0. Stripe’ı test modunda mı yoksa canlı modda mı bağlayacağınızı belirleyin. Başlangıçta bunu 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ğini unutmayın. 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ğlayacaktır. Ardından devam etmek için Continue to app settings düğmesine tıklayın.

İzin açılır penceresinin alt kısmında, uygulamayı canlı modda mı yoksa test modunda mı yükleyeceğ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 tekrar göremezsiniz; bu nedenle bir parola yöneticisinde veya güvenli bir depoda 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 bunları Adapty’ye ekleyin.

Kullanımdan kaldırılan 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 düğmesine 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 düğmesine tıklayın:

4. Adapty’den kopyaladığınız webhook URL’sini Endpoint URL alanına yapıştırın. Ardından webhook Version alanında Latest API version seçeneğini 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” düğmesine basın, ardından “Signing secret” altındaki “Reveal” düğmesine basın. Bu, webhook verilerinin Adapty tarafında çözümlenmesinde kullanılan anahtardır; açıkladıktan sonra kopyalayın:

6. Son olarak, bu anahtarı Adapty’nin App Settings → Stripe sayfasındaki “Stripe Webhook Secret” alanına yapıştırın:

2. Stripe’ta ürün oluşturma

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

3. Stripe ürünlerini Adapty’ye ekleme

Stripe’a App Store ve Google Play ile aynı şekilde davranıyoruz: dijital ürünlerinizi sattığınız başka bir mağazadır. Yapılandırması da benzer şekildedir: Stripe ürünlerini (product_id ve price_id değerleriyle birlikte) Adapty’nin Ürünler bölümüne ekleyin:

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

Gerekli tüm ürünleri ekledikten sonra, bir sonraki adım Stripe’a satın almayı kimin yaptığını bildirmektir; böylece Adapty tarafından işlenebilir.

4. Web’den yapılan satın almalara kullanıcı kimliğinizi ekleme

Adapty, kullanıcıların access level’larını 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 kendi tarafınızdan Stripe ile çalışırken 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ı kimliğine güvenmeniz gerekir. Bu, kullandığınız yetkilendirme sisteminden kullanıcının e-postası, telefon numarası veya herhangi bir başka kimlik olabilir.

Kullanıcılarınızı tanımlamak için hangi kimliği kullanmak istediğinize karar verin. Ardından, Stripe üzerinden ödemeyi başlatan kod bölümüne erişin ve bu kullanıcı kimliğini Stripe Subscription (sub_...) veya Checkout Session nesnesinin (ses_...) metadata nesnesine customer_user_id olarak şu şekilde ekleyin:

{'customer_user_id': "YOUR_USER_ID"}

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

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

Web’den gelen mobil kullanıcıların ücretli özelliklere erişebilmesini sağlamak için, bir önceki adımda sağladığınız customer_user_id ile Adapty.activate() veya Adapty.identify() fonksiyonunu çağırmanız yeterlidir (daha fazlası için Kullanıcıları tanımlama iOS, Android, React Native, Flutter ve Unity bölümlerine bakın).

6. Entegrasyonunuzu test etme

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

Profil oluşturma davranışı

Adapty, bir satın almanın mobilde kullanılabilir olması 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ı kimliği olarak ne kullanmak istediğinizi seçebilirsiniz:

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

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

Profil oluşturmamak için dördüncü bir seçeneğiniz de var; ancak Analytics’teki yukarıda belirtilen kısıtlamalar nedeniyle bu önerilmez.

Mevcut kısıtlamalar

Yükseltme, düşürme ve proration

Yükseltme veya düşürme gibi abonelik değişiklikleri, orantılı ücretlere (proration) 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 ü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, herhangi bir proration seçeneğiyle ya da seçeneği olmaksızın hemen iptal edilir
2. Dönem sonunda iptal: Abonelik, mevcut fatura döneminin sonunda iptal edilir (uygulama mağazalarındaki uygulama içi aboneliklere benzer şekilde).

Adapty her iki seçeneği de destekler; ancak anlık iptal için gelir hesaplaması proration seçeneğini göz ardı eder.

Fatura Sorunları ve Ek Süre

Müşteri ödemeyle ilgili bir sorunla karşılaştığında, Adapty bir fatura sorunu olayı oluşturur ve erişim iptal edilir. Şu an için Stripe’ın ek süresini (Grace Period) desteklemiyoruz; bu, gelecek sürümlerde eklenecektir.

Geri ödemeler

Adapty yalnızca tam geri ödemeleri takip eder. Proration veya kısmi geri ödemeler şu anda desteklenmemektedir.

İşlem kimliği 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 önemlidir

Aynı işlem kimliği her iki ortamda da mevcutsa Adapty bunları tek bir işlem olarak değerlendirir ve şu sorunlara yol açar:

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

Benzersizlik nasıl sağlanır

Stripe fatura kimlikleri, Test ve Live ortamları arasında örtüşebilir. Ortamlar arası çakışmaları önlemek için aşağıdaki yaklaşımlardan birini seçin:

1. Seçenek: Ortam önekleri ile hesap düzeyinde numaralandırma

Her ortam için ayrı ayrı önekler 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- (veya test ortamına özgü başka bir önek) olarak ayarlayın.
5. Live moda geçin ve LIVE- (veya canlı ortama özgü başka bir önek) önekini kullanarak 2-4. adımları tekrarlayın.

2. Seçenek: 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 kimliği yeniden kullanabilir. Mümkün olduğunca fatura silmekten kaçınmak en iyisidir.

Stripe Checkout veya Payment Links aracılığıyla tek seferlik satın almalar

Adapty, Stripe Checkout (mode=payment) veya Payment Links aracılığıyla yapılan tek seferlik (abonelik dışı) satın almaları yalnızca Stripe satın alma için bir fatura oluşturduğunda takip eder. Varsayılan olarak, Stripe tek seferlik Checkout satın almaları için fatura oluşturmaz. Bu durumda payment_intent.succeeded fatura verisi olmadan gelir ve bu Adapty’nin işlemi kaydetmesi için yeterli değildir.

Tek seferlik Checkout satın almalarını Adapty’de takip etmek için oturumu oluştururken fatura oluşturmayı etkinleştirin. Stripe daha sonra bir fatura oluşturur ve Adapty’nin işlemi kaydetmek için işlediği invoice.created ve invoice.updated olaylarını gönderir.

Stripe verilerinizden daha fazla yararlanın

Stripe ile entegrasyon sağladıktan sonra Adapty hemen içgörüler sunmaya hazır olur. Stripe verilerinizden en iyi şekilde yararlanmak için, tüm abonelik analitiğinizi tek bir Adapty Kontrol Paneli’nde toplayarak Stripe olaylarını iletmek amacıyla ek Adapty entegrasyonları kurabilirsiniz.

{
  '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