Son birkaç yılda CONSUMPTION_REQUEST hakkında herhangi bir yerde bir şeyler okuduysanız, muhtemelen on iki alanlık bir liste görmüşsünüzdür: hesap yaşı, toplam satın alma tutarı, oynama süresi, platform ve benzerleri.
Bu liste endpoint'in eski sürümüne ait. Apple'ın güncel sürümü beş alan alıyor, üçü zorunlu, ve orijinalinden daha fazla ürün türünü kapsıyor. Hâlâ eski yapıya göre kurulmuş pek çok canlı entegrasyon var.
Bu yazı, bildirimin aslında ne olduğunu, Apple'ın bugün ne beklediğini ve dayanıklı bir yanıt akışını nasıl kuracağınızı adım adım ele alıyor.
Öne Çıkanlar
• CONSUMPTION_REQUEST, iade incelemesi sırasında bilgi isteyen bir bildirimdir. Bir iade değildir, bir karar da değildir.
• İade kararını Apple verir. Yanıtınız bu karara giren girdilerden yalnızca biridir.
• Güncel endpoint beş alan alır, üçü zorunludur ve tüm ürün türlerini kapsar.
• Müşteri onayı zorunludur. Onayın doğrulanmadığı istekleri Apple reddeder.
• Apple, bildirimden itibaren 12 saat içinde yanıt bekler.
• Endpoint'in iki sürümü vardır. Entegrasyonunuzun hangisini çağırdığını kontrol edin.
Apple CONSUMPTION_REQUEST nedir?
Apple CONSUMPTION_REQUEST, bir müşterinin iade talep ettiğini sunucunuza bildiren ve sizi o satın alma hakkında tüketim bilgisi göndermeye davet eden 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 bildirimi değildir. Geldiğinde henüz hiçbir şeye karar verilmemiştir; Apple talebi değerlendirmenin ortasındadır ve işi bitirmeden önce bağlam topluyordur. Bir geliştirici için pratik anlamı dar: backend'inize az önce bir iş düştü, bu işin bir son tarihi var ve yalnızca sizin sistemlerinizde bulunan verilere ihtiyaç duyuyor.
Apple neden CONSUMPTION_REQUEST gönderir?
Çünkü Apple işlemin yalnızca yarısını görebilir.
Apple neyin, ne zaman, hangi hesapla satın alındığını ve o hesabın geçmişinin nasıl göründüğünü bilir. Uygulamanızın içini göremez: jetonların hesaba işlenip işlenmediğini, kilit açmanın çalışıp çalışmadığını ya da müşterinin parasını geri istemeden önce ne kadar kullandığını bilemez.
Buradaki “tüketim”, müşterinin satın aldığı şeyle ne kadar ilerlediği anlamına gelir. Üç hafta boyunca her gün kullanılan bir abonelik ile hiç açılmamış bir abonelik Apple'a aynı görünür. Size aynı görünmez.
Sınırları net koymakta fayda var. Apple yalnızca bir tüketim rakamına bakarak onaylamaz ya da reddetmez. Bu bilgi, birden fazla faktörü tartan bir karara girdi sağlar ve yüksek bir tüketim yüzdesi bir ret düğmesi değildir.
Apple CONSUMPTION_REQUEST nasıl çalışır?
Sıralama şöyle görünür:
Müşteri iade talebi başlatır
↓
Apple iade incelemesine başlar
↓
CONSUMPTION_REQUEST bildirim endpoint'inize ulaşır
↓
Bildirimi doğrular ve işlemi tespit edersiniz
↓
Onayı kontrol eder ve kullanım verisini toplarsınız
↓
Gereklilikler karşılanıyorsa tüketim bilgisini gönderirsiniz
↓
Apple bilgiyi değerlendirir
↓
Apple iade kararını verir
↓
Ortaya çıkan işlem durumunu takip edersiniz
Bir çekince. Apple'ın güncel dokümantasyonu bu bildirimi tüm ürün türlerindeki iade talepleriyle ilişkili olarak tanımlıyor; bu, eski dokümantasyonun ima ettiğinden daha geniş bir kapsam. Ancak Apple her durumda bir bildirim geleceğine dair 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 geliştiricilerden hangi bilgileri ister?
Apple'ın güncel Send Consumption Information endpoint'i beş alan alır. Üçü zorunlu, ikisi isteğe bağlıdır.
Alan | Zorunlu | Anlamı |
customerConsented | Evet | true olmalıdır. Aksi halde Apple isteği reddeder. |
deliveryStatus | Evet | Uygulamanızın çalışan bir satın almayı teslim edip etmediği ve etmediyse nedeni. |
sampleContentProvided | Evet | Müşterinin satın almadan önce içeriği deneyip deneyemediği. |
consumptionPercentage | Hayır | Ne kadarının tüketildiği, milli birim cinsinden (50% için 50000). |
refundPreference | Hayır | Tam iade, ret veya orantılı iade — tercihinizdir, karar değildir. |
İki doğrulama kuralı insanları yanıltıyor. Teslimat durumu “delivered” dışında bir değerse tüketim yüzdesi sıfır olmalıdır, aksi halde istek başarısız olur. Ayrıca milli birimler yüzde değildir; yarısı tüketilmişse değer 50000'dir.
İade tercihi en yeni parça ve en çok yanlış anlaşılmaya açık olanı. Apple'a iadenin tam olarak verilmesini, reddedilmesini ya da orantılı yapılmasını tercih ettiğinizi söyleyebilirsiniz; Apple bunu diğer her şeyle birlikte tartar. Sonuç farklı olabilir. Orantılı bir iade onaylanırsa geri alınan kısım işlem payload'ında gelir; dolayısıyla entitlement mantığınızın kısmi geri almayı ele alması gerekir.
Kontrol etmeye değer sürüm farkı
Apple bu endpoint'in iki sürümünü belgeliyor ve adlandırma kolayca yanlış okunabiliyor. Send Consumption Information V1, çoğu üçüncü taraf makalenin hâlâ anlattığı on iki alanlık gövdeye sahip eski sürümdür. Apple'ın o sayfadaki kendi notu, standart In-App Purchase'ları güncel endpoint'e yönlendiriyor ve V1'i Advanced Commerce API kullanan satın almalarla sınırlıyor.
| Güncel endpoint | V1 endpoint |
İstek alanları | 5 (3 zorunlu) | 12 |
Ürün türleri | Dört türün tamamı | Tüketilebilir ürün ve otomatik yenilenen abonelik |
Kullanım alanı | Standart In-App Purchase'lar | Advanced Commerce API satın almaları |
Entegrasyonunuz bu değişiklikten önceye dayanıyorsa işe buradan başlayın.
Tüketim bilgisi nedir?
Tüketim bilgisi, müşteri satın aldıktan sonra o satın almayla ne olduğunu anlatmak için Apple'a gönderdiğiniz veridir: teslim edilip edilmediği, müşterinin önceden deneyip deneyemediği ve ne kadarını kullandığı.
Önemlidir çünkü resmin Apple'ın göremediği tek parçası budur. Bir abonelik uygulaması için müşterinin satın aldıktan sonra hizmeti kullanıp kullanmadığını anlatır. Tüketilebilir bir ürün için bakiyenin ne kadarının harcandığını. Tüketilemeyen bir ürün için kilit açmanın çalışıp çalışmadığını.
Önemli kelime “doğru”. Bu, paylaşmak için onay aldığınız, kayıtlarınızdan çekilen veridir. Kurduğunuz bir argüman değildir ve onu tercih ettiğiniz sonuca doğru eğmek, güvenilir bir kazanç sağlamadan gerçek bir risk taşır.
Geliştiriciler CONSUMPTION_REQUEST'e nasıl yanıt vermeli?
Dokuz adım; işin çoğu da herhangi bir istek gelmeden önce yapılır.
1. Bildirimi alın
İstekler, App Store Server Notifications V2 için belirlediğiniz URL'ye gelir. Apple'ın App Store Server Notifications dokümantasyonu kurulumu ve payload yapısını anlatır. Yanlış yapılandırılmış bir endpoint, isteğin size hiç ulaşmaması demektir, hem de sessizce.
2. Bildirimi doğrulayın
Payload'lar imzalıdır. İçindeki herhangi bir şeye göre işlem yapmadan önce Apple'ın sertifika zincirine karşı doğrulayın ve bundle ID'yi teyit edin.
3. İlgili işlemi tespit edin
Çözülmüş payload'dan işlem tanımlayıcılarını alın ve satın alma kayıtlarınızla eşleştirin. Saklanmış bir kayıt yoksa arama da yapılamaz, tüketimi tanımlamak için bir dayanak da olmaz.
4. Onayın yanıt vermeye izin verip vermediğini kontrol edin
Apple, müşteri verisini paylaşmadan önce geçerli müşteri onayı ister ve bu onayı almak sizin sorumluluğunuzdur. Bildirim bir onay bayrağı taşımaz; bu yüzden bunu kendi kayıtlarınızdan bilmeniz gerekir. Apple ayrıca App Tracking Transparency isteminin bunun mekanizması olmadığını belirtir; bu, uygulamanızda toplanan ayrı bir onaydır. Onay yoksa Apple'ın yönlendirmesi yanıt vermemenizdir. Bu aramayı mümkün kılan tanımlama tarafını, appAccountToken ve Apple iade savunması hakkındaki yazımızda ele alıyoruz.
5. İlgili tüketim bilgisini toplayın
Teslimat durumunu ve kullanımı kendi sistemlerinizden okuyun. Tüketilebilir bir bakiye takip ediyorsanız rakam zaten mevcuttur. Bir kilit açma başarısız olduysa loglarınız bunu bilir.
6. Desteklenen yanıtı hazırlayın
Zorunlu alanları bir araya getirin, gerçek değerleriniz olan isteğe bağlı alanları ekleyin ve önce doğrulama kurallarını kontrol edin.
7. Apple'ın süresi içinde gönderin
Bildirimdeki orijinal işlem tanımlayıcısını kullanarak tüketim endpoint'ine bir PUT isteği gönderin.
8. Yanıtı kaydedin
Ne gönderdiğinizi, ne zaman gönderdiğinizi ve ne döndüğünü saklayın. Sonucu kaydetmediyseniz doğrulamadan geçemeyen bir gönderim, başarılı olanla aynı görünür.
9. Nihai iade sonucunu takip edin
Apple kararı ayrı bir bildirim olarak gönderir. Bunu ilgili işlem ve müşteriyle ilişkilendirerek kaydedin.
Geliştiricilerin yanıt vermek için ne kadar süresi var?
Apple'ın güncel dokümantasyonu, bildirimin alınmasından itibaren 12 saat içinde yanıt istiyor.
On iki saat, bildirimlerin ne zaman geldiğini düşünene kadar cömert görünür. İstekler gece, hafta sonları, tatillerde gelir ve saat durmaz. Cuma gecesi 23:00'te düşen bir isteğin süresi pazartesiden önce dolmuştur.
Apple, süreyi kaçırmanın otomatik olarak iadenin verileceği anlamına geldiğini söylemiyor ve bunu iddia etmek yanlış olur. Anlamı daha basit: Apple'ın dikkate almaya hazır olduğu bilgiyi sağlamadınız ve karar o bilgi olmadan veriliyor.
Geliştirici yanıt verdikten sonra ne olur?
Apple bilgiyi incelemesine dahil eder ve karar verir. Sonucu bir bildirim olarak görürsünüz: verildi, reddedildi ya da Apple daha önce onayladığı bir iadeyi geri alırsa sonradan tersine çevrildi.
Buradan sonrası sizin işiniz. Verilen bir iadede entitlement'ı iptal edin, tersine çevirmede geri yükleyin ve işlemin yalnızca bir kısmının geri döndüğü orantılı durumu ele alın.
Abonelik durumu da ilgi ister; çünkü iade edilen bir dönem genellikle aboneliği çalışır halde bırakmak yerine sonlandırır ve iadenin doğru döneme ait gelir kayıtlarına yansıması gerekir.
Ayrımı açıkça söylemekte fayda var: siz bilgi sağlarsınız, Apple karar verir ve sonra siz sistemlerinizi sonuçla senkronize tutarsınız. Üç ayrı sorumluluk ve yalnızca ortadaki Apple'a ait.
Manuel CONSUMPTION_REQUEST yönetimi neden zordur?
Bu iş akışındaki her kısıt, bunu elle yapan kişinin aleyhine çalışır.
Bildirimler günün her saati gelir. Süre 12 saattir. Her istek bir imza kontrolü, bir işlem araması, bir kullanıcı eşleştirmesi, bir onay kontrolü, bir kullanım hesabı, kimlik doğrulamalı bir API çağrısı ve loglanmış bir sonuç gerektirir. Hiçbiri zor değildir. Hepsi süreye bağlı ve tekrarlıdır; doğru gittiğinde de görünür hiçbir şey üretmez.
Ölçek işi daha da zorlaştırır: birden fazla uygulama, bir sistemde işlem verisi diğerinde kullanım verisi, giderek eksilen yanıt logları, işlem durumundan fark edilmeden uzaklaşan entitlement durumu. Bu, manuel yönetimin her zaman size paraya mal olduğu anlamına gelmez; ama risk gerçektir ve sessizce birikir.
Apple CONSUMPTION_REQUEST otomatikleştirilebilir mi?
Evet; iş akışının yapısı da bunu destekliyor, çünkü neredeyse her adım deterministik.
Otomasyon bildirimleri izleyip doğrulayabilir, özellikle tüketim isteklerini ayırt edebilir, işlemleri hesaplarla eşleştirebilir, yanıtı kayıtlarınızdan oluşturabilir, süreyi takip edebilir, gönderebilir, sonucu loglayabilir, kararı kaydedebilir ve entitlement güncellemelerini iletebilir.
Yapamayacağı şey Apple'ın kararını etkilemektir. Hiçbir araç bunu değiştirmez ve aksini ima eden her ürün süreci yanlış anlatıyordur. Otomasyonun değiştirdiği şey, sizin tarafınızın tutarlı biçimde ve süre içinde gerçekleşip gerçekleşmediğidir.
RefundSensor, geliştiricilerin Apple iade iş akışlarını yönetmesine nasıl yardımcı olur
App Store iade yönetimi, bu işin ait olduğu kategoridir. RefundSensor bunun geliştirici tarafını kapsar: Apple'ın iadeyle ilgili iş akışlarını izler, desteklenen CONSUMPTION_REQUEST yanıt akışını yönetir ve iade olaylarını ve sonuçlarını dashboard'lara ve tablolara dağılmak yerine tek bir yerde tutar.
Pratikte yanıtlar, birinin bildirimleri izlemesine gerek kalmadan süre içinde gider ve hacim büyüdükçe iade kayıtları doğru kalır. İadeleri durdurmaz ve Apple'dan belirli bir karar garanti edemez. Manuel izlemeyi ve atlanan adımları azaltır.
Bu Kurallar Nerede Belgelenmiş
Yukarıdaki her şey üç Apple kaynağına dayanıyor. Bunları doğrudan okuyun ve düzenli olarak yeniden kontrol edin — bu alan yakın zamanda değişti ve ikincil kaynaklar geride kalıyor.
Send Consumption Information — güncel endpoint. Onay gerekliliği, 12 saatlik süre, beş alanlık istek gövdesi ve kapsadığı ürün türleri. Standart In-App Purchase'lar için buna göre geliştirin.
Send Consumption Information V1 — on iki alanlık gövdeye sahip eski endpoint. Entegrasyonunuzun hangi sürümde olduğunu anlamak ve Advanced Commerce API kullanan ekipler için faydalı.
App Store Server Notifications — bildirimlerin backend'inize nasıl ulaştığı, imzalı payload formatı ve CONSUMPTION_REQUEST ile iade sonuçları dahil bildirim türleri.
Bu iş hâlâ elle yapılıyorsa
12 saatlik bir süre ve sabah 3'te gelen bildirimler, birinin dashboard'u kontrol etmesine bağlı bir süreçle kötü bir eşleşme.
Ekibiniz bu noktadaysa, RefundSensor bu iş akışlarının geliştirici tarafını üstlenir: bildirimleri izler, yanıtları süre içinde hazırlayıp gönderir ve sonuçları entitlement kayıtlarınıza kadar takip eder.
Sık sorulan sorular
Bir müşterinin iade talep ettiğini ve Apple'ın sizi o satın alma hakkında tüketim bilgisi göndermeye davet ettiğini sunucunuza bildiren bir App Store Server Notification'dır. Bir iade bildirimi değildir, bir karar da değildir. Apple kararı ayrıca verir ve yanıtınızı birçok faktörden biri olarak kullanır.
Çünkü Apple uygulamanızın içini göremez. İşlemi ve hesap geçmişini bilir; ancak içeriğin teslim edilip edilmediğini, çalışıp çalışmadığını ya da müşterinin ne kadar kullandığını bilemez. Bu bağlam sizin sistemlerinizde bulunur ve Apple incelemesini bitirmeden önce bunu sizden ister.
Müşteri iade talep eder, Apple incelemeye başlar ve yapılandırdığınız endpoint'e bir bildirim ulaşır. Bildirimi doğrular, işlemi tespit eder, onayı teyit eder, kullanım verisini toplar ve süre içinde tüketim bilgisini gönderirsiniz. Apple bunu değerlendirir, karar verir ve sonucu ayrı bir bildirim olarak gönderir.
Güncel endpoint'te beş alan. Üçü zorunlu: müşteri onayı, teslimat durumu ve örnek içerik sunulup sunulmadığı. İkisi isteğe bağlı: satın almanın ne kadarının tüketildiği ve tercih ettiğiniz iade sonucu. Eski V1 endpoint'i on iki alan istiyordu; eski makalelerin çok daha uzun bir liste anlatmasının nedeni bu.
Apple'ın güncel dokümantasyonu bu bildirimi tüm ürün türlerindeki iade talepleriyle ilişkili olarak tanımlıyor; bu, eski dokümantasyonun ima ettiğinden daha geniş bir kapsam. Ancak Apple her durum için bir garanti yayımlamıyor; bu yüzden her zaman bir istek geleceğine dayanan bir mantık yerine, istek geldiğinde yanıt veren bir handler kurun.
Apple'ın dokümantasyonu bildirimden itibaren 12 saat içinde yanıt istiyor. İstekler hafta sonları dahil günün her saati gelir; bu yüzden manuel bir sürecin en çok kaçırdığı adım budur. Eski bir entegrasyona güvenmek yerine güncel gerekliliği Apple'ın sayfasından kontrol edin.
Bilgilendirebilirsiniz, kontrol edemezsiniz. Doğru tüketim verisi Apple'a başka türlü sahip olamayacağı bağlamı sağlar ve güncel endpoint bir iade tercihi belirtmenize izin verir. Apple her ikisini diğer faktörlerle birlikte tartar ve farklı karar verebilir. Bir geliştiricinin iadeyi onaylayacağı ya da reddedeceği bir mekanizma yoktur.
Evet. Bildirimleri doğrulamak, işlemleri tespit etmek, onay durumunu kontrol etmek, kayıtlardan veri oluşturmak, süreye uymak, göndermek ve sonuçları loglamak tamamen deterministik adımlardır. İnsana kalan kısım, uygulamanızdaki onay akışını tasarlamak ve iade tercihi politikanızın ne olacağına karar vermektir.
