Compartilhar via

Obter dados de aquisições para seus jogos e aplicativos

Use esse método na API de análise da Microsoft Store para obter dados de aquisição agregados no formato JSON para aplicativos UWP e jogos do Xbox One que foram ingeridos por meio do Portal do Desenvolvedor do Xbox (XDP) e estão disponíveis no painel de Análise XDP.

Observação

Esta API não fornece dados agregados diários antes de 1º de outubro de 2016.

Pré-requisitos

Para usar este método, primeiro você precisa fazer o seguinte:

  • Se você ainda não fez isso, conclua todos os pré-requisitos da API de análise da Microsoft Store.
  • Obtenha um token de acesso do Azure AD a ser usado no cabeçalho da solicitação para esse método. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá obter um novo.

Solicitação

Sintaxe da solicitação

Método URI de solicitação
OBTER https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions

Cabeçalho da solicitação

Cabeçalho Tipo Descrição
Autorização cadeia de caracteres Obrigatória. O token de acesso do Azure AD no formato Bearer<token>.

Parâmetros da solicitação

Parâmetro Tipo Descrição Obrigatório
ID do aplicativo cadeia de caracteres A ID do produto (product ID) do jogo do Xbox One cujos dados de aquisição você está recuperando. Para obter a ID do produto do seu jogo, navegue até o jogo no Programa de Análise XDP e recupere a ID do produto pela URL. Como alternativa, se você fizer download dos dados de aquisições no relatório de análise da Central de Parceiros, a ID do produto será incluída no arquivo .tsv. Sim
Data de Início data A data de início no intervalo de datas dos dados de aquisição a serem recuperados. O padrão é a data atual. Não
data de término data A data de término do intervalo de datas dos dados de aquisição a serem recuperados. O padrão é a data atual. Não
filtro cadeia de caracteres Uma ou mais declarações que filtram as linhas na resposta. Cada instrução contém um nome de campo do corpo da resposta e um valor associados aos operadores eq ou ne, e as instruções podem ser combinadas usando and ou or. Os valores de sequência devem estar entre aspas simples no parâmetro filter. Por exemplo, filter=market eq 'US' and gender eq 'm'.
Você pode especificar os seguintes campos no corpo da resposta:
  • tipoDeAquisicao
  • idade
  • storeClient
  • Gênero
  • mercado
  • OSVersion
  • tipoDeDispositivo
  • sandboxId
 Não
nível de agregação cadeia de caracteres Especifica o intervalo de tempo cujos dados agregados serão recuperados. Pode ser uma das seguintes sequências: dia, semana ou mês. Se não for especificado, o padrão será dia. Não
pedido por cadeia de caracteres Uma instrução que ordena os valores dos dados de resultado para cada aquisição. A sintaxe é orderby=field [order],field [order],... O parâmetro field pode ser uma das seguintes sequências:
  • data
  • tipoDeAquisicao
  • idade
  • storeClient
  • Gênero
  • mercado
  • OSVersion
  • tipoDeDispositivo
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
O parâmetro order é opcional e pode ser asc ou desc para especificar ordem ascendente ou descendente para cada campo. O padrão é asc. Este é um exemplo de sequência orderby: orderby=date,market		 Não
AGRUPARPOR cadeia de caracteres Uma instrução que aplica agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos:
  • data
  • nome_do_aplicativo
  • tipoDeAquisicao
  • idade
  • storeClient
  • Gênero
  • mercado
  • OSVersion
  • tipoDeDispositivo
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
As linhas de dados retornadas conterão os campos especificados no parâmetro groupby, bem como:
  • data
  • ID do aplicativo
  • quantidadeDeAquisicao
O parâmetro groupby pode ser usado com o parâmetro aggregationLevel. Por exemplo: &groupby=age,market&aggregationLevel=week		 Não

Exemplo de solicitação

O exemplo a seguir demonstra várias solicitações para obter dados de aquisição de jogos do Xbox One. Substitua o valor applicationId pela ID do produto (product ID) do seu jogo.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&top=10&skip=0 HTTP/1.1 
Authorization: Bearer <your access token> 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&skip=0&filter=market eq 'US' and gender eq 'm' HTTP/1.1 
Authorization: Bearer <your access token>

Resposta

Corpo da resposta

Valor Tipo Descrição
Valor matriz Uma matriz de objetos que contêm dados de aquisição agregados para o jogo. Para obter mais informações sobre os dados em cada objeto, consulte a seção Valores de aquisição abaixo.
ContagemTotal Número inteiro O número total de linhas no resultado de dados da consulta.

Valores de aquisição

Os elementos na matriz Value contêm os valores a seguir.

Valor Tipo Descrição
data cadeia de caracteres A primeira data no intervalo de datas dos dados de aquisição. Se a solicitação tiver especificado um único dia, esse valor será essa data. Se a solicitação tiver especificado uma semana, um mês ou outro intervalo de datas, esse valor será a primeira data nesse intervalo de datas.
ID do aplicativo cadeia de caracteres A ID do produto (product ID) do jogo do Xbox One cujos dados de aquisição você está recuperando.
nomeDoAplicativo cadeia de caracteres O nome de exibição do jogo.
Tipo de aquisição cadeia de caracteres Uma das seguintes sequências que indicam o tipo de aquisição:
  • Gratuito
  • Avaliação
  • Pago
  • Código de promoção
  • Iap
  • Iap de assinatura
  • Audiência Privada
  • Pré-venda
  • Xbox Game Pass (ou Game Pass se estiver consultando dados antes de 23 de março de 2018)
  • Disco
  • Código pré-pago
  • Pré-venda cobrada
  • Pré-venda cancelada
  • Pré-venda com falha
idade cadeia de caracteres Uma das seguintes sequências que indica a faixa etária do usuário que fez a aquisição:
  • Menos de 13
  • 13-17
  • 18-24
  • 25-34
  • 35-44
  • 44-55
  • Superior a 55
  • Desconhecido
tipo de dispositivo cadeia de caracteres Uma das seguintes sequências que especifica o tipo de dispositivo que concluiu a aquisição:
  • Computador
  • Telefone
  • Console-Xbox Um
  • SérieConsole-Xbox X
  • Muito
  • Servidor
  • Tabuleta
  • Holográfico
  • Desconhecido
gênero cadeia de caracteres Uma das seguintes sequências que especifica o gênero do usuário que fez a aquisição:
  • m
  • f
  • Desconhecido
mercado cadeia de caracteres O código de país ISO 3166 do mercado no qual a aquisição ocorreu.
osVersion cadeia de caracteres A versão do sistema operacional em que a aquisição ocorreu. Para esse método, esse valor é sempre Windows 10 ou Windows 11.
tipoDeInstrumentoDePagamento cadeia de caracteres Uma das seguintes sequências que indica a instrução de pagamento usada para a aquisição:
  • Cartão de crédito
  • Cartão de débito direto
  • Compra inferida
  • Saldo MS
  • Operadora móvel
  • Transferência bancária online
  • PayPal
  • Transação dividida
  • Resgate de token
  • Valor zero pago
  • eWallet
  • Desconhecido
sandboxId cadeia de caracteres A ID da área restrita criada para o jogo. Esse pode ser o valor RETAIL ou uma ID de área restrita privada.
storeClient cadeia de caracteres Uma das seguintes sequências que indica a versão da Store na qual a aquisição ocorreu:
  • Windows Phone Store (aplicativo cliente)
  • Microsoft Store (cliente) (ou Windows Store (cliente) se estiver consultando dados antes de 23 de março de 2018)
  • Microsoft Store (Web) (ou Windows Store (Web) se estiver consultando dados antes de 23 de março de 2018)
  • Aquisição de volume por organizações
  • Outras
xboxTitleId cadeia de caracteres O ID do título do Xbox Live (representado em valor hexadecimal) atribuído pelo Portal do Desenvolvedor do Xbox (XDP) para jogos compatíveis com o Xbox Live.
quantidade de aquisição número O número de aquisições que ocorreram durante o nível de agregação especificado.
valor do preço de compra em USD número O valor pago pelo cliente pela aquisição, convertido para USD, utilizando a taxa de câmbio mensal.
valorImpostoCompraUSD número O valor do imposto aplicado à aquisição, convertido em USD.
localCurrencyCode cadeia de caracteres Código de moeda local com base no país/região da conta do Partner Center.
xboxProductId cadeia de caracteres ID do Produto Xbox do produto XDP, se aplicável.
identificadorDeDisponibilidade cadeia de caracteres ID de disponibilidade do produto do XDP, se aplicável.
skuId cadeia de caracteres ID de SKU do produto do XDP, se aplicável.
skuDisplayName cadeia de caracteres Nome de exibição do SKU do produto do XDP, se aplicável.
xboxParentProductId cadeia de caracteres ID do produto pai Xbox do produto do XDP, se aplicável.
nomeDoProdutoPai cadeia de caracteres Nome do produto pai do produto do XDP, se aplicável.
nomeTipoProduto cadeia de caracteres Nome do tipo de produto do XDP, se aplicável.
tipoDeImpostoDeCompra cadeia de caracteres Tipo de imposto de compra do produto do XDP, se aplicável.
valorLocalDoPreçoDeCompra número Preço de compra local do produto da XDP, se aplicável.
valorLocalImpostoCompra número Valor local do imposto de compra do produto do XDP, se aplicável.

Exemplo de resposta

Veja a seguir um exemplo de corpo de resposta JSON para essa solicitação.

{ 
    "Value": [ 
        { 
            "date": "2019-01-15T01:00:00.0000000Z", 
            "applicationId": "9WZDNCRFHXHT", 
            "applicationName": null, 
            "acquisitionType": "Paid", 
            "age": null, 
            "deviceType": "Phone", 
            "gender": null, 
            "market": "US", 
            "osVersion": "Windows 11", 
            "paymentInstrumentType": null, 
            "sandboxId": "RETAIL", 
            "storeClient": "Microsoft Store (client)", 
            "xboxTitleId": null, 
            "localCurrencyCode": "USD", 
            "xboxProductId": null, 
            "availabilityId": "B42LRTSZ2MCJ", 
            "skuId": "0010", 
            "skuDisplayName": null, 
            "xboxParentProductId": null, 
            "parentProductName": null, 
            "productTypeName": "Game", 
            "purchaseTaxType": "TaxesNotIncluded", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 3.08, 
            "purchasePriceLocalAmount": 3.08, 
            "purchaseTaxUSDAmount": 0.09, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null,
    
    "TotalCount": 12221 
}

 

  • Last updated on