Partilhar via

Obter dados de aquisições adicionais para os seus jogos e aplicações

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

Pré-requisitos

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

  • Se ainda não tiver feito isso, complete todos os pré-requisitos e para a API de análise da Microsoft Store.
  • Obtenha um token de acesso do Azure AD para usar no cabeçalho da solicitação para esse método. Depois de obter um token de acesso, você tem 60 minutos para usá-lo antes que ele expire. 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.

Solicitação

Sintaxe da solicitação

Método Solicitar URI
Obtém https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

Cabeçalho da solicitação

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

Parâmetros de solicitação

O parâmetro applicationId ou addonProductId é necessário. Para recuperar dados de aquisição para 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 addonProductId. Se você especificar ambos, o parâmetro applicationId será ignorado.

Parâmetro Tipo Descrição Obrigatório
applicationId corda O productId do jogo Xbox One para o qual você está recuperando dados de aquisição. Para obter o productId do seu jogo, navegue até o seu jogo no Programa XDP Analytics e recupere o productId do URL. Como alternativa, se você baixar os dados de aquisições do relatório de análise do Partner Center, o productId será incluído no arquivo .tsv. Sim
addonProductId corda O productId do complemento para o qual você deseja recuperar dados de aquisição. Sim
data de início data A data de início no intervalo de datas dos dados de aquisição de complementos a recuperar. O padrão é a data atual. Não
data de término data A data final do intervalo de datas dos dados de aquisição de complementos a recuperar. O padrão é a data atual. Não
filtro corda Uma ou mais declarações que filtram as linhas da resposta. Cada instrução contém um nome de campo do corpo da resposta e um valor que estão associados aos operadores eq ou ne, e as instruções podem ser combinadas usando "e" ou "ou". Os valores de cadeia de caracteres devem ser cercados por aspas simples no parâmetro filter. Por exemplo, filter=market eq 'US' e gender eq 'm'.
Você pode especificar os seguintes campos do corpo da resposta:
  • Tipo de Aquisição
  • idade
  • armazenarCliente
  • género
  • mercado
  • osVersão
  • Tipo de dispositivo
  • sandboxId
 Não
Nível de Agregação corda Especifica o intervalo de tempo para o qual recuperar dados agregados. Pode ser uma das seguintes cadeias de caracteres: dia, semanaou mês. Se não for especificado, o valor predefinido é dia. Não
ordenar por corda Uma instrução que classifica os valores dos dados de resultado para cada aquisição adicional. A sintaxe é orderby=field [order],field [order],... O field parâmetro pode ser uma das seguintes strings:
  • data
  • Tipo de Aquisição
  • idade
  • armazenarCliente
  • género
  • mercado
  • osVersão
  • Tipo de dispositivo
  • nomeDoPedido
O parâmetro order é opcional e pode ser asc ou desc para especificar a ordem crescente ou decrescente para cada campo. O padrão é asc.
Aqui está um exemplo orderby string: orderby=date,market		 Não
agrupar por corda Uma instrução que aplica a agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos:
  • data
  • nome_do_aplicativo
  • addonNome do Produto
  • Tipo de Aquisição
  • idade
  • armazenarCliente
  • género
  • mercado
  • osVersão
  • Tipo de dispositivo
  • tipoDeInstrumentoDePagamento
  • sandboxId
  • xboxTitleIdHex
As linhas de dados retornadas conterão os campos especificados no parâmetro groupby , bem como o seguinte:
  • data
  • IdDeAplicação
  • addonProductId
  • quantidade de aquisição
O parâmetro groupby pode ser usado com o parâmetro aggregationLevel. Por exemplo: &groupby=age,market&aggregationLevel=semana		 Não

Exemplo de solicitação

Os exemplos a seguir demonstram várias solicitações para a obtenção de dados de aquisição de complementos. Substitua os valores de addonProductId e applicationId pela ID apropriada da Loja para o 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 conjunto Uma matriz de objetos que contêm dados agregados de aquisição de complementos. Para obter mais informações sobre os dados em cada objeto, consulte a seção valores de aquisição de complementos abaixo.
Contagem total Int O número total de linhas no resultado de dados para a consulta.

Valores de aquisição de complementos

Os elementos na matriz Value contêm os seguintes valores.

Valor Tipo Descrição
data corda A primeira data no intervalo de datas dos dados de aquisição. Se a solicitação especificou um único dia, esse valor será essa data. Se a solicitação especificou uma semana, mês ou outro intervalo de datas, esse valor será a primeira data nesse intervalo de datas.
addonProductId corda O productId do complemento para o qual você está recuperando dados de aquisição.
addonNome do Produto corda O nome a exibir do complemento. Esse valor só aparecerá nos dados de resposta se o parâmetro aggregationLevel estiver definido como dia, a não ser que o campo addonProductName seja especificado no parâmetro groupby.
applicationId corda O productId do aplicativo para o qual você deseja recuperar dados de aquisição de complementos.
Nome da Aplicação corda O nome de exibição do jogo.
Tipo de dispositivo corda Uma das seguintes cadeias de caracteres que especifica o tipo de dispositivo que concluiu a aquisição:
  • Computador
  • Telefone
  • Console-Xbox Um
  • "Console-Xbox Série X"
  • "IoT"
  • Servidor
  • Tablete
  • Holográfico
  • "Desconhecido"
storeClient corda Uma das seguintes cadeias de caracteres que indica a versão da Loja onde ocorreu a aquisição:
  • 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)
  • "Compra em volume por organizações"
  • "Outros"
osVersão corda A versão do SO em que ocorreu a aquisição. Para este método, este valor é sempre Windows 10 ou Windows 11".
mercado corda O código de país ISO 3166 do mercado onde ocorreu a aquisição.
Género corda Uma das seguintes cadeias de caracteres que especifica o gênero do usuário que fez a aquisição:
  • "m"
  • f
  • "Desconhecido"
idade corda Uma das seguintes cadeias de caracteres 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 aquisição corda Uma das seguintes cadeias de caracteres que indica o tipo de aquisição:
  • Grátis
  • "Julgamento"
  • Pago
  • "Código promocional"
  • Iap
  • "Subscrição Iap"
  • "Audiência Privada"
  • Pré-encomenda
  • "Xbox Game Pass" (ou "Game Pass" ao consultar dados antes de 23 de março de 2018)
  • "Disco"
  • "Código pré-pago"
  • "Pré-encomenda cobrada"
  • "Pré-encomenda cancelada"
  • "Pré-encomenda falhada"
quantidade de aquisição número inteiro O número de aquisições que ocorreram.
ID do Produto no App corda ID do produto onde este complemento é usado.
nome do produto no aplicativo corda Nome do produto onde este complemento é usado.
tipo de instrumento de pagamento corda Tipo de instrumento de pagamento utilizado para a aquisição.
sandboxId corda O Sandbox ID criado para o jogo. Pode ser o valor RETAIL ou um ID de sandbox privado.
xboxTitleId corda ID de 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 XDP, se aplicável.
Id de disponibilidade 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 SKU do produto proveniente do XDP, se aplicável.
xboxParentProductId corda Identificador do Produto Pai Xbox do XDP, se aplicável.
nomeDoProdutoPai corda Nome do produto pai do produto da XDP, se aplicável.
nomeDoTipoDeProduto corda Tipo de produto Nome do produto de XDP, se aplicável.
tipoDeImpostoDeCompra corda Tipo de imposto de compra do produto do XDP, se aplicável.
preço de compra USD número O valor pago pelo cliente pelo complemento, convertido em USD.
Montante do preço de compra local número O valor pago pelo cliente pelo complemento, na moeda da região.
MontanteImpostoCompraUSD número O valor do imposto aplicado ao complemento, convertido em USD.
valorLocalImpostoDeCompra número Valor Local do Imposto de Compra do produto do XDP, se aplicável.

Exemplo de resposta

O exemplo a seguir demonstra um corpo de resposta JSON de exemplo 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