Abrufen von Add-On-Kaufdaten für Ihre Spiele und Apps
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.
Anfordern
Anforderungssyntax
| Methode | Anforderungs-URI |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions |
Anforderungsheader
| Header | Typ | Beschreibung |
|---|---|---|
| Autorisierung | 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 | date | Das Startdatum im Datumsbereich der Add-On-Kaufdaten, die abgerufen werden sollen. Die Standardeinstellung ist das aktuelle Datum. | No |
| endDate | date | Das Enddatum im Datumsbereich der Add-On-Kaufdaten, die abgerufen werden sollen. Die Standardeinstellung ist das aktuelle Datum. | No |
| filter | Zeichenfolge | Eine oder mehrere Anweisungen, die die Zeilen in der Antwort filtern. Jede Anweisung enthält einen Feldnamen aus dem Antwortkörper und einen Wert, die mit den Operatoren eq oder ne verbunden sind, und Anweisungen können mit and oder or 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:
|
No |
| 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. | No |
| 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:
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:
|
No |
Anforderungsbeispiel
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 | Typ | 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 | Typ | 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:
|
| storeClient | Zeichenfolge | Eine der folgenden Zeichenfolgen, die die Version des Stores angibt, in der der Kauf erfolgte:
|
| osVersion | Zeichenfolge | Die Betriebssystemversion, auf der der Kauf erfolgte. Für diese Methode ist dieser Wert immer Windows 10 oder Windows 11". |
| Markt | 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:
|
| age | Zeichenfolge | Eine der folgenden Zeichenfolgen, die die Altersgruppe des Benutzers angibt, der den Kauf getätigt hat:
|
| acquisitionType | Zeichenfolge | Eine der folgenden Zeichenfolgen, die den Typ des Kaufs angibt:
|
| 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
}