CONSUMPTION_REQUEST'in ne olduğunu anlamak yaklaşık bir paragraf sürer. Bunu güvenilir şekilde işleyen bir yapı kurmak ise çok daha uzun sürer ve insanları yanıltan kısımlar, beklediğiniz kısımlar değildir.
İmza doğrulaması bunlardan biri. Onay (consent) bir diğeri, çünkü bildirim gelmeden önce zaten mevcut olması gerekir. Yeniden deneme takvimi de yanıt penceresiyle öyle bir etkileşime giriyor ki çoğu ekip buna ilk kez yakından baktığında şaşırıyor.
Bu yazı, isteğin endpoint'inize ulaştığı andan süreci kapatan entitlement güncellemesine kadar handler'ı adım adım ele alıyor.
Öne Çıkanlar
• CONSUMPTION_REQUEST, bir iade incelemesi sırasında bilgi ister. Kararı yine Apple verir.
• Harekete geçmeden önce imzalı payload'ı doğrulayın. Doğrulanmamış bir bildirime asla güvenmeyin.
• Onay, uygulamanızda zaten mevcut olmalıdır. İstek geldikten sonra onay toplayamazsınız.
• Apple, bildirimden itibaren 12 saat içinde yanıt ister.
• Apple, başarısız teslimatları sabit bir takvime göre yeniden dener ve ikinci deneme yanıt penceresi kapandıktan sonra gelir.
• Sonucu takip edin ve ardından entitlement'ı güncelleyin. Yanıt vermek son adım değildir.
Apple CONSUMPTION_REQUEST bildirimi nedir?
Apple CONSUMPTION_REQUEST bildirimi, sunucunuza bir müşterinin iade talep ettiğini ve Apple'ın sizi bu satın alma hakkında tüketim bilgisi göndermeye davet ettiğini bildiren bir App Store Server Notification'dır. Yapılandırdığınız bildirim URL'sine gelir, ilgili işlemi taşır ve yanıt vermeniz için sınırlı bir süre tanır.
Bu bir iade değildir, bir karar da değildir. Apple incelemenin ortasındadır ve bağlam topluyordur. Sizin rolünüz satın almayla ilgili ne olduğuna dair doğru bilgi sağlamak; Apple'ın rolü ise karar vermektir.
Apple neden CONSUMPTION_REQUEST gönderir?
Çünkü Apple uygulamanızın içini göremez. İşlemi, hesabı ve satın alma geçmişini bilir. İçeriğin teslim edilip edilmediğini, çalışıp çalışmadığını veya müşterinin ne kadarını kullandığını bilmez.
Tüketim bilgisi bu boşluğu doldurur. Apple'ın değerlendirdiği birkaç faktörden biridir, belirleyici olanı değil; yüksek bir tüketim oranı da bir ret anahtarı değildir. Bunu savunduğunuz bir dava olarak değil, katkıda bulunduğunuz bir bağlam olarak görün.
Geliştiriciler CONSUMPTION_REQUEST aldığında ne yapmalı?
Bildirimi doğrulayın, işlemi ve müşteriyi belirleyin, onayı teyit edin, doğru tüketim verilerini derleyin, Apple'ın penceresi içinde gönderin ve ardından olanları kaydedin.
Pratikte on adım:
1. Bildirimi yapılandırdığınız sunucu endpoint'inde alın ve hemen kalıcı olarak kaydedin.
2. Herhangi bir alanı gerçek kabul etmeden önce imzalı payload'ı doğrulayın.
3. Bildirim türünü okuyun ve yönlendirin. Bir tüketim isteği, bir iade sonucu değildir.
4. Çözümlenmiş payload'dan ilgili işlemi belirleyin.
5. İşlemi kendi sisteminizdeki bir müşteri hesabıyla eşleştirin.
6. Bu müşterinin onayının yanıt vermeye izin verip vermediğini kontrol edin.
7. Teslimat ve kullanım verilerini tahminlerden değil, kayıtlarınızdan toplayın.
8. Yanıtı hazırlayın ve alan doğrulama kurallarına göre kontrol edin.
9. Apple'ın consumption endpoint'ine gönderin ve sonucu kaydedin.
10. Ardından gelen iade sonucunu takip edin, sonra entitlement'ı ve kayıtları güncelleyin.
Geliştiriciler CONSUMPTION_REQUEST'i nasıl doğrulamalı?
İçeriğe güvenmeden önce imzayı doğrulayın. Bildirimler, Apple App Store Server Notifications dokümantasyonunda belgelenen imzalı JWS payload'ları olarak gelir; handler'ınız bunları Apple'ın sertifika zincirine göre kontrol etmeli ve bundle ID'nin uygulamanızla eşleştiğini teyit etmelidir.
Nedeni basit. Bildirim URL'niz herkese açık bir endpoint'tir. Gelen her şeyi parse edip buna göre hareket eden bir uygulama, URL'yi bulan herkesin yönlendirebileceği bir uygulamadır.
Üç handler detayı imza kadar önemlidir:
Doğru durum koduyla yanıt verin. Apple, HTTP 200 ile 206 arasını başarı olarak kabul eder. 40x veya 50x, App Store'a yeniden denemesini söyler. Başarı yanıtını işlemeyi bitirdiğinizde değil, bildirimi kaydettiğinizde döndürün — bunlar farklı anlardır ve ikisini birbirine bağlamak, yavaş bir arka plan işinin gereksiz yeniden denemeleri tetiklemesine yol açar.
Yinelenen bildirimleri ele alın. Yeniden denemeler, aynı bildirimin birden fazla kez gelebileceği anlamına gelir ve her biri tekilleştirme için kullanabileceğiniz bir bildirim UUID'si taşır. Tekrarlara hata döndürmek yerine onları onaylayın; bir hata yanıtı yeniden deneme döngüsünü baştan başlatır.
Sandbox'ın farklı davrandığını unutmayın. Yeniden denemeler production'da geçerlidir. Sandbox'ta App Store teslimatı yalnızca bir kez dener; bu yüzden testte sorunsuz görünen bir handler production'da hâlâ olay kaybediyor olabilir, tersi de geçerlidir.
Geliştiriciler yanıt vermeden önce neleri kontrol etmeli?
Dört şey, şu sırayla.
Önce onay, çünkü her şeyi durdurabilecek olan budur. Apple, müşteri verilerini paylaşmadan önce geçerli müşteri onayı ister; bu onayı almak Apple'ın değil sizin sorumluluğunuzdur ve bildirimin kendisi herhangi bir onay bayrağı taşımaz. Apple ayrıca App Tracking Transparency isteminin buradaki mekanizma olmadığını açıkça belirtir. Onay yoksa, yönlendirme yanıt vermemek yönündedir.
İkinci olarak işlem kimliği. Bunun hangi satın alma olduğunu ve arkasında hangi hesabın bulunduğunu bilmeniz gerekir. Bu eşleştirme, appAccountToken ve Apple iade savunması yazısının tam da konusudur; işlemden hesaba istikrarlı bir bağlantı olmadan, bir son tarih baskısı altında tahmin yürütüyorsunuz demektir.
Üçüncü olarak ürün türü, çünkü hangi seçeneklerin size açık olduğunu etkiler. Ve son olarak, gerçekten kullanılabilir veriye sahip olup olmadığınız. Sistemleriniz içeriğin teslim edilip edilmediğini söyleyemiyorsa, bunu yanıt hazırlamaya başlamadan önce bilmekte fayda var.
Geliştiriciler Apple'a hangi tüketim bilgilerini gönderebilir?
Apple'ın güncel Send Consumption Information dokümantasyonu beş alan tanımlar. Üçü zorunlu, ikisi isteğe bağlıdır.
Alan | Zorunlu | Kısaca |
customerConsented | Evet | Müşteri buna onay verdi mi? true olmalıdır, aksi halde istek reddedilir. |
deliveryStatus | Evet | Uygulamanız gerçekten çalışan bir satın alma teslim etti mi, etmediyse neden? |
sampleContentProvided | Evet | Müşteri satın almadan önce deneyebildi mi? |
consumptionPercentage | Hayır | Ne kadarını kullandılar? Milibirim cinsinden — yarısı 50 değil, 50000'dir. |
refundPreference | Hayır | Tercihiniz: tam iade, ret veya orantılı iade. |
İki kural insanları yanıltır. Teslimat durumu "teslim edildi" dışında bir şeyse, tüketim yüzdesi sıfır olmalıdır. İade tercihi de bir tercihtir, bir talimat değil; Apple farklı karar verebilir ve veriyor da.
Hangi endpoint'te olduğunuzu kontrol etmekte fayda var. Apple ayrıca çoğu üçüncü taraf makalenin hâlâ anlattığı, on iki alanlı gövdeye sahip önceki sürüm olan Apple'ın ConsumptionRequestV1 dokümantasyonunu da yayımlıyor. Apple'ın oradaki notu, standart In-App Purchase'ları güncel endpoint'e yönlendiriyor ve V1'i Advanced Commerce API satın almalarıyla sınırlıyor. Entegrasyonunuz bu değişiklikten önceye dayanıyorsa, ilk bakılacak yer burası.
Geliştiricilerin CONSUMPTION_REQUEST'e yanıt vermek için ne kadar süresi var?
Apple'ın güncel dokümantasyonu, bildirimden itibaren 12 saat içinde yanıt istiyor.
Dikkat gerektiren kısım şu. Apple, başarısız teslimatları önceki denemeden 1, 12, 24, 48 ve 72 saat sonra olmak üzere beş kez yeniden dener. Bunu 12 saatlik pencereyle yan yana koyduğunuzda hesap rahatsız edici: endpoint'iniz ilk teslimatı kaçırırsa, ilk yeniden deneme bir saat sonra gelir ve sorun yok. Onu da kaçırırsa, sonraki deneme yaklaşık on üçüncü saatte gelir — pencere çoktan kapandıktan sonra.
Dolayısıyla endpoint güvenilirliği burada genel bir hijyen meselesi değil. Özellikle tüketim istekleri için yaklaşık bir saatlik kesinti telafi edilebilir, yarım günlük kesinti ise edilemez.
Apple, pencereyi kaçırmanın iadenin otomatik olarak onaylanacağı anlamına geldiğini söylemiyor ve böyle bir iddiada bulunmak yanlış olur. Anlamı yalnızca şu: Apple, sağlayabileceğiniz bilgi olmadan karar verir.
Geliştirici yanıt verdikten sonra ne olur?
Apple bilginizi incelemesine alır, diğer her şeyle birlikte tartar ve karar verir. Sonuç ayrı bir bildirim olarak gelir: onaylandı, reddedildi veya Apple onayladığı bir iadeyi sonradan geri alırsa tersine çevrildi.
Burada üç ayrı şey oluyor ve bunları birbirinden ayrı tutmak faydalı. Yanıtınız bilgidir. Apple'ın kararı bir karardır. Sistem güncellemeniz bir durum değişikliğidir. Yalnızca ortadaki Apple'a aittir; üçüncüsü ise siz inşa etmedikçe gerçekleşmez.
Geliştiriciler yanıt sonrasında Apple iadelerini nasıl yönetir
Sonuç geldiğinde iş yeniden size döner.
Sonucu işlem ve müşteri kaydına işleyin. Abonelik durumunu güncelleyin; iade edilen bir dönem genellikle aboneliği çalışır bırakmak yerine sonlandırır. Onaylanan bir iadede entitlement'ı iptal edin, tersine çevirmede geri yükleyin ve bir işlemin yalnızca bir kısmının iptal edildiği orantılı durumu da ele alın.
Ardından tutarı doğru raporlama dönemiyle mutabakata sokun ve iadeyi sorgulanabilir bir geçmişte tutun. Bu geçmiş, daha sonra bir ürünün veya fiyat noktasının orantısız bir pay üretip üretmediğini size söyleyen şeydir; bir müşteri erişimine ne olduğunu sorduğunda destek ekibinin ihtiyaç duyduğu şey de budur.
CONSUMPTION_REQUEST yönetiminde yaygın hatalar nelerdir?
Sürekli karşılaşılanlar:
• Bildirimi bir iade olarak görüp erişimi hemen iptal etmek. Henüz hiçbir şey karara bağlanmadı.
• Payload testte sorunsuz göründüğü için imza doğrulamasını atlamak.
• Yanıt verme zamanı geldiğinde onay akışının olmadığını fark etmek.
• Gerçek tüketim rakamları yerine tahmini rakamlar göndermek.
• İsteği gönderip başarılı olup olmadığını hiç kontrol etmemek. Başarısız bir gönderim, sonrasında başarılı olanla tıpatıp aynı görünür.
• İptali iadeyle karıştırmak. Bunlar erişim üzerinde farklı etkileri olan farklı olaylardır.
• Onaylanan ve reddedilen sonuçları ele alıp tersine çevirme durumunu unutmak; bu, ödeme yapan müşterileri dışarıda bırakır.
• 12 saatlik bir sayaç karşısında birinin bildirimi elle fark etmesine güvenmek.
CONSUMPTION_REQUEST yönetimi otomatikleştirilebilir mi?
Evet ve neredeyse tamamı otomatikleştirilmeli, çünkü hemen her adım deterministik.
Otomasyon; bildirim izleme ve doğrulama, işlem sorgulama, onay kontrolleri, tüketim verisi hazırlama, gönderim, yanıt kaydı, sonuç takibi, dahili uyarılar ve raporlamayı kapsar. Bunların hiçbiri o anda insan yargısı gerektirmez.
İnsana kalan kısım daha yukarıda: uygulamanızdaki onay akışını tasarlamak ve iade tercihi politikanızın ne olması gerektiğine karar vermek. Ayrıca bazı araçlar ne ima ederse etsin, otomasyonun Apple'ın kararı üzerinde hiçbir etkisi yoktur.
RefundSensor geliştiricilerin Apple iade iş akışlarını yönetmesine nasıl yardımcı olur
App Store iade yönetimi kategorinin adı; RefundSensor ise bunun geliştirici tarafını kapsar: Apple iade iş akışlarını izlemek, tüketim istekleri için desteklenen yanıt yolunu yönetmek, iade olaylarını ve sonuçlarını takip etmek ve tekrarlayan işleri insanların üzerinden almak.
Pratikte yanıtlar, kimse sabahın 3'ünde bir dashboard'a bakmadan pencere içinde gider ve iade kayıtları hacim büyüdükçe doğru kalır. İadeleri engellemez ve Apple'ın kararını etkileyemez. Manuel izlemeyi ve atlanan adımları ortadan kaldırır.
Bu Kurallar Nerede Belgelenmiş
Send Consumption Information — güncel endpoint. Onay gereksinimi, 12 saatlik pencere ve beş istek alanı. Standart In-App Purchase'lar için buna göre geliştirin.
Send Consumption Information V1 — on iki alanlı gövdeye sahip önceki endpoint. Entegrasyonunuzun hangi sürümü çağırdığını belirlemek ve Advanced Commerce API satın almaları için faydalı.
App Store Server Notifications — bildirim teslimatı, imzalı payload formatı, beklenen yanıt kodları ve yeniden deneme takvimi.
Bu iş hâlâ elle yapılıyorsa
12 saatlik bir pencere, onu aşabilen bir yeniden deneme takvimi ve gece boyunca gelen bildirimler, manuel izleme için kötü bir kombinasyon. RefundSensor bu iş akışlarının geliştirici tarafını üstlenir: bildirimleri doğrulamak, yanıtları pencere içinde hazırlayıp göndermek ve sonuçları entitlement kayıtlarınıza kadar takip etmek.
Sık sorulan sorular
Sunucunuza bir müşterinin iade talep ettiğini ve Apple'ın sizi satın alma hakkında tüketim bilgisi göndermeye davet ettiğini bildiren bir App Store Server Notification'dır. Bir iade bildirimi ya da karar değildir. Apple kararı ayrıca verir ve yanıtınızı birçok faktörden yalnızca biri olarak değerlendirir.
Çünkü Apple uygulamanızın içinde ne olduğunu göremez. İşlemi ve hesap geçmişini bilir ama içeriğin teslim edilip edilmediğini, çalışıp çalışmadığını veya müşterinin ne kadar kullandığını bilmez. Bu bağlam sizin sistemlerinizde durduğu için Apple inceleme sırasında bunu sizden ister.
İmzalı bildirimi doğrulayın, işlemi ve arkasındaki müşteriyi belirleyin, onayın mevcut olduğunu teyit edin, kayıtlarınızdan gerçek teslimat ve kullanım verilerini toplayın, ardından pencere içinde Apple'ın consumption endpoint'ine gönderin. Çağrının başarılı olduğunu varsaymak yerine yanıt sonucunu kaydedin.
Güncel endpoint'te beş alan vardır. Üçü zorunlu: müşteri onayı, teslimat durumu ve örnek içerik sunulup sunulmadığı. İkisi isteğe bağlı: tüketim yüzdesi ve iade tercihiniz. Önceki V1 endpoint'i on iki alan istiyordu; eski kaynakların daha uzun bir liste anlatmasının nedeni budur.
Apple'ın güncel dokümantasyonu, bildirimi eski belgelerin ima ettiğinden daha geniş şekilde, tüm ürün türlerindeki iade talepleriyle bağlantılı olarak tanımlıyor. Apple her durum için bir garanti yayımlamıyor; bu yüzden her zaman bir istek geleceğini varsayan bir mantık yerine, istek geldiğinde yanıt veren bir handler kurun.
Apple, bildirimden itibaren 12 saat içinde yanıt ister. Şunu belirtmekte fayda var: Apple'ın başarısız teslimatlar için yeniden deneme takvimi 1, 12, 24, 48 ve 72 saat şeklinde işler; dolayısıyla ilk yeniden denemeyi de kaçıracak kadar uzun süre kapalı kalan bir endpoint, bildirimi ancak pencere kapandıktan sonra alabilir.
Apple bunu diğer faktörlerle birlikte değerlendirir ve karar verir. Sonuç, iadenin onaylandığını, reddedildiğini veya sonradan tersine çevrildiğini belirten ayrı bir bildirim olarak gelir. Bundan sonra entitlement'ı, abonelik durumunu ve gelir kayıtlarını yeni işlem durumuna göre güncellemek sizin işinizdir.
Evet. Doğrulama, işlem sorgulama, onay kontrolleri, veri hazırlama, gönderim, kayıt tutma ve sonuç takibinin tamamı deterministiktir. İnsana kalan kısım, onay akışını tasarlamak ve iade tercihi politikanızı belirlemektir. Otomasyonun Apple'ın iade kararı üzerinde hiçbir etkisi yoktur.
