App Store Review API – Entwicklerleitfaden

Die App Store Review API ermöglicht es Drittanbieter-App-Shops, die über das Programm „Drittanbieter-App-Shops bei Google Play“ bei Google Play registriert sind, die erforderlichen Details für Apps bereitzustellen, die in ihrem Shop gehostet werden. Dazu gehören App-Metadaten, Einträge, APK-Binärdateien und Erklärungen zur Richtlinienkonformität.

Eine vollständige Liste der Endpunkte, Methoden und Ressourcenschemas finden Sie in der App Store Review API Reference.

Vorbereitung

Sie müssen die Kurzanleitung durcharbeiten, um API-Zugriff, Dienstanmeldedaten und Ihr Google Cloud-Projekt einzurichten, bevor Sie Aufrufe an die App Store Review API senden können. Die App Store Review API erwartet maximal 300 Anfragen pro Minute und App-Shop.

API-Design und ‑Architektur

Die App Store Review API basiert auf einem atomaren Snapshot-Muster. Anstatt transaktionale Sitzungen zu verwenden, laden Sie Dateien einzeln hoch und übertragen dann den vollständigen Status in einem einzigen atomaren Aufruf:

  1. Sie laden einzelne Dateien und Assets (APKs, Bilder und Richtliniendateien) in separaten, direkten Aufrufen hoch.
  2. Sie speichern die zurückgegebenen IDs für diese Dateien im Cache.
  3. Sie senden eine einzelne, endgültige UpdateAppStoreHostedApp-Anfrage, um den gesamten gehosteten App-Status atomar zu übertragen.

1. Anmeldung

Rufen Sie zum Registrieren einer gehosteten App die Methode createappstorehostedapp auf und geben Sie den Paketnamen der App und den Paketnamen Ihres Shops an. Details zu den Anfrage- und Antwortschemata finden Sie in der API-Referenz.

2. Binär- und Asset-Uploads

Nachdem die gehostete App registriert wurde, müssen Sie ihre Assets über die speziellen Upload-Endpunkte hochladen:

Asset-Caching und ‑Wiederverwendung

Um Bandbreite und Leistung zu optimieren, sollten Sie identische Assets nicht noch einmal hochladen. Alle zurückgegebenen apkId-, imageId- und fileId-Tokens sind dauerhaft. Sie können diese IDs in Ihrer eigenen Backend-Datenbank zwischenspeichern und bei nachfolgenden Updates der gehosteten App wiederverwenden. Wenn Sie beispielsweise die Beschreibung einer gehosteten App aktualisieren, das App-Symbol und die Screenshots aber unverändert bleiben, verwenden Sie die im Cache gespeicherten imageId-Tokens in Ihrem nächsten Update-Aufruf.

3. Zusammenstellen und übertragen

Nachdem Sie alle Assets erfolgreich hochgeladen und die entsprechenden IDs abgerufen haben, müssen Sie den vollständigen gehosteten App-Status zusammenstellen und mit der Methode updateappstorehostedapp übertragen. Diese Methode akzeptiert eine vollständige, atomare Darstellung der Details der gehosteten App, der lokalisierten Store-Einträge, der aktiven APK-Sets und der Sicherheitserklärungen.

Mit diesem Aufruf wird jeder zuvor aktive Status durch den im Antrag beschriebenen neuen Status ersetzt.

Beispiel für einen Anfragetext

Das Folgende ist ein realistischer und syntaktisch gültiger JSON-Anfragetext, der alle wichtigen Elemente enthält:

{
  "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
  ]
}

Richtlinienerklärungen

Wenn Sie App-Informationen über die API einreichen oder aktualisieren, müssen Sie alle erforderlichen Richtlinienerklärungen angeben.

Erklärungsanforderungen

Die folgenden Erklärungen sind betroffen:

Für alle Apps erforderlich, um zu bestätigen, ob zusätzliche Erklärungen erforderlich sind:

  1. Gesundheits-Apps:Teilen Sie uns mit, welche Gesundheitsfunktionen die App verwendet, damit wir wissen, welche Anforderungen sie gemäß der Richtlinie für Gesundheits-Apps erfüllen muss.
  2. Finanzfunktionen:Apps, die Finanzfunktionen bereitstellen, müssen eventuell in einigen Ländern oder Regionen bestimmte Vorschriften einhalten. Reiche korrekte und aktuelle Details zu den Finanzfunktionen in der App ein, damit wir deine Einreichung zur Überprüfung an die richtigen Teams weiterleiten können.
  3. Werbe-ID:Teilen Sie uns mit, ob die App eine Werbe-ID verwendet.
  4. Test-Anmeldedaten (Anmeldedetails): Wenn Teile der App nur standortabhängig, mit Anmeldedetails, einer Mitgliedschaft oder anderen Authentifizierungsmethoden zugänglich sind, informiere uns bitte, wie wir auf die App zugreifen können.
  5. Datenschutzerklärung:Ein Link zur Datenschutzerklärung der App und Details dazu.
  6. Zielgruppe und Inhalte:Sie müssen uns die Zielaltersgruppe der App und andere Informationen zum Inhalt mitteilen. So können wir besser dafür sorgen, dass Apps, die für Kinder gedacht sind, sicher und für sie geeignet sind.
  7. Werbung:Sie müssen uns mitteilen, ob die App Werbung enthält.

Bedingt erforderlich:

  1. Behörden-Apps:Teilen Sie uns mit, ob die App für die Nutzung durch Behörden jeglicher Art vorgesehen ist. Gemeint sind Behörden auf Bundes-, Landes- und kommunaler Ebene sowie lokale Behörden. Diese Angabe sorgt dafür, dass die Einreichung von den richtigen Teams geprüft wird. Wenn diese Erklärung nicht ausgefüllt wird, gilt die App nicht als Behörden-App.
  2. Sicherheitsstandards zum Schutz von Kindern:Erforderlich für Apps in den Kategorien „Soziale Netzwerke“ oder „Dating“. Apps in den Kategorien „Soziale Netzwerke“ oder „Dating“ müssen veröffentlichte Sicherheitsstandards und Kontaktdaten angeben, um unserer Richtlinie zu den Sicherheitsstandards zum Schutz von Kindern zu entsprechen.
  3. Nachrichten- und Zeitschriften-Apps:Erforderlich für Apps in der Kategorie „Nachrichten & Zeitschriften“. Fügen Sie Details zur Nachrichten- und Zeitschriften-App hinzu, damit transparent dargelegt werden kann, welche Rechtssubjekte hinter der App stehen.

Struktur von API-Anfragen

Richtlinienerklärungen werden im Array policyDeclarations im Hauptteil der UpdateAppStoreHostedAppRequest bereitgestellt. Jedes Element in diesem Array ist ein AppStoreAppPolicyDeclaration-Objekt.

AppStoreAppPolicyDeclaration Objekt:

  • declarationId (String, erforderlich): Die eindeutige Kennung für die Richtlinienerklärung (z.B. POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (Array von PolicyResponse, erforderlich): Eine Liste mit Antworten auf die Fragen in dieser spezifischen Erklärung.

PolicyResponse Objekt:

  • questionId (String, erforderlich): Die eindeutige Kennung für die spezifische Frage, die beantwortet wird (z.B. POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (erforderlich): Die Antwort selbst, die einen der folgenden Typen haben kann:
    • booleanResponse: Für Ja- oder Nein-Fragen.
      • value (boolesch)
    • stringResponse: Für Antworten im Nur-Text-Format, einschließlich URLs.
      • value (string)
    • singleChoiceResponse: Wenn nur eine Option aus einer Liste ausgewählt werden kann.
      • value (String): Die ID der ausgewählten Antwort.
    • multipleChoiceResponse: Wenn mehrere Optionen ausgewählt werden können.
      • values (Array mit String): Die IDs der ausgewählten Antwortmöglichkeiten.
    • documentResponse: Für Fragen, für die ein Dokument hochgeladen werden muss. Weitere Informationen finden Sie unter Dokument-Uploads verarbeiten.
    • groupResponse: Für sich wiederholende Gruppen verschachtelter Fragen.
    • keyedGroupResponse: Für Gruppen von verschachtelten Fragen, die nach einem bestimmten Schlüssel gruppiert sind.

Beispiel-Snippets für die Deklaration finden Sie im ausführlichen Leitfaden.

Dokument-Uploads verarbeiten

Bei einigen Richtlinienfragen müssen Sie Belege einreichen, z.B. Lizenzen für Finanzfunktionen. Dokumente können nicht direkt in die UpdateAppStoreHostedAppRequest eingebettet werden. Stattdessen müssen Sie Folgendes tun:

  1. Dokument hochladen:Verwenden Sie den Endpunkt UploadAppStoreAppPolicyDeclarationFile. Dies ist eine Anfrage zum Hochladen von Medien. fileType sollte auf DECLARATION_FILE_TYPE_DOCUMENT gesetzt sein.

    • Endpunkt:POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • Antworten auf erfolgreiche Uploads enthalten ein fileId.

  2. Dokument-ID referenzieren:Verwenden Sie in der PolicyResponse für das betreffende Dokument den Typ documentResponse. Füllen Sie das Feld documentId mit dem fileId aus, das Sie beim Hochladen erhalten haben.

PolicyDocumentResponse Objekt:

  • documentId (String, erforderlich): Die ID, die vom Endpunkt UploadAppStoreAppPolicyDeclarationFile zurückgegeben wird.
  • expiryDate (Datum, optional): Das Ablaufdatum des Dokuments, falls zutreffend.
  • nonExpiring (boolesch, optional): Auf true setzen, wenn das Dokument nicht abläuft.

Beispiel für eine Dokumentantwort:

// 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. Verfügbarkeit steuern

Sobald Sie den Status der gehosteten App mit UpdateAppStoreHostedApp übertragen haben, wird die App automatisch verarbeitet und standardmäßig in Google Play für den App-Shop des Drittanbieters als veröffentlicht markiert.

Wenn Sie die Verfügbarkeit der App nach der Übertragung steuern möchten, rufen Sie die Methode updateappstorehostedapppublishstatus auf, um den Status zu aktualisieren:

  • Veröffentlichung einer App aufheben: Wenn Sie die gehostete App nicht mehr verfügbar machen möchten, setzen Sie das Feld publishState auf APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • App neu veröffentlichen: Wenn Sie eine zuvor nicht veröffentlichte App wieder verfügbar machen möchten, ohne Einträge zu ändern oder Assets neu hochzuladen, setzen Sie das Feld publishState auf APP_STORE_APP_PUBLISH_STATE_PUBLISHED.