Partager via

Obtenir des données d’acquisitions pour vos applications et vos jeux

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

Remarque

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

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.

Requête

Syntaxe de la requête

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

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

Paramètre Catégorie Descriptif Obligatoire
applicationId chaîne ID de produit du jeu Xbox One pour lequel vous récupérez des données d’acquisition. Pour obtenir l’ID de produit de votre jeu, accédez à votre jeu dans le programme d’analyse XDP et récupérez l’ID de produit à partir de l’URL. Sinon, si vous téléchargez vos données d’acquisition à partir du rapport d’analytique de l’Espace partenaires, l’ID de produit est inclus dans le fichier .tsv. Oui
date de début date Date de début dans la plage de dates des données d’acquisition à 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 à 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. 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
  • type d'instrument de paiement
  • sandboxId
  • xboxTitleId
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
  • type d'acquisition
  • âge
  • storeClient
  • sexe
  • marché
  • osVersion
  • type d'appareil
  • type d'instrument de paiement
  • sandboxId
  • xboxTitleId
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
  • 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

L’exemple suivant illustre plusieurs demandes d’obtention de données d’acquisition de jeux Xbox One. Remplacez la valeur applicationId par l’ID de produit de votre jeu.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&top=10&skip=0 HTTP/1.1 
Authorization: Bearer <your access token> 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&skip=0&filter=market eq 'US' and gender eq 'm' HTTP/1.1 
Authorization: Bearer <your access token>

Réponse

Corps de réponse

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

Valeurs d’acquisition

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.
applicationId chaîne ID de produit du jeu Xbox One pour lequel vous récupérez des données d’acquisition.
Nom de l'application chaîne Le nom d'affichage du jeu.
type d'acquisition chaîne Une des chaînes de caractères suivantes qui indique le type d’acquisition :
  • Gratuit
  • Essai
  • Payé
  • Code promotionnel
  • Iap
  • Abonnement Iap
  • Audience privée
  • Précommander
  • 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
âge chaîne Une des expressions suivantes indique le groupe d’âge de l’utilisateur qui a effectué l’acquisition :
  • Moins de 13
  • 13-17
  • 18-24
  • 25-34
  • 35-44
  • 44-55
  • Supérieur à 55
  • Inconnu
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 Série X
  • IdO
  • Serveur
  • Tablette
  • Holographique
  • Inconnu
sexe chaîne Une des chaînes suivantes qui spécifie le sexe de l'utilisateur qui a effectué l'acquisition :
  • m
  • f
  • Inconnu
marché chaîne Code pays ISO 3166 du marché où l’acquisition s’est produite.
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.
type d'instrument de paiement chaîne L’une des chaînes de caractères suivantes qui indique les informations de paiement utilisées pour l’acquisition :
  • Carte de crédit
  • Carte de débit direct
  • Achat déduit
  • Solde MS
  • Opérateur mobile
  • Transfert bancaire en ligne
  • PayPal
  • Fractionner la transaction
  • Échange de jetons
  • Montant zéro payé
  • eWallet
  • Inconnu
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é.
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
  • Autres
xboxTitreId chaîne ID de titre Xbox Live (représenté en valeur hexadécimale) attribué par le portail des développeurs Xbox (XDP) pour les jeux avec Xbox Live.
quantitéAcquisition nombre Nombre d’acquisitions qui se sont produites pendant le niveau d’agrégation spécifié.
prixAchatMontantUSD nombre Montant payé par le client pour l’acquisition, converti en USD, à l’aide du taux de change mensuel.
montantTaxeAchatUSD nombre Montant de l’impôt appliqué à l’acquisition, converti en USD.
codeMonnaieLocale chaîne Code de la devise locale basé sur le pays/la région du compte Partner Center.
xboxProductId chaîne ID du produit Xbox provenant 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 ID de produit parent Xbox fourni par XDP, si applicable.
nomDuProduitParent chaîne Nom du produit parent du produit provenant de XDP, le cas échéant.
NomDuTypeDeProduit chaîne Type de produit Nom du 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.
prixAchatMontantLocal nombre Montant local du prix d’achat du produit auprès de XDP, le cas échéant.
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": [ 
        { 
            "date": "2019-01-15T01:00:00.0000000Z", 
            "applicationId": "9WZDNCRFHXHT", 
            "applicationName": null, 
            "acquisitionType": "Paid", 
            "age": null, 
            "deviceType": "Phone", 
            "gender": null, 
            "market": "US", 
            "osVersion": "Windows 11", 
            "paymentInstrumentType": null, 
            "sandboxId": "RETAIL", 
            "storeClient": "Microsoft Store (client)", 
            "xboxTitleId": null, 
            "localCurrencyCode": "USD", 
            "xboxProductId": null, 
            "availabilityId": "B42LRTSZ2MCJ", 
            "skuId": "0010", 
            "skuDisplayName": null, 
            "xboxParentProductId": null, 
            "parentProductName": null, 
            "productTypeName": "Game", 
            "purchaseTaxType": "TaxesNotIncluded", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 3.08, 
            "purchasePriceLocalAmount": 3.08, 
            "purchaseTaxUSDAmount": 0.09, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null,
    
    "TotalCount": 12221 
}

 

  • Last updated on