Compartir a través de

Obtener datos de adquisiciones de complementos para sus aplicaciones y juegos

Usa este método en la API de análisis de Microsoft Store para obtener datos agregados de adquisición de complementos en formato JSON para aplicaciones para UWP y juegos de Xbox One que se ingieren a través del Portal para desarrolladores de Xbox (XDP) y están disponibles en el panel del Centro de partners de XDP Analytics.

Requisitos previos

Para usar este método, primero debes hacer lo siguiente:

  • Si aún no lo has hecho, completa todos los requisitos previos de la API de análisis de Microsoft Store.
  • Obtenga un token de acceso a Azure AD para utilizarlo en el encabezado de solicitud de este método. Una vez que haya obtenido un token de acceso, tiene 60 minutos para usarlo antes de que expire. Una vez que expire el token, puede obtener uno nuevo.

Nota

Esta API no proporciona datos agregados diarios de antes del 1 de octubre de 2016.

Solicitud

Sintaxis de la solicitud

Método URI de solicitud
OBTENER https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

Encabezado de solicitud

Encabezado Tipo Descripción
Autorización cadena Necesario. Token de acceso de Azure AD con el formato Portador<token>.

Parámetros de solicitud

El parámetro applicationId o addonProductId es obligatorio. Para recuperar los datos de adquisición de todos los complementos registrados en la aplicación, especifica el parámetro applicationId. Para recuperar los datos de adquisición de un único complemento, especifica el parámetro addonProductId. Si especificas ambos, se omite el parámetro applicationId.

Parámetro Tipo Descripción Obligatorio
applicationId cadena productId del juego de Xbox One para el que estás recuperando datos de adquisición. Para obtener el productId del juego, ves hasta el juego en el programa de análisis XDP y recupera el productId de la dirección URL. Como alternativa, si descargas los datos de adquisiciones del informe de análisis del Centro de partners, el productId está incluido en el archivo .tsv. Sí
id_producto_adicional cadena productId del complemento para el que se desean recuperar los datos de adquisición. Sí
Fecha de inicio fecha Fecha de inicio del intervalo de fechas de los datos de adquisición de complementos que se van a recuperar. La fecha actual es el valor predeterminado. No
fecha de finalización fecha Fecha de finalización del intervalo de fechas de los datos de adquisición de complementos que se van a recuperar. La fecha actual es el valor predeterminado. No
filtro cadena Una o varias instrucciones que filtran las filas de la respuesta. Cada instrucción contiene un nombre de campo del cuerpo de la respuesta y el valor que están asociados a los operadores eq o ne, y las instrucciones se pueden combinar mediante y u o. Los valores de cadena deben estar entre comillas simples en el parámetro de filtro. Por ejemplo, filter=market eq 'US' and gender eq 'm'.
Puedes especificar los campos siguientes desde el cuerpo de la respuesta:
  • tipo de adquisición
  • Edad
  • storeClient
  • género
  • mercado
  • versión del sistema operativo
  • tipoDeDispositivo
  • sandboxId
 No
nivel de agregación cadena Especifica el intervalo de tiempo para el que se van a recuperar los datos agregados. Puede ser una de las siguientes cadenas: día, semana o mes. Si no se especifica nada, el valor predeterminado es día. No
Ordenar por cadena Instrucción que ordena los valores de datos de resultados para cada adquisición de un complemento. La sintaxis es orderby=field [order],field [order],.... El parámetro field puede estar formado por una de las siguientes cadenas:
  • fecha
  • tipo de adquisición
  • Edad
  • storeClient
  • género
  • mercado
  • versión del sistema operativo
  • tipoDeDispositivo
  • nombre del pedido
El parámetro order es opcional y puede ser asc o desc para especificar el orden ascendente o descendente de cada campo. El valor predeterminado es asc.
Este es un ejemplo de cadena orderby: orderby=date,market		 No
groupby cadena Instrucción que aplica la agregación de datos solo a los campos especificados. Puedes especificar los siguientes campos:
  • fecha
  • Nombre de la aplicación
  • addonProductName
  • tipo de adquisición
  • Edad
  • storeClient
  • género
  • mercado
  • versión del sistema operativo
  • tipoDeDispositivo
  • tipoDeInstrumentoDePago
  • sandboxId
  • xboxTitleIdHex
Las filas de datos devueltas contendrán los campos especificados en el parámetro groupby, además de los siguientes:
  • fecha
  • Id de la aplicación
  • addonProductId
  • cantidadDeAdquisición
El parámetro groupby se puede usar con el parámetro aggregationLevel. Por ejemplo: &groupby=age,market&aggregationLevel=week		 No

Ejemplo de solicitud

En los ejemplos siguientes se muestran varias solicitudes para obtener datos de adquisición de complementos. Reemplaza los valores addonProductId y applicationId por el Id. de Store adecuado del complemento o la aplicación.

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>

Respuesta

Cuerpo de la respuesta

Importancia Tipo Descripción
Importancia arreglo Matriz de objetos que contienen datos de adquisición de complementos agregados. Para obtener más información sobre los datos de cada objeto, consulta la sección valores de adquisición de complementos a continuación.
Conteo Total entero Número total de filas que figura en el resultado de datos de la consulta.

Valores de adquisición de complementos

Los elementos de la matriz Value contienen los valores siguientes.

Importancia Tipo Descripción
fecha cadena La primera fecha del intervalo de fechas de los datos de adquisición. Si la solicitud especificaba un solo día, este valor es esa fecha. Si la solicitud especificaba una semana, un mes u otro intervalo de fechas, este valor es la primera fecha de ese intervalo de fechas.
id_producto_adicional cadena productId del complemento para el que se recuperan los datos de adquisición.
nombreDeProductoComplementario cadena Nombre para mostrar del complemento. Este valor solo aparece en los datos de respuesta si el parámetro aggregationLevel se configura como día, a menos que se especifique el campo addonProductName en el parámetro groupby.
applicationId cadena productId de la aplicación para la que se desean recuperar los datos de adquisición de complementos.
Nombre de la aplicación cadena Nombre para mostrar del juego.
tipo de dispositivo cadena Una de las siguientes cadenas que especifica el tipo de dispositivo que completó la adquisición:
  • Ordenador personal
  • "Teléfono"
  • "Consola-Xbox One"
  • "Consola-Xbox Series X"
  • "IoT"
  • "Servidor"
  • "Tableta"
  • "Holográfico"
  • "Desconocido"
storeClient cadena Una de las siguientes cadenas que indica la versión de Store desde la que se produjo la adquisición:
  • "Tienda de Windows Phone (cliente)"
  • "Microsoft Store (cliente)" (o "Windows Store (cliente)" si se consultan datos de antes del 23 de marzo de 2018)
  • "Microsoft Store (web)" (o "Windows Store (web)" si se consultan datos de antes del 23 de marzo de 2018)
  • "Compra por volumen por parte de organizaciones"
  • "Otros"
osVersion cadena Versión del sistema operativo en la que se produjo la adquisición. Para este método, este valor siempre es Windows 10 o Windows 11".
mercado cadena El código de país ISO 3166 del mercado en el que se produjo la adquisición.
género cadena Una de las siguientes cadenas que especifica el género del usuario que realizó la adquisición:
  • "m"
  • f
  • "Desconocido"
edad cadena Una de las siguientes cadenas que indica el grupo de edad del usuario que realizó la adquisición:
  • "Menor de 13"
  • "13-17"
  • "18-24"
  • 25-34
  • "35-44"
  • 44-55
  • "mayor de 55"
  • "Desconocido"
tipo de adquisición cadena Una de las siguientes cadenas que indica el tipo de adquisición:
  • "Gratis"
  • "Prueba"
  • "De pago"
  • "Código promocional"
  • Iap
  • "Iap de suscripción"
  • "Audiencia privada"
  • "Pedido por adelantado"
  • "Xbox Game Pass" (o "Game Pass" si se consultan datos de antes del 23 de marzo de 2018)
  • "Disco"
  • "Código de prepago"
  • "Pedido por adelantado pagado"
  • "Pedido por adelantado cancelado"
  • "Pedido por adelantado erróneo"
cantidadDeAdquisición entero Número de adquisiciones que se produjeron.
inAppProductId (ID de producto en la aplicación) cadena Id. de producto del producto en el que se usa este complemento.
NombreDeProductoEnLaAplicación cadena Nombre del producto en el que se usa este complemento.
Tipo de instrumento de pago cadena Tipo de instrumento de pago utilizado para la adquisición.
sandboxId cadena Identificador del espacio aislado creado para el juego. Puede ser el valor RETAIL o un identificador de espacio aislado privado.
xboxTitleId cadena Id. de título de Xbox del producto de XDP, si procede.
código de moneda local cadena Código de moneda local basado en el país/región de la cuenta del Centro de partners.
xboxProductId cadena Id. de producto de Xbox del producto de XDP, si procede.
identificadorDeDisponibilidad cadena Identificador de disponibilidad del producto de XDP, si procede.
skuId cadena Identificador de SKU del producto de XDP, si procede.
skuDisplayName cadena Nombre para mostrar del SKU del producto de XDP, si procede.
xboxParentProductId cadena Id. de producto primario de Xbox del producto de XDP, si procede.
nombreDelProductoPrincipal cadena Nombre del producto primario del producto de XDP, si procede.
nombreDelTipoDeProducto cadena Nombre del tipo de producto del producto de XDP, si procede.
tipoDeImpuestoDeCompra cadena Tipo de impuesto sobre las ventas del producto de XDP, si procede.
precioDeCompraMontoUSD número El importe pagado por el cliente por el complemento, convertido a USD.
montoLocalDelPrecioDeCompra número El importe pagado por el cliente por el complemento, en la moneda de la región.
impuestoDeCompraMontoUSD número Importe de los impuestos aplicados al complemento, convertido a USD.
monto local del impuesto de compra número Importe local del impuesto sobre las ventas del producto de XDP, si procede.

Ejemplo de respuesta

En el ejemplo siguiente se muestra un ejemplo de cuerpo de respuesta en formato JSON para esta solicitud.

{ 
  "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 
}
  • Last updated on