App Store Review API Geliştirici Kılavuzu

App Store Review API, Play'deki üçüncü taraf uygulama mağazası programı aracılığıyla Google Play'e kaydedilen üçüncü taraf uygulama mağazalarının, mağazalarında barındırılan uygulamalar için gerekli ayrıntıları sağlamasına olanak tanır. Uygulama meta verileri, listelemeler, APK ikilileri ve politika uygunluğu beyanları buna dahildir.

Uç noktaların, yöntemlerin ve kaynak şemalarının tam listesi için App Store Review API Referansı'na bakın.

Başlamadan Önce

App Store Review API'ye çağrı yapabilmeniz için API erişiminizi, hizmet kimlik bilgilerinizi ve Google Cloud projenizi ayarlamak üzere ana Başlangıç Kılavuzu'nu tamamlamanız gerekir. App Store Review API, uygulama mağazası başına dakikada en fazla 300 istek bekler.

API Tasarımı ve Mimarisi

App Store Review API, atomik anlık görüntü düzeninde çalışır. İşlem oturumlarını kullanmak yerine, dosyaları tek tek yükleyip tam durumu tek bir atomik çağrıyla kaydedersiniz:

  1. Ayrı ve doğrudan çağrılarla ayrı dosyalar ve öğeler (APK'lar, resimler ve politika dosyaları) yüklersiniz.
  2. Döndürülen kimlikleri bu dosyalar için önbelleğe alırsınız.
  3. Barındırılan uygulamanın tüm durumunu atomik olarak işlemek için tek bir nihai UpdateAppStoreHostedApp isteği gönderirsiniz.

1. Kayıt

Barındırılan bir uygulamayı kaydetmek için createappstorehostedapp yöntemini çağırın, uygulamanın paket adını ve mağazanızın paket adını belirtin. İstek ve yanıt şemalarıyla ilgili ayrıntılar için API referansına bakın.

2. İkili ve öğe yüklemeleri

Barındırılan uygulama kaydedildikten sonra, öğelerini aşağıdaki özel yükleme uç noktalarını kullanarak yüklemeniz gerekir:

  • APK'lar: Uygulamanın etkin olarak dağıtılan tüm APK ikilileri (uploadapk kullanılarak).
  • Resimler: Uygulama simgesi ve ekran görüntüleri gibi resim öğeleri (uploadimage kullanılarak).
  • Politikalar: (İlgiliyse) Politika ile ilgili belgeler (uploadappstoreapppolicydeclarationfile kullanılarak).

Öğeleri Önbelleğe Alma ve Yeniden Kullanma

Bant genişliğini ve performansı optimize etmek için aynı öğeleri yeniden yüklemeyin. Döndürülen tüm apkId, imageId ve fileId jetonları kalıcıdır. Bu kimlikleri kendi arka uç veritabanınızda önbelleğe alabilir ve sonraki barındırılan uygulama güncellemelerinde yeniden kullanabilirsiniz. Örneğin, barındırılan bir uygulamanın açıklamasını güncelliyorsanız ancak uygulama simgesi ve ekran görüntüleri değişmeden kalıyorsa bir sonraki güncelleme çağrınızda önbelleğe alınmış imageId jetonlarını kullanın.

3. Derleme ve gönderme

Tüm öğeleri başarıyla yükleyip ilgili kimliklerini aldıktan sonra, tam olarak barındırılan uygulama durumunu oluşturmanız ve updateappstorehostedapp yöntemini kullanarak bunu işlemeniz gerekir. Bu yöntem, barındırılan uygulamanın ayrıntılarının, yerelleştirilmiş mağaza listelemelerinin, etkin APK kümelerinin ve güvenlik beyanlarının eksiksiz ve atomik bir gösterimini kabul eder.

Bu çağrı, daha önce etkin olan tüm durumların yerine istekte açıklanan yeni durumu kullanır.

İstek Metni Örneği

Aşağıda, tüm temel öğeleri gösteren gerçekçi ve söz dizimi açısından geçerli bir JSON istek gövdesi örneği verilmiştir:

{
  "appStorePackageName": "com.example.thirdparty.store",
  "packageName": "com.example.hostedapp.game",
  "appDetails": {
    "developerName": "Adventure Games Studio Ltd.",
    "contactEmail": "support@adventuregames.example.com",
    "developerWebsite": "https://adventuregames.example.com"
  },
  "activeLocalizedStoreListings": [
    {
      "languageCode": "en-US",
      "appName": "Super Quest Legends",
      "shortDescription": "An epic fantasy RPG adventure.",
      "fullDescription": "Super Quest Legends is an immersive action RPG featuring real-time battles, customizable classes, and a deep fantasy narrative. Journey through a magical realm, fight epic bosses, and team up with friends in dungeon raids.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ],
      "videoLink": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    },
    {
      "languageCode": "es-ES",
      "appName": "Super Quest Leyendas",
      "shortDescription": "Una aventura épica de RPG fantástico.",
      "fullDescription": "Super Quest Leyendas es un RPG de acción inmersivo con batallas en tiempo real, clases personalizables y una profunda narrativa de fantasía. Viaja a través de un reino mágico, lucha contra jefes épicos y únete a amigos en incursiones.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ]
    }
  ],
  "activeApks": {
    "activeApkSets": [
      {
        "baseApkId": "554433"
      },
      {
        "baseApkId": "990011"
      }
    ]
  },
  "policyDeclarations": [
    {
      "declarationId": "POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS",
          "multipleChoiceResponse": {
            "values": [
              "POLICY_RESPONSE_CHOICE_ID_TAC_AGE_EIGHTEEN_AND_ABOVE"
            ]
          }
        },
        // ... other responses for TAC
      ]
    },
    {
      "declarationId": "POLICY_DECLARATION_ID_ADVERTISING_ID",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_AD_ID_IS_USED",
          "booleanResponse": {
            "value": false
          }
        }
        // ... other responses for AD_ID
      ]
    }
    // ... other declarations
  ]
}

Politika Beyanları

API'yi kullanarak uygulama bilgileri gönderirken veya güncellerken gerekli politika beyanlarını eklemeniz gerekir.

Beyan Şartları

Aşağıdaki beyanlar kapsam dahilindedir:

Ek beyan gerekip gerekmediğini onaylamak için tüm uygulamaların yapması gerekenler:

  1. Sağlık Uygulamaları: Uygulamanın kullandığı sağlık özelliklerini bize bildirin. Bu sayede, uygulamanın Sağlık Uygulamaları Politikası'nda karşılaması gereken şartları anlayabiliriz.
  2. Finansal Özellikler: Finans ile ilgili özellikler sunan uygulamaların bazı ülkelerdeki veya bölgelerdeki belirli düzenlemelere uyması gerekebilir. Gönderiminizin doğru ekipler tarafından incelenmesi için uygulamadaki finans ile ilgili özelliklerin doğru ve güncel ayrıntılarını gönderin.
  3. Reklam kimliği: Uygulamanın reklam kimliği kullanıp kullanmadığını anlamamıza yardımcı olun.
  4. Test Kimlik Bilgileri (Oturum Açma Bilgileri): Uygulamanın herhangi bir bölümüne erişim; oturum açma bilgileri, üyelik, konum veya diğer kimlik doğrulama yöntemleriyle kısıtlanmışsa bu bölümlere nasıl erişileceğine dair talimatlar sağlayın.
  5. Gizlilik Politikası: Uygulamanın gizlilik politikasıyla ilgili bağlantı ve ayrıntılar.
  6. Hedef Kitle ve İçerik: Uygulamanın hedef yaş grubunu ve içeriğiyle ilgili diğer bilgileri bize bildirmeniz gerekir. Bu bilgiler, çocuklar için tasarlanan uygulamaların güvenli ve uygun olmasını sağlamaya yardımcı olur.
  7. Reklamlar: Uygulamanın reklam içerip içermediğini bize bildirmeniz gerekir.

Koşullu olarak zorunlu:

  1. Resmi Kurum Uygulamaları: Uygulamanın herhangi bir resmi kurum tarafından kullanılıp kullanılmadığını bize bildirin. Ulusal yönetimler, eyalet ve şehir yönetimleri ile yerel yetkililer de devlet kurumudur. Bu şekilde, gönderiminizin doğru ekipler tarafından incelenmesini sağlayabiliriz. Bu beyan doldurulmazsa uygulama, kamu kuruluşlarına ait uygulama olarak kabul edilmez.
  2. Çocuk Güvenliği Standartları: "Sosyal" veya "Arkadaşlık" kategorilerindeki uygulamalar için zorunludur. Sosyal veya arkadaşlık kategorilerindeki uygulamaların Çocuk Güvenliği Standartları Politikamıza uyması için, yayınlanmış güvenlik standartlarını ve iletişim bilgilerini paylaşması gerekir.
  3. Haber ve Dergi Uygulamaları: "Haberler ve Dergiler" kategorisindeki uygulamalar için gereklidir. Uygulamanın arkasındaki tüzel kişilerle ilgili şeffaf bir yaklaşım sergilemek için haber ve dergi uygulaması hakkında ayrıntılı bilgi ekleyin.

API İsteği Yapısı

Politika beyanları, UpdateAppStoreHostedAppRequest gövdesindeki policyDeclarations dizisinde sağlanır. Bu dizideki her öğe bir AppStoreAppPolicyDeclaration nesnesidir.

AppStoreAppPolicyDeclaration Nesne:

  • declarationId (dize, zorunlu): Politika beyanının benzersiz tanımlayıcısı (ör. POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (PolicyResponse dizisi, zorunlu): Söz konusu beyandaki soruların yanıtlarının listesi.

PolicyResponse Nesne:

  • questionId (dize, zorunlu): Yanıtlanan sorunun benzersiz tanımlayıcısı (ör. POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (Zorunlu): Aşağıdaki türlerden biri olabilen yanıtın kendisi:
    • booleanResponse: Evet veya Hayır soruları için.
      • value (boolean)
    • stringResponse: URL'ler de dahil olmak üzere düz metin yanıtlar için.
      • value (dize)
    • singleChoiceResponse: Bir listeden yalnızca bir seçenek belirlenebildiğinde.
      • value (dize): Seçilen yanıt seçeneğinin kimliği.
    • multipleChoiceResponse: Birden fazla seçeneğin belirlenebildiği durumlarda.
      • values (Dize dizisi): Seçilen yanıt seçeneklerinin kimlikleri.
    • documentResponse: Belge yüklenmesini gerektiren sorular için. Belge Yüklemelerini İşleme başlıklı makaleyi inceleyin.
    • groupResponse: İç içe yerleştirilmiş soruların tekrar eden grupları için.
    • keyedGroupResponse: Belirli bir anahtara göre gruplandırılmış iç içe yerleştirilmiş soru kümeleri için.

Bildirimle ilgili örnek snippet'ler için ayrıntılı kılavuza bakın.

Belge Yüklemelerini İşleme

Bazı politika soruları için destekleyici belgeler (ör. finansal özellikler için lisanslar) sağlamanız gerekir. Belgeler doğrudan UpdateAppStoreHostedAppRequest'ye yerleştirilemez. Bunun yerine şunları yapmanız gerekir:

  1. Belgeyi Yükleme: UploadAppStoreAppPolicyDeclarationFile uç noktasını kullanın. Bu bir medya yükleme isteğidir. fileType, DECLARATION_FILE_TYPE_DOCUMENT olarak ayarlanmalıdır.

    • Uç nokta: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • Başarılı yükleme yanıtları fileId içerir.

  2. Belge kimliğine referans verme: Belge sorusu için PolicyResponse bölümünde documentResponse türünü kullanın. documentId alanını, yükleme adımında elde edilen fileId ile doldurun.

PolicyDocumentResponse Nesne:

  • documentId (dize, zorunlu): UploadAppStoreAppPolicyDeclarationFile uç noktasından döndürülen kimlik.
  • expiryDate (Tarih, isteğe bağlı): Geçerliyse belgenin geçerlilik bitiş tarihi.
  • nonExpiring (boolean, İsteğe bağlı): Belge geçerliliğini yitirmiyorsa true olarak ayarlayın.

Belge Yanıtı örneği:

// Inside a PolicyResponse object
{
  "questionId": "POLICY_QUESTION_ID_FINANCE_CRYPTO_US_FINCEN_LICENSE", // Example ID
  "documentResponse": {
    "documentId": "123456789", // The fileId from upload
    "expiryDate": {
      "year": 2027,
      "month": 6,
      "day": 1
    }
  }
}

4. Kullanılabilirliği kontrol etme

Barındırılan uygulama durumunu UpdateAppStoreHostedApp kullanarak onayladığınızda uygulama otomatik olarak işlenir ve Google Play'de üçüncü taraf uygulama mağazası için varsayılan olarak yayınlandı şeklinde işaretlenir.

Uygulama kaydedildikten sonra kullanılabilirliğini kontrol etmek için durumunu güncellemek üzere updateappstorehostedapppublishstatus yöntemini çağırın:

  • Uygulamayı yayından kaldırma: Barındırılan uygulamayı kullanılamaz hale getirmek için publishState alanını APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED olarak ayarlayın.
  • Uygulamayı yeniden yayınlama: Daha önce yayınlanmamış bir uygulamayı girişleri değiştirmeden veya öğeleri yeniden yüklemeden tekrar kullanılabilir hale getirmek için publishState alanını APP_STORE_APP_PUBLISH_STATE_PUBLISHED olarak ayarlayın.