Guide du développeur de l'API App Store Review

L'API App Store Review permet aux magasins d'applications tiers enregistrés sur Google Play via le programme "Magasin d'applications tiers sur Play" de fournir les informations requises pour les applications hébergées sur leur plate-forme. Cela inclut les métadonnées de l'application, les fiches, les binaires APK et les déclarations de conformité avec les règles.

Pour obtenir la liste complète des points de terminaison, des méthodes et des schémas de ressources, consultez la documentation de référence de l'API App Store Review.

Avant de commencer

Vous devez suivre le guide de démarrage principal pour configurer votre accès à l'API, vos identifiants de service et votre projet Google Cloud avant de pouvoir effectuer des appels à l'API App Store Review. L'API App Store Review s'attend à recevoir au maximum 300 requêtes par minute et par plate-forme de téléchargement d'applications.

Conception et architecture des API

L'API App Store Review fonctionne selon un modèle instantané atomique. Au lieu d'utiliser des sessions transactionnelles, vous importez les fichiers individuellement, puis validez l'état complet dans un seul appel atomique :

  1. Vous importez des fichiers et des composants individuels (APK, images et fichiers de règles) dans des appels directs distincts.
  2. Vous mettez en cache les ID renvoyés pour ces fichiers.
  3. Vous envoyez une seule et unique requête UpdateAppStoreHostedApp pour valider l'état de l'application hébergée de manière atomique.

1. Inscription

Pour enregistrer une application hébergée, appelez la méthode createappstorehostedapp en spécifiant le nom du package de l'application et celui de votre plate-forme de téléchargement. Pour en savoir plus sur les schémas de requête et de réponse, consultez la documentation de référence de l'API.

2. Importations binaires et d'éléments

Une fois l'application hébergée enregistrée, vous devez importer ses composants à l'aide des points de terminaison d'importation spécialisés :

  • APK : tous les binaires APK de l'application distribués activement (à l'aide de uploadapk).
  • Images : composants Image, tels que l'icône d'application et les captures d'écran (à l'aide de uploadimage).
  • Règles : (le cas échéant) documentation sur les règles (en utilisant uploadappstoreapppolicydeclarationfile).

Mise en cache et réutilisation des composants

Pour optimiser la bande passante et les performances, n'effectuez pas de nouvelle importation d'éléments identiques. Tous les jetons apkId, imageId et fileId renvoyés sont persistants. Vous pouvez mettre ces ID en cache dans votre propre base de données backend et les réutiliser lors des mises à jour ultérieures de l'application hébergée. Par exemple, si vous mettez à jour la description d'une application hébergée, mais que l'icône et les captures d'écran de l'application restent inchangées, utilisez les jetons imageId mis en cache dans votre prochain appel de mise à jour.

3. Assembler et valider

Une fois que vous avez importé tous les composants et récupéré leurs ID respectifs, vous devez assembler l'état complet de l'application hébergée et l'enregistrer à l'aide de la méthode updateappstorehostedapp. Cette méthode accepte une représentation complète et atomique des détails de l'application hébergée, des fiches Play Store localisées, des ensembles d'APK actifs et des déclarations de sécurité.

Cet appel remplace tout état actif précédent par le nouvel état décrit dans la requête.

Exemple de corps de requête

Voici un corps de requête JSON réaliste et syntaxiquement valide qui illustre tous les éléments clés :

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

Déclarations relatives aux règles

Lorsque vous envoyez ou mettez à jour les informations sur l'application à l'aide de l'API, vous devez inclure toutes les déclarations requises par le règlement.

Exigences concernant la déclaration

Les déclarations suivantes sont concernées :

Obligatoire pour toutes les applications afin de confirmer si des déclarations supplémentaires sont nécessaires :

  1. Applications de santé : indiquez-nous les fonctionnalités de santé que l'application utilise afin de nous aider à déterminer quelles exigences du règlement sur les applications de santé elle doit respecter.
  2. Fonctionnalités financières : les applications proposant des fonctionnalités financières peuvent être dans l'obligation de se conformer à certaines réglementations dans certains pays ou certaines régions. Envoyez des informations précises et à jour sur les fonctionnalités financières de l'application pour nous permettre de nous assurer que les équipes appropriées examinent la demande.
  3. Identifiant publicitaire : aidez-nous à déterminer si l'application utilise un identifiant publicitaire.
  4. Identifiants de test (informations de connexion) : si des parties de l'application sont limitées en raison d'informations de connexion, d'abonnements, de données de localisation ou de toute autre forme d'authentification, indiquez comment y accéder.
  5. Règles de confidentialité : lien vers les règles de confidentialité de l'application et informations les concernant.
  6. Cible et contenu : vous devez nous indiquer la tranche d'âge cible de l'application et d'autres informations sur son contenu. Nous serons ainsi en mesure de nous assurer que les applications conçues pour les enfants sont adaptées à ce type d'audience.
  7. Annonces : vous devez nous indiquer si l'application contient des annonces.

Obligatoire sous certaines conditions :

  1. Applications gouvernementales : indiquez-nous si l'application est destinée à être utilisée par un organisme gouvernemental. Cela inclut les administrations nationales, étatiques et municipales, ainsi que les autorités locales. Nous pouvons ainsi nous assurer que les bonnes équipes examinent la demande. Si vous ne remplissez pas cette déclaration, l'application sera considérée comme non gouvernementale.
  2. Normes liées à la sécurité des enfants : obligatoires pour les applications des catégories "Réseaux sociaux" ou "Rencontres". Les applications de réseaux sociaux ou de rencontres doivent fournir des normes de sécurité publiées et des coordonnées pour respecter notre Règlement sur les normes liées à la sécurité des enfants.
  3. Applications d'actualités et de magazines : obligatoire pour les applications de la catégorie "Actualités et magazines". Ajoutez des informations sur l'appli d'actualités et de magazines dans un souci de transparence sur les entités dont elle dépend.

Structure des requêtes API

Les déclarations de conformité au règlement sont fournies dans le tableau policyDeclarations du corps de UpdateAppStoreHostedAppRequest. Chaque élément de ce tableau est un objet AppStoreAppPolicyDeclaration.

AppStoreAppPolicyDeclaration Objet :

  • declarationId (chaîne, obligatoire) : identifiant unique de la déclaration de règle (par exemple, POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (tableau de PolicyResponse, obligatoire) : liste des réponses aux questions de cette déclaration spécifique.

PolicyResponse Objet :

  • questionId (chaîne, obligatoire) : identifiant unique de la question spécifique à laquelle la réponse est fournie (par exemple, POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (obligatoire) : la réponse elle-même, qui peut être l'un des types suivants :
    • booleanResponse : pour les questions de type "Oui" ou "Non".
      • value (booléen)
    • stringResponse : pour les réponses en texte brut, y compris les URL.
      • value (chaîne)
    • singleChoiceResponse : lorsqu'une seule option peut être sélectionnée dans une liste.
      • value (chaîne) : ID du choix de réponse sélectionné.
    • multipleChoiceResponse : lorsque plusieurs options peuvent être sélectionnées.
      • values (tableau de chaînes) : ID des choix de réponse sélectionnés.
    • documentResponse : pour les questions nécessitant l'importation d'un document. Consultez Gérer les importations de documents.
    • groupResponse : pour les ensembles de questions imbriquées répétées.
    • keyedGroupResponse : pour les ensembles de questions imbriquées regroupées par une clé spécifique.

Pour obtenir des exemples d'extraits de code pour la déclaration, consultez le guide détaillé.

Gérer les importations de documents

Pour certaines questions sur les règles, vous devez fournir des pièces justificatives (par exemple, des licences pour les fonctionnalités financières). Les documents ne peuvent pas être intégrés directement dans UpdateAppStoreHostedAppRequest. Vous devez plutôt :

  1. Importer le document : utilisez le point de terminaison UploadAppStoreAppPolicyDeclarationFile. Il s'agit d'une demande d'importation de contenu multimédia. fileType doit être défini sur DECLARATION_FILE_TYPE_DOCUMENT.

    • Point de terminaison : POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • Les réponses d'importation réussie incluent un fileId.

  2. Faites référence à l'ID du document : dans le PolicyResponse de la question sur le document, utilisez le type documentResponse. Renseignez le champ documentId avec le fileId obtenu lors de l'étape d'importation.

PolicyDocumentResponse Objet :

  • documentId (chaîne, obligatoire) : ID renvoyé par le point de terminaison UploadAppStoreAppPolicyDeclarationFile.
  • expiryDate (date, facultatif) : date d'expiration du document, le cas échéant.
  • nonExpiring (booléen, facultatif) : défini sur true si le document n'expire pas.

Exemple de réponse de document :

// 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. Contrôler la disponibilité

Une fois que vous avez validé l'état de l'application hébergée à l'aide de UpdateAppStoreHostedApp, l'application est automatiquement traitée et marquée comme publiée par défaut dans Google Play pour le magasin d'applications tiers.

Pour contrôler la disponibilité de l'application une fois qu'elle a été validée, appelez la méthode updateappstorehostedapppublishstatus pour mettre à jour son état :

  • Annuler la publication d'une application : pour rendre l'application hébergée indisponible, définissez le champ publishState sur APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • Republier une application : pour rendre une application non publiée à nouveau disponible sans modifier les fiches ni réimporter les composants, définissez le champ publishState sur APP_STORE_APP_PUBLISH_STATE_PUBLISHED.