Partager via

Obtenez des données sur les extensions achetées pour vos jeux et applications

Utilisez cette méthode dans l’API d’analytique du Microsoft Store pour obtenir des données d’acquisition d’extensions agrégées au format JSON pour les applications UWP et les jeux Xbox One, ingérés via le Portail des développeurs Xbox (XDP) et disponibles dans le tableau de bord du Centre de partenaires XDP Analytics.

Prérequis

Pour utiliser cette méthode, vous devez d’abord effectuer les opérations suivantes :

  • Si ce n’est pas déjà fait, remplissez toutes les conditions préalables relatives à l’API d’analyse de la Boutique Microsoft.
  • Obtenir un jeton d’accès Azure AD à utiliser dans l’en-tête de requête pour cette méthode. Une fois que vous avez récupéré le jeton d’accès, vous avez 60 minutes pour l’utiliser avant qu’il n’expire. Une fois le jeton expiré, vous pouvez en obtenir un nouveau.

Remarque

Cette API ne fournit pas de données d’agrégation quotidiennes avant le 1er octobre 2016.

Requête

Syntaxe de la requête

Méthode URI de requête
OBTENIR https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

En-tête de requête

En-tête de page Catégorie Descriptif
Autorisation chaîne Obligatoire. Le jeton d'accès Azure AD sous la forme Bearer<token>.

Paramètres de la demande

Le paramètre applicationId ou addonProductId est requis. Pour récupérer les données d’acquisition pour tous les modules complémentaires inscrits à l’application, spécifiez le paramètre applicationId. Pour récupérer les données d’acquisition d’un seul module complémentaire, spécifiez le paramètre addonProductId. Si vous spécifiez les deux, le paramètre applicationId est ignoré.

Paramètre Catégorie Descriptif Obligatoire
applicationId chaîne Le productId du jeu Xbox One pour lequel vous récupérez des données d’acquisition. Pour obtenir le productId de votre jeu, accédez à votre jeu dans le programme d’analyse XDP et récupérez le productId à partir de l’URL. Sinon, si vous téléchargez vos données d’acquisition à partir du rapport d’analytique de l’Espace partenaires, le productId est inclus dans le fichier .tsv. Oui
addonProductId chaîne ProductId du module complémentaire pour lequel vous souhaitez récupérer les données d’acquisition. Oui
date de début date Date de début dans la plage de dates des données d’acquisition d’extensions à récupérer. La valeur par défaut est la date actuelle. Non
date de fin date Date de fin dans la plage de dates des données d’acquisition d’extensions à récupérer. La valeur par défaut est la date actuelle. Non
Filter chaîne Une ou plusieurs instructions qui filtrent les lignes dans la réponse. Chaque instruction contient un nom de champ à partir du corps de la réponse et une valeur associés aux opérateurs eq ou ne, et les instructions peuvent être combinées à l’aide et ou ou. Les valeurs de chaîne doivent être entourées de guillemets simples dans le paramètre de filtre. Par exemple, filter=market eq 'US' et gender eq 'm'.
Vous pouvez spécifier les champs suivants à partir du corps de la réponse :
  • type d'acquisition
  • âge
  • storeClient
  • sexe
  • marché
  • osVersion
  • type d'appareil
  • sandboxId
 Non
niveau d'agrégation chaîne Spécifie l’intervalle de temps pour lequel récupérer des données agrégées. Il peut s’agir de l’une des chaînes suivantes : jour, semaine ou mois. Si aucune valeur n’est spécifiée, la valeur par défaut est jour. Non
classer par chaîne Instruction qui ordonne les valeurs des données de résultat pour chaque acquisition de module complémentaire. La syntaxe est orderby=field [order],field [order],... Le paramètre de champ peut être l’une des chaînes suivantes :
  • date
  • type d'acquisition
  • âge
  • storeClient
  • sexe
  • marché
  • osVersion
  • type d'appareil
  • orderName
Le paramètre d’ordre est facultatif et peut être asc ou desc pour spécifier l’ordre croissant ou décroissant pour chaque champ. La valeur par défaut est asc.
Voici un exemple de chaîne orderby : orderby=date,market		 Non
grouppar chaîne Instruction qui applique l’agrégation de données uniquement aux champs spécifiés. Spécifiez les champs suivants :
  • date
  • nomapplication
  • addonProductName
  • type d'acquisition
  • âge
  • storeClient
  • sexe
  • marché
  • osVersion
  • type d'appareil
  • type d'instrument de paiement
  • sandboxId
  • xboxTitleIdHex
Les lignes de données retournées contiennent les champs spécifiés dans le paramètre groupby, ainsi que les éléments suivants :
  • date
  • applicationId
  • addonProductId
  • quantité d'acquisition
Le paramètre groupby peut être utilisé avec le paramètre aggregationLevel. Par exemple : &groupby=age,market&aggregationLevel=semaine		 Non

Exemple de requête

Les exemples suivants illustrent plusieurs demandes d’obtention de données d’acquisition d’extensions. Remplacez les valeurs addonProductId et applicationId par l’ID Store approprié pour votre module complémentaire ou votre application.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0 HTTP/1.1 

Authorization: Bearer <your access token> 

 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0&filter=market eq 'GB' and gender eq 'm' HTTP/1.1 

Authorization: Bearer <your access token>

Réponse

Corps de la réponse

Valeur Catégorie Descriptif
Valeur tableau Tableau d’objets contenant des données agrégées d’acquisition d’extensions. Pour plus d’informations sur les données de chaque objet, consultez la section ci-dessous sur les valeurs d’acquisition des modules complémentaires.
NombreTotal Int Nombre total de lignes dans le résultat des données de la requête.

Valeurs d’acquisition d’extensions

Les éléments du tableau Valeur contiennent les valeurs suivantes.

Valeur Catégorie Descriptif
date chaîne Première date de la plage de dates pour les données d'acquisition. Si la demande a spécifié un jour unique, cette valeur est cette date. Si la requête a spécifié une semaine, un mois ou une autre plage de dates, cette valeur est la première date de cette plage de dates.
addonProductId chaîne productId du module complémentaire pour lequel vous récupérez des données d’acquisition.
NomDuProduitAdditionnel chaîne Nom d’affichage de l’extension. Cette valeur apparaît uniquement dans les données de réponse si le paramètre aggregationLevel est défini sur jour, sauf si vous spécifiez le champ addonProductName dans le paramètre groupby.
applicationId chaîne Le productId de l’application pour laquelle vous voulez récupérer les données d’acquisition d’extensions.
Nom de l'application chaîne Le nom d'affichage du jeu.
type d'appareil chaîne L'une des chaînes suivantes qui spécifie le type d'appareil qui a effectué l'acquisition :
  • « PC »
  • « Téléphone »
  • « Console-Xbox One »
  • « Console-Xbox Series X »
  • « IoT »
  • « Serveur »
  • « Tablette »
  • « Holographique »
  • « Inconnu »
storeClient chaîne Une des chaînes suivantes qui indique la version du magasin où l'acquisition a eu lieu :
  • « Windows Phone Store (client) »
  • « Boutique Microsoft (client) » (ou « Boutique Windows (client) » si vous interrogez des données datant d’avant le 23 mars 2018)
  • « Boutique Microsoft (web) » (ou « Boutique Windows (web) » si vous interrogez des données datant d’avant le 23 mars 2018)
  • « Achat en volume par les organisations »
  • « Autre »
osVersion chaîne Version du système d’exploitation sur laquelle l’acquisition s’est produite. Pour cette méthode, cette valeur est toujours Windows 10 ou Windows 11.
marché chaîne Code pays ISO 3166 du marché où l’acquisition s’est produite.
sexe chaîne Une des chaînes suivantes qui spécifie le sexe de l'utilisateur qui a effectué l'acquisition :
  • « m »
  • « f »
  • « Inconnu »
âge chaîne Un des textes suivants qui indique le groupe d’âge de l’utilisateur ayant effectué l’acquisition :
  • « inférieur à 13 »
  • « 13-17 »
  • « 18-24 »
  • « 25-34 »
  • « 35-44 »
  • « 44-55 »
  • « supérieur à 55 »
  • « Inconnu »
type d'acquisition chaîne Une des expressions suivantes qui indique le type d’acquisition :
  • « Gratuit »
  • « Essai »
  • « Payant »
  • « Code de promotion »
  • « portable »
  • « Abonnement Iap »
  • Audience privée
  • « Précommande »
  • « Xbox Game Pass » (ou « Game Pass » si vous interrogez des données datant d’avant le 23 mars 2018)
  • « Disque »
  • « Code prépayé »
  • « Pré-commande chargée »
  • « Précommande annulée »
  • « Échec de la précommande »
quantitéAcquisition entier Nombre d’acquisitions qui se sont produites.
inAppProductId chaîne ID de produit du produit dans lequel ce module complémentaire est utilisé.
NomDuProduitDansL'Application chaîne Nom du produit dans lequel ce module complémentaire est utilisé.
type d'instrument de paiement chaîne Type d’instrument de paiement utilisé pour l’acquisition.
sandboxId chaîne L’ID du bac à sable créé pour le jeu. Il peut s’agir de la valeur RETAIL ou d’un ID de bac à sable privé.
xboxTitreId chaîne Identifiant de titre Xbox du produit de XDP, le cas échéant.
codeMonnaieLocale chaîne Code de la devise locale basé sur le pays/la région du compte Partner Center.
xboxProductId chaîne Identifiant de produit Xbox du produit de XDP, le cas échéant.
identifiant de disponibilité chaîne ID de disponibilité du produit à partir de XDP, le cas échéant.
skuId chaîne ID de référence SKU du produit à partir de XDP, le cas échéant.
skuDisplayName chaîne Nom d’affichage de la référence SKU du produit de XDP, le cas échéant.
xboxParentProductId chaîne Identifiant parent de produit Xbox du produit de XDP, le cas échéant.
nomDuProduitParent chaîne Nom du produit parent provenant de XDP, le cas échéant.
nomDuTypeDeProduit chaîne Nom du type de produit provenant de XDP, le cas échéant.
type de taxe d'achat chaîne Type de taxe d’achat du produit auprès de XDP, le cas échéant.
prixAchatMontantUSD nombre Montant payé par le client pour le module complémentaire, converti en USD.
prixAchatMontantLocal nombre Montant payé par le client pour le module complémentaire, dans la devise de la région.
montantTaxeAchatUSD nombre Montant fiscal appliqué au module complémentaire, converti en USD.
montantTaxeLocaleAchat nombre Montant local de la taxe d’achat du produit auprès de XDP, le cas échéant.

Exemple de réponse

L’exemple suivant illustre un exemple de corps de réponse JSON pour cette requête.

{ 
  "Value": [ 
    { 
            "inAppProductId": "9NBLGGH1864K", 
            "inAppProductName": "866879", 
            "addonProductId": "9NBLGGH1864K", 
            "addonProductName": "866879", 
            "date": "2017-11-05", 
            "applicationId": "9WZDNCRFJ314", 
            "applicationName": "Tetris Blitz", 
            "acquisitionType": "Iap", 
            "age": "35-49", 
            "deviceType": "Phone", 
            "gender": "m", 
            "market": "US", 
            "osVersion": "Windows Phone 8.1", 
            "paymentInstrumentType": "Credit Card", 
            "sandboxId": "RETAIL", 
            "storeClient": "Windows Phone Store (client)", 
            "xboxTitleId": "", 
            "localCurrencyCode": "USD", 
            "xboxProductId": "00000000-0000-0000-0000-000000000000", 
            "availabilityId": "", 
            "skuId": "", 
            "skuDisplayName": "Full", 
            "xboxParentProductId": "", 
            "parentProductName": "Tetris Blitz", 
            "productTypeName": "Add-On", 
            "purchaseTaxType": "", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 1.08, 
            "purchasePriceLocalAmount": 0.09, 
            "purchaseTaxUSDAmount": 1.08, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null, 
    
    "TotalCount": 7601 
}
  • Last updated on