Partager via

Obtenir des données d’acquisitions d’extension 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 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 de l’Espace partenaires Analyse XDP.

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

Method URI de demande
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

En-tête de requête

En-tête Type Description
Autorisation string Obligatoire. Jeton d’accès Azure AD dans le porteur <token>de formulaire .

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 Type Description Obligatoire
applicationId string 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 string ProductId du module complémentaire pour lequel vous souhaitez récupérer les données d’acquisition. Oui
startDate date Date de début dans la plage de dates des données d’acquisition de l’extension à 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 de l’extension à 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 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
  • acquisitionType
  • âge
  • storeClient
  • sexe
  • market
  • osVersion
  • deviceType
  • 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
groupby string Instruction qui applique l’agrégation de données uniquement aux champs spécifiés. Spécifiez les champs suivants :
  • date
  • applicationName
  • addonProductName
  • acquisitionType
  • âge
  • storeClient
  • sexe
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • 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
  • 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

Les exemples suivants illustrent plusieurs demandes d’obtention de données d’acquisition de modules complémentaires. 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>

Response

Response body

Valeur Type Description
active tableau Tableau d’objets qui contiennent des données d’acquisition d’extension agrégées. Pour plus d’informations sur les données de chaque objet, consultez la section des valeurs d’acquisition de module complémentaire ci-dessous.
TotalCount int Nombre total de lignes dans le résultat des données de la requête.

Valeurs d’acquisition de modules complémentaires

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.
addonProductId string productId du module complémentaire pour lequel vous récupérez des données d’acquisition.
addonProductName string 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 string ProductId de l’application pour laquelle vous souhaitez récupérer les données d’acquisition de module complémentaire.
applicationName string Nom complet du jeu.
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 »
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 »
  • « Autre »
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.
market string Code pays ISO 3166 du marché où l’acquisition s’est produite.
gender string Une des chaînes suivantes qui spécifie le genre de l’utilisateur qui a effectué l’acquisition :
  • "m"
  • "f"
  • « Inconnu »
âge string Une des chaînes suivantes qui indique le groupe d’âge de l’utilisateur qui a effectué l’acquisition :
  • « inférieur à 13 »
  • « 13-17 »
  • « 18-24 »
  • « 25-34 »
  • « 35-44 »
  • « 44-55 »
  • « supérieur à 55 »
  • « Inconnu »
acquisitionType string Une des chaînes suivantes qui indique le type d’acquisition :
  • « Gratuit »
  • « Essai »
  • « Payant »
  • « Code de promotion »
  • « 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 »
acquisitionQuantity entier Nombre d’acquisitions qui se sont produites.
inAppProductId string ID de produit du produit dans lequel ce module complémentaire est utilisé.
inAppProductName string Nom du produit dans lequel ce module complémentaire est utilisé.
PaymentInstrumenttype string Type d’instrument de paiement utilisé pour l’acquisition.
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é.
xboxTitleId string ID de titre Xbox du produit à partir de XDP, le cas échéant.
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.
purchasePriceUSDAmount nombre Montant payé par le client pour le module complémentaire, converti en USD.
purchasePriceLocalAmount nombre Montant payé par le client pour le module complémentaire, dans la devise de la région.
purchaseTaxUSDAmount nombre Montant fiscal appliqué au module complémentaire, converti en USD.
purchaseTaxLocalAmount 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 
}