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

  • Article

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 demande
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions

En-tête de requête

En-tête Type Description
Autorisation string Obligatoire. Jeton d’accès Azure AD au format porteur<token>.

Paramètres de la demande

Paramètre Type Description Obligatoire
applicationId string 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
startDate 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
endDate 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 string 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 :
  • acquisitionType
  • âge
  • storeClient
  • sexe
  • market
  • osVersion
  • deviceType
  • sandboxId
 Non
aggregationLevel string 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
orderby string Instruction qui commande les valeurs de 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
  • acquisitionType
  • âge
  • storeClient
  • sexe
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • 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
groupby string Instruction qui applique l’agrégation de données uniquement aux champs spécifiés. Spécifiez les champs suivants :
  • date
  • applicationName
  • acquisitionType
  • âge
  • storeClient
  • sexe
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • 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
  • acquisitionQuantity
Le paramètre groupby peut être utilisé avec le paramètre aggregationLevel. Par exemple : &groupby=age,market&aggregationLevel=week		 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>

Response

Response body

Valeur Type Description
active 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.
TotalCount 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 Type Description
date string La 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 string ID de produit du jeu Xbox One pour lequel vous récupérez des données d’acquisition.
applicationName string Nom complet du jeu.
acquisitionType string Une des chaînes suivantes qui indique le type d’acquisition :
  • Gratuit
  • Évaluation
  • Réglé(e)
  • Code promotionnel
  • Iap
  • Iap d’abonnement
  • Participant privé
  • 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 facturée
  • Précommande annulée
  • Échec de la précommande
age string Une des chaînes suivantes qui 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
deviceType string Une des chaînes suivantes qui spécifie le type d’appareil qui a terminé l’acquisition :
  • PC
  • Téléphone
  • Console-Xbox One
  • Console-Xbox Series X
  • IoT
  • Serveur
  • Tablette
  • Holographique
  • Inconnu
gender string Une des chaînes suivantes qui spécifie le genre de l’utilisateur qui a effectué l’acquisition :
  • m
  • f
  • Inconnu
market string Code pays ISO 3166 du marché où l’acquisition s’est produite.
osVersion string 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.
PaymentInstrumenttype string L’une des chaînes suivantes qui indique l’instruction de paiement utilisée 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 string ID de bac à sable créé pour le jeu. Il peut s’agir de la valeur RETAIL ou d’un ID de bac à sable privé.
storeClient string Une des chaînes suivantes qui indique la version du Store où l’acquisition s’est produite :
  • 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
xboxTitleId string 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.
acquisitionQuantity number Nombre d’acquisitions qui se sont produites pendant le niveau d’agrégation spécifié.
purchasePriceUSDAmount number Montant payé par le client pour l’acquisition, converti en USD, à l’aide du taux de change mensuel.
purchaseTaxUSDAmount number Montant de l’impôt appliqué à l’acquisition, converti en USD.
localCurrencyCode string Code monétaire local basé sur le pays du compte Espace partenaires.
xboxProductId string ID de produit Xbox du produit à partir de XDP, le cas échéant.
availabilityId string ID de disponibilité du produit à partir de XDP, le cas échéant.
skuId string ID de référence SKU du produit à partir de XDP, le cas échéant.
skuDisplayName string Nom complet de la référence SKU du produit à partir de XDP, le cas échéant.
xboxParentProductId string ID de produit parent Xbox du produit à partir de XDP, le cas échéant.
parentProductName string Nom du produit parent du produit à partir de XDP, le cas échéant.
productTypeName string Nom du type de produit du produit à partir de XDP, le cas échéant.
purchaseTaxType string Type de taxe d’achat du produit auprès de XDP, le cas échéant.
purchasePriceLocalAmount number Montant local du prix d’achat du produit auprès de XDP, le cas échéant.
purchaseTaxLocalAmount number 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 
}