Abrufen von Add-On-Kaufdaten für Ihre Spiele und Apps

  • Artikel

Verwenden Sie diese Methode in der Microsoft Store-Analyse-API, um aggregierte Add-On-Kaufdaten im JSON-Format für UWP-Apps und Xbox One-Spiele abzurufen, die über das Xbox Developer Portal (XDP) aufgenommen wurden und im XDP Analytics Partner Center-Dashboard verfügbar sind.

Voraussetzungen

Um diese Methode zu verwenden, müssen Sie zuerst Folgendes tun:

  • Falls noch nicht geschehen, erfüllen Sie alle Voraussetzungen für die Microsoft Store-Analyse-API.
  • Rufen Sie ein Azure AD-Zugriffstoken ab, das im Anforderungsheader für diese Methode verwendet wird. Nachdem Sie ein Zugriffstoken erhalten haben, haben Sie 60 Minuten Zeit, es zu verwenden, bevor es abläuft. Nachdem das Token abgelaufen ist, können Sie eine neue abrufen.

Hinweis

Diese API stellt keine täglichen Aggregatdaten vor dem 1. Oktober 2016 bereit.

Anforderung

Anforderungssyntax

Methode Anforderungs-URI
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

Anforderungsheader

Header type BESCHREIBUNG
Authorization Zeichenfolge Erforderlich. Das Azure AD-Zugriffstoken im Formular Bearer<token>.

Anforderungsparameter

Der Parameter applicationId oder addonProductId ist erforderlich. Um Kaufdaten für alle add-ons abzurufen, die für die App registriert sind, geben Sie den applicationId-Parameter an. Um Kaufdaten für ein einzelnes Add-On abzurufen, geben Sie den AddonProductId-Parameter an. Wenn Sie beide angeben, wird der applicationId-Parameter ignoriert.

Parameter Typ Beschreibung Erforderlich
applicationId Zeichenfolge Die productId des Xbox One-Spiels, für das Sie Kaufdaten abrufen. Um die productId Ihres Spiels abzurufen, navigieren Sie im XDP Analytics-Programm zu Ihrem Spiel, und rufen Sie die productId aus der URL ab. Wenn Sie Ihre Kaufdaten aus dem Partner Center-Analysebericht herunterladen, ist die productId auch in der TSV-Datei enthalten. Ja
addonProductId Zeichenfolge Die productId des Add-Ons, für das Sie Kaufdaten abrufen möchten. Ja
startDate Datum Das Startdatum im Datumsbereich der Add-On-Kaufdaten, die abgerufen werden sollen. Die Standardeinstellung ist das aktuelle Datum. Nein
endDate Datum Das Enddatum im Datumsbereich der Add-On-Kaufdaten, die abgerufen werden sollen. Die Standardeinstellung ist das aktuelle Datum. Nein
filter Zeichenfolge Eine oder mehrere Anweisungen, die die Zeilen in der Antwort filtern. Jede Anweisung enthält einen Feldnamen aus dem Antworttext und Wert, die dem eq- oder ne-Operator zugeordnet sind, und Anweisungen können mit und oder oder kombiniert werden. Zeichenfolgenwerte müssen von einfachen Anführungszeichen im Filterparameter umgeben sein. Beispielsweise filter=market eq 'US' und gender eq 'm'.
Sie können die folgenden Felder aus dem Antworttext angeben:
  • acquisitionType
  • Alter
  • storeClient
  • Geschlecht
  • market
  • osVersion
  • deviceType
  • sandboxId
 Nein
aggregationLevel Zeichenfolge Gibt den Zeitraum an, für den aggregierte Daten abgerufen werden sollen. Dies kann eine der folgenden Zeichenfolgen sein: Tag, Woche oder Monat. Wenn keine Angabe erfolgt, lautet der Standardwert Tag. Nein
orderby Zeichenfolge Eine Anweisung, die die Ergebnisdatenwerte für jeden Add-On-Kauf anordnet. Die Syntax ist orderby=Feld [order],Feld [order],... Der Feld-Parameter kann eine der folgenden Zeichenfolgen sein:
  • date
  • acquisitionType
  • Alter
  • storeClient
  • Geschlecht
  • market
  • osVersion
  • deviceType
  • orderName
Der Order-Parameter ist optional und kann asc oder desc sein, um die aufsteigende oder absteigende Reihenfolge für jedes Feld anzugeben. Die Standardeinstellung ist asc.
Hier ist ein Beispiel für eine orderby-Zeichenfolge: orderby=date,market		 Nein
groupby Zeichenfolge Eine Anweisung, die Datenaggregation nur auf die angegebenen Felder anwendet. Sie können die folgenden Felder angeben:
  • date
  • applicationName
  • addonProductName
  • acquisitionType
  • Alter
  • storeClient
  • Geschlecht
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleIdHex
Die zurückgegebenen Datenzeilen enthalten die im groupby Parameter angegebenen Felder sowie folgendes:
  • date
  • applicationId
  • addonProductId
  • acquisitionQuantity
Der Parameter groupby kann mit dem aggregationLevel-Parameter verwendet werden. Zum Beispiel: &groupby=age,market&aggregationLevel=week		 Nein

Beispiel für eine Anfrage

In den folgenden Beispielen werden verschiedene Anforderungen zum Abrufen von Add-On-Kaufdaten veranschaulicht. Ersetzen Sie die Werte addonProductId und applicationId durch die entsprechende Store-ID für Ihr Add-On oder Ihre 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>

Antwort

Antworttext

Wert type BESCHREIBUNG
Wert array Ein Array von Objekten, die aggregierte Add-On-Kaufdaten enthalten. Weitere Informationen zu den Daten in den einzelnen Objekten finden Sie im Abschnitt Add-On-Akquisitionswerte‭ weiter unten.
TotalCount INT Die Gesamtanzahl der Zeilen im Datenergebnis für die Abfrage.

Add-On-Akquisitionswerte‭

Elemente im Value-Array enthalten die folgenden Werte.

Wert type Beschreibung
Datum Zeichenfolge Das erste Datum im Datumsbereich für die Kaufdaten. Wenn die Anforderung einen einzelnen Tag angegeben hat, ist dieser Wert dieses Datum. Wenn die Anforderung eine Woche, einen Monat oder einen anderen Datumsbereich angegeben hat, ist dieser Wert das erste Datum in diesem Datumsbereich.
addonProductId Zeichenfolge Die productId des Add-Ons, für das Sie Kaufdaten abrufen.
addonProductName Zeichenfolge Der Anzeigename des Add-ons. Dieser Wert wird nur in den Antwortdaten angezeigt, wenn der aggregationLevel-Parameter auf Tag festgelegt ist, es sei denn, Sie geben das AddonProductName-Feld im groupby-Parameter an.
applicationId Zeichenfolge Die productId der App, für die Add-On-Kaufdaten abgerufen werden sollen.
applicationName Zeichenfolge Der Anzeigename des Spiels.
deviceType Zeichenfolge Eine der folgenden Zeichenfolgen, die den Gerätetyp angibt, der den Kauf abgeschlossen hat:
  • "PC"
  • "Telefon"
  • "Console-Xbox One"
  • "Console-Xbox Series X"
  • "IoT"
  • "Server"
  • "Tablet"
  • "Holographisch"
  • "Unbekannt"
storeClient Zeichenfolge Eine der folgenden Zeichenfolgen, die die Version des Stores angibt, in der der Kauf erfolgte:
  • "Windows Telefon Store (Client)"
  • "Microsoft Store (Client)" (oder "Windows Store (Client)" bei Abfragen nach Daten vor dem 23. März 2018)
  • "Microsoft Store (Web)" (oder "Windows Store (Web)" bei Abfragen nach Daten vor dem 23. März 2018)
  • "Volumenkauf durch Organisationen"
  • "Sonstiges"
osVersion Zeichenfolge Die Betriebssystemversion, auf der der Kauf erfolgte. Für diese Methode ist dieser Wert immer Windows 10 oder Windows 11".
market Zeichenfolge Der ISO 3166-Ländercode des Marktes, auf dem der Kauf erfolgte.
gender Zeichenfolge Eine der folgenden Zeichenfolgen, die das Geschlecht des Benutzers angibt, der den Kauf getätigt hat:
  • "m"
  • "f"
  • "Unbekannt"
age Zeichenfolge Eine der folgenden Zeichenfolgen, die die Altersgruppe des Benutzers angibt, der den Kauf getätigt hat:
  • "weniger als 13"
  • "13-17"
  • "18-24"
  • "25-34"
  • "35-44"
  • "44-55"
  • "Größer als 55"
  • "Unbekannt"
acquisitionType Zeichenfolge Eine der folgenden Zeichenfolgen, die den Typ des Kaufs angibt:
  • „Free“
  • "Testversion"
  • „Paid“
  • "Angebotscodes"
  • "Iap"
  • "Abonnement Iap"
  • "Private Zielgruppe"
  • "Vorbestellen"
  • "Xbox Game Pass" (oder "Game Pass", wenn die Daten vor dem 23. März 2018 abgefragt werden)
  • "Datenträger"
  • "Prepaid-Code"
  • "Berechnete Vorbestellung"
  • "Stornierte Vorbestellung"
  • "Fehlgeschlagene Vorbestellung"
acquisitionQuantity integer Die Anzahl der erfolgten Käufe.
inAppProductId Zeichenfolge Produkt-ID des Produkts, in dem dieses Add-On verwendet wird.
inAppProductName Zeichenfolge Produktname des Produkts, auf dem dieses Add-On verwendet wird.
paymentInstrumenttype Zeichenfolge Zahlungsinstrumenttyp, der für den Kauf verwendet wird.
sandboxId Zeichenfolge Die für das Spiel erstellte Sandbox-ID. Dies kann der Wert RETAIL oder eine private Sandbox-ID sein.
xboxTitleId Zeichenfolge Xbox-Titel-ID des Produkts aus XDP, falls zutreffend.
localCurrencyCode Zeichenfolge Lokaler Währungscode basierend auf dem Land des Partner Center-Kontos.
xboxProductId Zeichenfolge Xbox-Produkt-ID des Produkts aus XDP, falls zutreffend.
availabilityId Zeichenfolge Verfügbarkeits-ID des Produkts aus XDP, falls zutreffend.
skuId Zeichenfolge SKU-ID des Produkts aus XDP, falls zutreffend.
skuDisplayName Zeichenfolge SKU-Anzeigename des Produkts aus XDP, falls zutreffend.
xboxParentProductId Zeichenfolge Xbox Übergeordnete Produkt-ID des Produkts aus XDP, falls zutreffend.
parentProductName Zeichenfolge Übergeordneter Produktname des Produkts aus XDP, falls zutreffend.
productTypeName Zeichenfolge Produkttypname des Produkts aus XDP, falls zutreffend.
purchaseTaxType Zeichenfolge Einkaufssteuertyp des Produkts aus XDP, falls zutreffend.
purchasePriceUSDAmount Zahl Der vom Kunden für das Add-On gezahlte Betrag, der in USD umgewandelt wird.
purchasePriceLocalAmount Zahl Der vom Kunden für das Add-On gezahlte Betrag in der Währung der Region.
purchaseTaxUSDAmount Zahl Der auf das Add-On angewendete Steuerbetrag, konvertiert in USD.
purchaseTaxLocalAmount Zahl Einkaufssteuer lokaler Betrag des Produkts aus XDP, falls zutreffend.

Beispielantwort

Im folgenden Beispiel wird ein Beispiel für einen JSON-Antworttext für diese Anforderung veranschaulicht.

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