App Store Connect API ile App Store ekran görüntüsü yükleme
appScreenshotSet oluştur, bir appScreenshot rezerve et (Apple sana önceden imzalanmış parça URL'leri verir), byte'ları PUT ile gönder, ardından rezervasyonu uploaded: true ve dosyanın MD5'iyle PATCH et. Kimlik doğrulama, .p8 anahtarınla imzalanan 20 dakikalık bir JWT'dir. Hiçbiri zor değil; hepsi ayrıntılı ve uğraştırıcı. İşte gerçek sıra — ve bunu kendin kurmak istemezsen kısayolu.Apple'ın bu konudaki dokümantasyonu doğru ama neredeyse okunaksız — akış, tek bir örnek uygulama olmadan bir düzine referans sayfasına dağılmış durumda. Bu yazı, doğru sırada, tam uç noktalar ve alan adlarıyla adım adım anlatılan tek rehberdir. Entegrasyonu kendisi mi kuracak yoksa bunu zaten yapan bir araca mı geçecek konusunda karar vermeye çalışan biri için yazıldı.
Yüklediğin nesne modeli
Ekran görüntüleri uygulamana doğrudan bağlanmaz. Bir nesne zincirine asılırlar ve zinciri yukarıdan aşağı takip etmen gerekir:
- appStoreVersion — düzenlediğin belirli sürüm (düzenlenebilir durumda olmalı).
- appStoreVersionLocalization — her App Store diline (en-US, de-DE, ja vb.) bir tane.
- appScreenshotSet — bir yerelleştirme içinde her ekran türü için bir tane (6,7" iPhone, 13" iPad vb.).
- appScreenshot — tek tek görsel, set başına 10 adede kadar.
Yani iki iPhone boyutu ve bir iPad boyutu için 50 dilde tam yerelleştirilmiş bir listeleme, her biri 10 ekran görüntüsüne kadar tutan 50 × 3 set demektir. İnsanların bunu web arayüzünde tıklamak yerine otomatikleştirmesinin tüm sebebi bu çarpım.
Adım 0 — 20 dakikalık JWT
Byte yüklemelerinin dışındaki her istek, kendi imzaladığın bir JSON Web Token taşıyan bir Authorization: Bearer başlığına ihtiyaç duyar. App Store Connect'ten üç şeye ihtiyacın var: issuer ID'n, bir key ID ve anahtarı oluşturduğunda bir kez indirdiğin .p8 özel anahtar dosyası (Apple bunu bir daha göstermez).
Token, o .p8 anahtarı kullanılarak ES256 ile imzalanır — P-256 eğrisinde ECDSA ve SHA-256. Başlık kid'i taşır; gövde ise issuer'ı iss olarak, hedef kitleyi tam olarak appstoreconnect-v1 dizesi olarak ve iat'tan en fazla 20 dakika sonrasına ait bir exp'i taşır. Apple daha uzun ömürlü olan her şeyi reddeder, bu yüzden sık sık yeniden üretirsin — tek bir tokeni açık tutmaya çalışmak yerine her yığın için yeni bir token üret.
Bunu ES256 destekleyen herhangi bir JWT kütüphanesiyle (jsonwebtoken, PyJWT, yığınına göre ne kullanıyorsan) imzala, .p8 içeriğini anahtar olarak ver ve sonucu aşağıdaki her çağrıda Authorization başlığına koy.
Adım 1 — ekran görüntüsü setini oluştur
Bir set, tek bir yerelleştirme ve tek bir ekran türüyle sınırlıdır. Özniteliklerde screenshotDisplayType ile ve doldurmak istediğin appStoreVersionLocalization'a işaret eden bir ilişkiyle /v1/appScreenshotSets'e POST atarsın.
Yaygın ekran türleri: APP_IPHONE_67 (6,7", 1290 × 2796), mevcut büyük iPhone boyutu ve APP_IPAD_PRO_3GEN_129 (12,9", 2048 × 2732). Apple'ın artık yaptığı yararlı bir şey: en büyük iPhone boyutundaki ekran görüntüleri daha küçük iPhone sınıflarında, en büyük iPad boyutundakiler ise daha küçük iPad'lerde yeniden kullanılıyor — yani pratikte genellikle dil başına fiziksel cihaz başına değil, bir iPhone seti ve bir iPad seti yeterli oluyor. Yanıt sana bir sonraki çağrıya taşıyacağın bir set id'si verir. O dil/tür için zaten bir set varsa, yeni bir tane oluşturmak yerine onu yeniden kullan.
Adım 2 — ekran görüntüsünü rezerve et
Dosyayı tek seferde yüklemezsin. Önce onu rezerve edersin: Apple'a dosya adını ve tam byte boyutunu söylersin, o da sana bir yükleme planı verir. fileName ve fileSize öznitelikleriyle ve 1. adımdaki sete bir ilişkiyle /v1/appScreenshots'e POST at.
Yanıtın ilgi çekici kısmı burası. Yeni ekran görüntüsünün özniteliklerinin içinde, byte'ları tam olarak nasıl göndereceğini açıklayan bir dizi olan uploadOperations'ı alırsın. Küçük bir dosya için tek bir işlemdir; büyük bir dosya için Apple bunu birkaç parçaya böler. Her giriş sana bir method (PUT), önceden imzalanmış bir url, gönderilecek byte offset ve length'ini ve eklenecek requestHeaders'ı verir.
Adım 3 — byte'ları PUT et
Her işlem için, dosyandan offset'ten başlayarak length byte'lık dilimi oku ve Apple'ın sağladığı requestHeaders'la birlikte verilen url'ye PUT ile gönder. Bu URL'ler önceden imzalanmıştır, bu yüzden buraya JWT'ni göndermezsin — Authorization başlığı eklemek imzalı isteği bozabilir. Birden fazla işlem paralel çalışabilir ama Apple agresif yüklemeleri hız sınırlar, bu yüzden hepsini birden ateşlemek yerine yeniden-deneme-ve-geri-çekilme mantığına sar.
Adım 4 — uploaded: true ve MD5 ile onayla
Byte'ları yüklemek, Apple'a rezervasyonun tamamlandığını söyleyene kadar hiçbir şey yapmaz. Ekran görüntüsünü uploaded: true ve tüm dosyanın küçük harfli hex dizesi olarak MD5'i olan bir sourceFileChecksum ile geri PATCH et. Bu, Apple'ın bütünlük kontrolüdür: sağlama toplamı ulaşanla eşleşmezse işleme başarısız olur.
PATCH'ten sonra varlık Apple tarafında işlenmeye başlar. Ekran görüntüsünün assetDeliveryState'ini tamamlanmış bir duruma ulaşana kadar sorgula — ve başarısız olursa errors'ını oku, çünkü yanlış boyut ve alfa kanalı sorunları orada ortaya çıkar. PUT ve PATCH'in ikisi de başarılı olabilir ve ekran görüntüsü işleme sırasında dakikalar sonra yine de reddedilebilir. Onaydaki 2xx yanıtın işinin bittiği anlamına geldiğini varsayma; teslimat durumunu izle.
Adım 5 — görüntülenme sırasını ayarla
Ekran görüntüleri oluşturuldukları sırayla döner, ki bu nadiren istediğin gösterim sırasıdır. Setin sırası ayrı bir ilişkidir. Ekran görüntüsü ID'lerinin bir dizisiyle /v1/appScreenshotSets/{id}/relationships/appScreenshots'i PATCH et — dizideki sıra, mağazadaki görüntülenme sırasının ta kendisidir.
Apple'ın gerçekten uyguladığı kısıtlamalar
- Sadece PNG veya JPEG. HEIC yok, WebP yok. Renderer'ın başka bir şey üretiyorsa önce dönüştür.
- Alfa kanalı yok. Şeffaflığı düz bir arka plana düzleştir ve RGB olarak dışa aktar. Kaçak bir alfa kanalı, işleme sırasında en yaygın sessiz reddedilme nedenlerinden biridir.
- Ekran türü başına tam boyutlar. Görsel, ekran türünün piksel boyutuyla tam olarak eşleşmelidir — birkaç piksel fark yok, büyütme yok. 1290 × 2796 boyutlu bir dosya sadece
APP_IPHONE_67setine gider, başka hiçbir yere değil. - Set başına 10 adede kadar. Yerelleştirme ve ekran türü başına en fazla on ekran görüntüsü.
- Sadece düzenlenebilir sürüm. Yalnızca düzenlenebilir durumdaki bir sürümde setleri değiştirebilirsin; incelemede olan bir sürüm kilitlidir.
Bunun neden göründüğünden daha fazla iş olduğu
Her tek çağrı basit. Maliyet, etraflarındaki her şeyde: 20 dakikalık bir tokeni imzalamak ve döndürmek, MD5'leri hesaplamak, uploadOperations'a uyacak şekilde dosyaları dilimlemek, kısmi yükleme yeniden denemelerini yönetmek, teslimat durumunu sorgulamak, dillerini Apple'ın dil kodlarına eşlemek ve düzgün yerelleştirilmiş bir listeleme için bunların hepsini 150'den fazla kez yapmak. Bunu güvenilir hale getirmek bir hafta sonu kimlik doğrulama, parçalı yükleme ve hata yönetimi ister — ve sonra Apple her yeni ekran türü eklediğinde onun bakımını yapmak sana kalır.
Sırayı kendin yazmak istemiyorsan, Fastlane'in deliver aynı API'yi sarar ve standart açık kaynak yoldur. Yüklemeyi çözer; ekran görüntülerini tasarlamaz veya metinlerini yazmaz.
…ya da tamamını atla
API sadece bitmiş görselleri taşır. Yine de birinin karuseli tasarlaması, metinlerini yazması ve her dile çevirmesi gerekir — asıl zaman alan kısım bu. Mokbi bunu bugün yapıyor: ekran görüntülerini tasarlıyor, listeleme metnini hazırlıyor ve tamamını 50 dile çeviriyor, ardından her görseli bu API'nin talep ettiği tam ekran-türü-başına boyutlarda dışa aktarıyor — PNG, RGB, alfasız, doğru boyut — böylece bir yükleme teslimat durumu adımında geri sekmez.
Sonra yayınlıyor. App Store için Mokbi, tam olarak bu rezerve-et-ve-onayla dizisini arka planda çalıştırır — ekran görüntülerini ve meta verilerini yükler ve sürümü göndermeye hazır şekilde bekletir, böylece hiçbir zaman bir JWT'ye veya parçalı PUT'a dokunmazsın. Apple yine de son Gönder adımını ve incelemesini gerektirir; ona kadar olan her şey senin için halledilir. Google Play için doğrudan mağazaya iter. Her iki durumda da tasarım, metin ve 50 dilde çeviri zaten yapılmış olarak, kodu yazmadan API sonucunu alırsın.