Ottenere i dati sulle acquisizioni dei componenti aggiuntivi per giochi e app

  • Articolo

Usa questo metodo nell'API di analisi di Microsoft Store per ottenere dati aggregati sulle acquisizioni dei componenti aggiuntivi in formato JSON per le app UWP e i giochi per Xbox One inseriti tramite il portale per sviluppatori Xbox (XDP) e disponibili nel dashboard del Partner Center XDP Analytics.

Prerequisiti

Per usare questo metodo, è necessario prima eseguire le operazioni seguenti:

  • Se non lo si è ancora fatto, completare i prerequisiti per l'API di analisi di Microsoft Store.
  • Ottenere un token di accesso di Azure AD da usare nell'intestazione della richiesta per questo metodo. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza. Dopo la scadenza del token, è possibile ottenerne uno nuovo.

Nota

Questa API non fornisce dati aggregati giornalieri prima del 1 ottobre 2016.

Richiedi

Sintassi della richiesta

metodo URI della richiesta
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

Intestazione della richiesta

Intestazione Type Descrizione
Autorizzazione stringa Obbligatorio. Token di accesso di Azure AD nel formato Bearer<token>.

Parametri della richiesta

Il parametro applicationId o addonProductId è obbligatorio. Per recuperare i dati di acquisizione per tutti i componenti aggiuntivi registrati nell'app, specificare il parametro applicationId. Per recuperare i dati di acquisizione per un singolo componente aggiuntivo, specificare il parametro addonProductId. Se si specificano entrambi, il parametro applicationId viene ignorato.

Parametro Tipo Descrizione Richiesto
applicationId string ProductId del gioco Xbox One per il quale si stanno recuperando i dati di acquisizione. Per ottenere il productId del gioco, passare al gioco nel programma XDP Analytics e recuperare il productId dall'URL. In alternativa, se si scaricano i dati sulle acquisizioni dal report di analisi del Partner Center, il valore productId viene incluso nel file con estensione .tsv. Sì
addonProductId string ProductId del componente aggiuntivo per il quale si desidera recuperare i dati di acquisizione. Sì
startDate data Data di inizio nell'intervallo di date dei dati di acquisizione del componente aggiuntivo da recuperare. L'impostazione predefinita è la data corrente. No
endDate data Data di fine nell'intervallo di date dei dati di acquisizione del componente aggiuntivo da recuperare. L'impostazione predefinita è la data corrente. No
filter string Una o più istruzioni che filtrano le righe nella risposta. Ogni istruzione contiene un nome di campo dal corpo della risposta e dal valore associati agli operatori eq o ne e le istruzioni possono essere combinate usando e o o. I valori stringa devono essere racchiusi tra virgolette singole nel parametro filter. Ad esempio, filter=market eq 'US' e gender eq 'm'.
È possibile specificare i campi seguenti del corpo della risposta:
  • acquisitionType
  • età
  • storeClient
  • sesso
  • market
  • osVersion
  • deviceType
  • sandboxId
 No
aggregationLevel string Specifica l'intervallo di tempo per il quale recuperare i dati aggregati. Può essere una delle stringhe seguenti: giorno, settimana o mese. Se non è specificato, il valore predefinito è giorno. No
orderby string Istruzione che ordina i valori dei dati dei risultati per ogni acquisizione del componente aggiuntivo. La sintassi è orderby=field [order],field [order],.... Il parametro field può essere una delle stringhe seguenti:
  • date
  • acquisitionType
  • età
  • storeClient
  • sesso
  • market
  • osVersion
  • deviceType
  • orderName
Il parametro ordine è facoltativo e può essere asc o desc per specificare l'ordine crescente o decrescente per ogni campo. Il valore predefinito è asc.
Di seguito è riportato un esempio di stringa orderby: orderby=date,market		 No
groupby string Istruzione che applica l'aggregazione dei dati solo ai campi specificati. È possibile specificare i campi seguenti:
  • date
  • applicationName
  • addonProductName
  • acquisitionType
  • età
  • storeClient
  • sesso
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleIdHex
Le righe di dati restituite conterranno i campi specificati nel parametro groupby e i seguenti:
  • date
  • applicationId
  • addonProductId
  • acquisitionQuantity
Il parametro groupby può essere usato con il parametro aggregationLevel. Ad esempio: &groupby=age,market&aggregationLevel=week		 No

Esempio di richiesta

Gli esempi seguenti illustrano diverse richieste di recupero dei dati di acquisizione dei componenti aggiuntivi. Sostituire i valori addonProductId e applicationId con l'ID dello Store appropriato per il componente aggiuntivo o l'app.

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

Corpo della risposta

Valore Tipo Descrizione
Valore matrice Matrice di oggetti che contengono dati aggregati sulle acquisizioni dei componenti aggiuntivi. Per maggiori informazioni sui dati in ogni oggetto, vedere la sezione valori di acquisizione dei componenti aggiuntivi di seguito.
TotalCount int Numero totale di righe nei risultati di dati per la query.

Valori di acquisizione dei componenti aggiuntivi

Gli elementi nella matrice Valore contengono i valori seguenti.

Valore Tipo Descrizione
data string Prima data dell'intervallo di date per i dati acquisizione. Se la richiesta ha specificato un singolo giorno, questo valore corrisponde alla data. Se la richiesta ha specificato una settimana, un mese o un altro intervallo di date, questo valore corrisponde alla prima data nell'intervallo di date.
addonProductId string ProductId del componente aggiuntivo per il quale si stanno recuperando i dati di acquisizione.
addonProductName string Nome visualizzato del componente aggiuntivo. Questo valore viene visualizzato solo nei dati della risposta se il parametro aggregationLevel è impostato su daygiorno, a meno che non si specifichi il campo addonProductNamenel parametro groupby.
applicationId string ProductId dell'app per la quale si desidera recuperare i dati di acquisizione del componente aggiuntivo.
applicationName string Nome visualizzato del gioco.
deviceType string Una delle stringhe seguenti che specifica il tipo di dispositivo che ha completato l'acquisizione:
  • "PC"
  • "Telefono"
  • "Console-Xbox One"
  • "Console-Xbox Series X"
  • "IoT"
  • "Server"
  • "Tablet"
  • "Olografico"
  • "Sconosciuto"
storeClient string Una delle stringhe seguenti che indica la versione dello Store in cui si è verificata l'acquisizione:
  • "Store del Telefono Windows (client)"
  • "Microsoft Store (client)" (o "Windows Store (client)" se si eseguono query sui dati prima del 23 marzo 2018)
  • "Microsoft Store (web)" (o "Windows Store (web)" se si eseguono query sui dati prima del 23 marzo 2018)
  • "Volume di acquisto delle organizzazioni"
  • "Altro"
osVersion string Versione del sistema operativo in cui si è verificata l'acquisizione. Per questo metodo, questo valore è sempre Windows 10 o Windows 11".
market string Codice Paese ISO 3166 del mercato in cui si è verificata l'acquisizione.
sesso string Una delle stringhe seguenti che specifica il sesso dell'utente che ha eseguito l'acquisizione:
  • "m"
  • "f"
  • "Sconosciuto"
età string Una delle stringhe seguenti che indica la fascia di età dell'utente che ha eseguito l'acquisizione:
  • "meno di 13"
  • "13-17"
  • "18-24"
  • "25-34"
  • "35-44"
  • "44-55"
  • "maggiore di 55"
  • "Sconosciuto"
acquisitionType string Una delle stringhe seguenti che indica il tipo di acquisizione:
  • "Gratuita"
  • "Versione di valutazione"
  • "A pagamento"
  • "Codice promozionale"
  • "Iap"
  • "Abbonamento Iap"
  • "Destinatari privati"
  • "Preordine"
  • "Xbox Game Pass" (o "Game Pass" se si eseguono query sui dati prima del 23 marzo 2018)
  • "Disco"
  • "Codice prepagato"
  • "Ordine preliminare addebitato"
  • "Pre-ordine annullato"
  • "Pre-ordine non riuscito"
acquisitionQuantity integer Numero di acquisizioni che si sono verificate.
inAppProductId string ID prodotto del prodotto in cui viene usato questo componente aggiuntivo.
inAppProductName string Nome prodotto del prodotto in cui viene usato questo componente aggiuntivo.
paymentInstrumentType string Tipo di strumento di pagamento utilizzato per l'acquisizione.
sandboxId string ID Sandbox creato per il gioco. Può trattarsi del valore RETAIL o di un ID sandbox privato.
xboxTitleId string ID titolo Xbox del prodotto da XDP, se applicabile.
localCurrencyCode string Codice valuta locale in base al paese dell'account del Partner Center.
xboxProductId string ID Prodotto Xbox del prodotto da XDP, se applicabile.
availabilityId string ID disponibilità del prodotto da XDP, se applicabile.
skuId string ID SKU del prodotto da XDP, se applicabile.
skuDisplayName string Nome SKU visualizzato del prodotto da XDP, se applicabile.
xboxParentProductId string ID Prodotto genitore Xbox del prodotto da XDP, se applicabile.
parentProductName string Nome Prodotto genitore Xbox del prodotto da XDP, se applicabile.
productTypeName string Nome tipo Prodotto del prodotto da XDP, se applicabile.
purchaseTaxType string Tipo di imposta per l'acquisto del prodotto da XDP, se applicabile.
purchasePriceUSDAmount Numero Importo pagato dal cliente per il componente aggiuntivo, convertito in USD.
purchasePriceLocalAmount Numero Importo pagato dal cliente per il componente aggiuntivo, nella valuta dell'area geografica.
purchaseTaxUSDAmount Numero Importo fiscale applicato al componente aggiuntivo, convertito in USD.
purchaseTaxLocalAmount Numero Importo delle tasse di acquisto locale del prodotto da XDP, se applicabile.

Risposta di esempio

L'esempio seguente illustra un esempio di corpo della risposta JSON per questa richiesta.

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