Guida per sviluppatori dell'API App Store Review

L'API App Store Review consente agli store di terze parti registrati su Google Play tramite il programma Store di terze parti su Play di fornire i dettagli richiesti per le app ospitate nel loro store. Sono inclusi metadati dell'app, schede, file binari APK e dichiarazioni di conformità alle norme.

Per un elenco completo di endpoint, metodi e schemi delle risorse, consulta il Riferimento API App Store Review.

Prima di iniziare

Prima di poter effettuare chiamate all'API App Store Review, devi completare la Guida introduttiva principale per configurare l'accesso all'API, le credenziali di servizio e il progetto Google Cloud. L'API App Store Review prevede al massimo 300 richieste al minuto per app store.

Progettazione e architettura delle API

L'API App Store Review funziona con un pattern di snapshot atomico. Anziché utilizzare sessioni transazionali, carichi i file singolarmente e poi esegui il commit dello stato completo in una singola chiamata atomica:

  1. Carichi singoli file e asset (APK, immagini e file dei criteri) in chiamate dirette separate.
  2. Memorizzi nella cache gli ID restituiti per questi file.
  3. Invii una singola richiesta UpdateAppStoreHostedApp finale per eseguire il commit dell'intero stato dell'app ospitata in modo atomico.

1. Registrazione

Per registrare un'app ospitata, chiama il metodo createappstorehostedapp, specificando il nome del pacchetto dell'app e il nome del pacchetto del tuo store. Per informazioni dettagliate sugli schemi di richiesta e risposta, consulta il Riferimento API.

2. Caricamenti di file binari e asset

Una volta registrata l'app ospitata, devi caricare i relativi asset utilizzando gli endpoint di caricamento specializzati:

Memorizzazione nella cache e riutilizzo degli asset

Per ottimizzare la larghezza di banda e il rendimento, non caricare di nuovo asset identici. Tutti i token apkId, imageId e fileId restituiti sono persistenti. Puoi memorizzare nella cache questi ID nel tuo database di backend e riutilizzarli negli aggiornamenti successivi delle app ospitate. Ad esempio, se stai aggiornando la descrizione di un'app ospitata, ma l'icona e gli screenshot dell'app rimangono invariati, utilizza i token imageId memorizzati nella cache nella chiamata di aggiornamento successiva.

3. Assembla e invia

Dopo aver caricato correttamente tutti gli asset e recuperato i rispettivi ID, devi assemblare lo stato completo dell'app ospitata e eseguirne il commit utilizzando il metodo updateappstorehostedapp. Questo metodo accetta una rappresentazione completa e atomica dei dettagli dell'app ospitata, delle schede dello store localizzate, dei set di APK attivi e delle dichiarazioni di sicurezza.

Questa chiamata sostituisce qualsiasi stato attivo precedente con il nuovo stato descritto nella richiesta.

Esempio di corpo della richiesta

Di seguito è riportato un corpo della richiesta JSON realistico e valido dal punto di vista sintattico che illustra tutti gli elementi chiave:

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

Dichiarazioni relative alle norme

Quando invii o aggiorni le informazioni sull'app utilizzando l'API, devi includere tutte le dichiarazioni richieste dalle norme.

Requisiti della dichiarazione

Rientrano nell'ambito di applicazione le seguenti dichiarazioni:

Obbligatorio per tutte le app per confermare se sono necessarie dichiarazioni aggiuntive:

  1. App per la salute:comunicaci le funzionalità per la salute utilizzate dall'app per aiutarci a capire quali requisiti previsti dalle norme relative alle app per la salute deve soddisfare.
  2. Funzionalità finanziarie:le app che offrono funzionalità finanziarie potrebbero dover essere conformi a determinate normative in alcuni paesi o regioni. Invia dettagli precisi e aggiornati sulle funzionalità finanziarie dell'app per permetterci di assicurarci che l'app inviata venga esaminata dai team giusti.
  3. ID pubblicità:aiutaci a capire se l'app utilizza un ID pubblicità.
  4. Credenziali di test (dettagli di accesso): se alcune parti dell'app sono limitate in base a dettagli di accesso, abbonamenti, posizione o altre forme di autenticazione, fornisci istruzioni su come accedervi.
  5. Norme sulla privacy: un link e dettagli sulle norme sulla privacy dell'app.
  6. Pubblico di destinazione e contenuti:devi comunicarci la fascia d'età target dell'app e altre informazioni relative ai suoi contenuti. Ciò contribuisce a garantire che le app destinate ai bambini siano sicure e appropriate.
  7. Annunci:devi farci sapere se l'app contiene annunci.

Obbligatorio in base alle condizioni:

  1. App governative:comunicaci se l'app è destinata all'utilizzo da parte di governi di qualsiasi tipo. Sono inclusi i governi nazionali e statali, le amministrazioni comunali e le autorità locali. In questo modo possiamo assicurarci che l'app inviata venga esaminata dai team giusti. Se questa dichiarazione non viene completata, l'app verrà considerata non governativa.
  2. Norme sugli standard di sicurezza dei bambini:obbligatorie per le app delle categorie "Social" o "Incontri". Le app delle categorie social o di incontri devono fornire gli standard di sicurezza pubblicati e i dati di contatto per essere conformi alle nostre norme sugli standard di sicurezza dei minori.
  3. App di notizie e riviste:obbligatorio per le app nella categoria "Notizie e riviste". Aggiungi dettagli sull'app di notizie e riviste per garantire la trasparenza in merito alle entità che la gestiscono.

Struttura della richiesta API

Le dichiarazioni relative alle norme sono fornite all'interno dell'array policyDeclarations nel corpo di UpdateAppStoreHostedAppRequest. Ogni elemento di questo array è un oggetto AppStoreAppPolicyDeclaration.

AppStoreAppPolicyDeclaration Oggetto:

  • declarationId (stringa, obbligatorio): l'identificatore univoco della dichiarazione delle norme (ad es. POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (array di PolicyResponse, obbligatorio): un elenco di risposte alle domande all'interno di quella dichiarazione specifica.

PolicyResponse Oggetto:

  • questionId (stringa, obbligatorio): l'identificatore univoco della domanda specifica a cui si risponde (ad es. POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (Obbligatorio): la risposta stessa, che può essere uno dei seguenti tipi:
    • booleanResponse: Per le domande con risposta Sì o No.
      • value (booleano)
    • stringResponse: per risposte in testo normale, inclusi gli URL.
      • value (stringa)
    • singleChoiceResponse: Quando è possibile selezionare una sola opzione da un elenco.
      • value (stringa): l'ID della scelta di risposta selezionata.
    • multipleChoiceResponse: quando è possibile selezionare più opzioni.
      • values (array di stringhe): gli ID delle scelte di risposta selezionate.
    • documentResponse: Per domande che richiedono il caricamento di un documento. Consulta Gestione dei caricamenti di documenti.
    • groupResponse: Per set ripetuti di domande nidificate.
    • keyedGroupResponse: Per insiemi di domande nidificate raggruppate in base a una chiave specifica.

Per esempi di snippet per la dichiarazione, consulta la guida dettagliata.

Gestione dei caricamenti di documenti

Per alcune domande relative alle norme è necessario fornire documenti giustificativi (ad es. licenze per le funzionalità finanziarie). I documenti non possono essere incorporati direttamente in UpdateAppStoreHostedAppRequest. Devi invece:

  1. Carica il documento:utilizza l'endpoint UploadAppStoreAppPolicyDeclarationFile. Questa è una richiesta di caricamento di contenuti multimediali. fileType deve essere impostato su DECLARATION_FILE_TYPE_DOCUMENT.

    • Endpoint: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • Le risposte di caricamento riuscito includeranno un fileId.

  2. Fai riferimento all'ID documento:nel PolicyResponse per la domanda sul documento, utilizza il tipo documentResponse. Compila il campo documentId con il fileId ottenuto dal passaggio di caricamento.

PolicyDocumentResponse Oggetto:

  • documentId (stringa, obbligatorio): l'ID restituito dall'endpoint UploadAppStoreAppPolicyDeclarationFile.
  • expiryDate (data, facoltativo): la data di scadenza del documento, se applicabile.
  • nonExpiring (booleano, facoltativo): impostalo su true se il documento non scade.

Esempio per la risposta del documento:

// 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. Controllare la disponibilità

Una volta eseguito il commit dello stato dell'app ospitata utilizzando UpdateAppStoreHostedApp, l'app viene elaborata automaticamente e contrassegnata come pubblicata per impostazione predefinita in Google Play per lo store di terze parti.

Per controllare la disponibilità dell'app dopo il commit, chiama il metodo updateappstorehostedapppublishstatus per aggiornarne lo stato:

  • Annullamento della pubblicazione di un'app: per rendere non disponibile l'app ospitata, imposta il campo publishState su APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • Ripubblicazione di un'app: per rendere nuovamente disponibile un'app precedentemente non pubblicata senza modificare le schede o ricaricare gli asset, imposta il campo publishState su APP_STORE_APP_PUBLISH_STATE_PUBLISHED.