Compartilhar via

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

Use esse método na API de análise da Microsoft Store para obter dados agregados de aquisição de complemento 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 da Central de Parceiros da Análise XDP.

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.

Observação

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

Solicitar

Sintaxe da solicitação

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

Cabeçalho da solicitação

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

Parâmetros da solicitação

O parâmetro applicationId ou addonProductId é obrigatório. Para recuperar dados de aquisição de todos os complementos registrados no aplicativo, especifique o parâmetro applicationId. Para recuperar dados de aquisição de um único complemento, especifique o parâmetro inAppProductId. Se você especificar ambos, o parâmetro applicationId será ignorado.

Parâmetro Tipo Descrição Obrigatório
ID do aplicativo corda O productId do jogo do Xbox One cujos dados de aquisição você está recuperando. Para obter o productId do seu jogo, navegue até o jogo no Programa de Análise XDP e recupere o productId pela URL. Como alternativa, se você fizer download dos dados de aquisições pelo relatório de análise da Central de Parceiros, o productId será incluído no arquivo .tsv. Sim
ID do Produto Adicional corda O productId do complemento cujos dados de aquisição você deseja recuperar. Sim
Data de Início data A data de início no intervalo de datas dos dados de aquisição do complemento a serem recuperados. O padrão é a data atual. Não
data de término data A data de término no intervalo de datas dos dados de aquisição do complemento a serem recuperados. O padrão é a data atual. Não
filtro corda Uma ou mais instruçõ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 corda 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 corda Uma instrução que ordena os valores dos dados de resultado para cada aquisição de complemento. 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
  • nome do pedido
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
groupby corda Uma instrução que aplica agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos:
  • data
  • nome_do_aplicativo
  • addonProductName
  • tipoDeAquisicao
  • idade
  • storeClient
  • Gênero
  • mercado
  • OSVersion
  • tipoDeDispositivo
  • paymentInstrumentType
  • sandboxId
  • xboxTitleIdHex
As linhas de dados retornadas conterão os campos especificados no parâmetro groupby, bem como:
  • data
  • ID do aplicativo
  • ID do produto adicional
  • 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

Os exemplos a seguir demonstram várias solicitações para obter dados de aquisição de complemento. Substitua os valores addonProductId e applicationId pela ID da Store apropriada para seu complemento ou aplicativo.

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>

Resposta

Corpo da resposta

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

Valores de aquisição de complementos

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

Valor Tipo Descrição
data corda A primeira data no intervalo de datas para os 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 Produto Adicional corda O productId do complemento cujos dados de aquisição você está recuperando.
NomeDoProdutoComplemento corda O nome de exibição do complemento. Esse valor só será exibido nos dados de resposta se o parâmetro aggregationLevel estiver definido como day, a menos que você especifique o campo addonProductName no parâmetro groupby.
ID do aplicativo corda O productId do aplicativo cujos dados de aquisição de complemento você deseja recuperar.
Nome do aplicativo corda O nome de exibição do jogo.
tipo de dispositivo corda Uma das seguintes sequências que especifica o tipo de dispositivo que concluiu a aquisição:
  • "Computador"
  • "Telefone"
  • Console-Xbox Um
  • "Console-Xbox Série X"
  • "IoT"
  • "Servidor"
  • Tablet
  • "Holográfico"
  • "Desconhecido"
storeClient corda Uma das seguintes sequências que indica a versão da Store na qual a aquisição ocorreu:
  • "Loja do Windows Phone (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”
  • "Outro"
osVersion corda A versão do sistema operacional em que a aquisição ocorreu. Para esse método, esse valor é sempre Windows 10 ou Windows 11".
mercado corda O código de país ISO 3166 do mercado no qual a aquisição ocorreu.
Gênero corda Uma das seguintes sequências que especifica o gênero do usuário que fez a aquisição:
  • "m"
  • f
  • "Desconhecido"
idade corda 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
  • "mais de 55"
  • "Desconhecido"
Tipo de aquisição corda Uma das seguintes sequências que indica o tipo de aquisição:
  • "Gratuito"
  • “Avaliação”
  • "Pago"
  • “Código de promoção”
  • Iap
  • "Iap de assinatura"
  • "Público-alvo privado"
  • "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”
quantidade de aquisição Número inteiro O número de aquisições ocorridas.
ID do Produto In-App corda ID do produto (product ID) em que esse complemento é usado.
inAppProductName corda Nome do produto em que esse complemento é usado.
tipoDeInstrumentoDePagamento corda Tipo de instrumento de pagamento utilizado para a aquisição.
sandboxId corda A ID da área restrita criada para o jogo. Esse pode ser o valor RETAIL ou uma ID de área restrita privada.
xboxTitleId corda ID do título do Xbox do produto do XDP, se aplicável.
localCurrencyCode corda Código de moeda local com base no país/região da conta do Partner Center.
xboxProductId corda ID do Produto Xbox do produto XDP, se aplicável.
identificadorDeDisponibilidade corda ID de disponibilidade do produto do XDP, se aplicável.
skuId corda ID de SKU do produto do XDP, se aplicável.
skuDisplayName corda Nome de exibição da SKU do produto do XDP, se aplicável.
xboxParentProductId corda ID do produto pai Xbox do produto do XDP, se aplicável.
nomeDoProdutoPai corda Nome do produto pai do produto do XDP, se aplicável.
nomeDoTipoDeProduto corda Nome do tipo de produto do produto do XDP, se aplicável.
tipoDeImpostoDeCompra corda Tipo de imposto de compra do produto do XDP, se aplicável.
valor do preço de compra em USD número O valor pago pelo cliente pelo complemento, convertido em USD.
valorLocalDoPreçoDeCompra número O valor pago pelo cliente pelo complemento, na moeda da região.
valorImpostoCompraUSD número O valor do imposto aplicado ao complemento, convertido em USD.
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": [ 
    { 
            "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