Compartilhar via

Obter uso do aplicativo mensalmente

Use esse método na API de análise da Microsoft Store para obter dados de uso agregados (sem incluir Xbox para múltiplos jogadores) em formato JSON para um aplicativo durante um determinado intervalo de datas (somente os últimos 90 dias) e outros filtros opcionais. Essas informações também estão disponíveis no relatório Uso no Partner Center.

A telemetria para aplicativos PWA baseados em Anaheim é coletada no nível do dispositivo. Portanto, as métricas relacionadas aos usuários não estarão disponíveis para esses produtos. Veja a seção Valores de uso a seguir para obter mais detalhes sobre a validade dos campos.

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 para a API de análise da Microsoft Store.
  • Obtenha um token de acesso do Azure AD a ser usado no cabeçalho de 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.

Solicitar

Sintaxe da solicitação

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

Cabeçalho da solicitação

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

Parâmetros da solicitação

Parâmetro Tipo Descrição Obrigatório
ID do aplicativo cadeia de caracteres A ID da Store do aplicativo para o qual você deseja recuperar dados de revisão. Sim
Data de Início data A data de início no intervalo de datas dos dados de revisão 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 revisão a serem recuperados. O padrão é a data atual. Não
Início int O número de linhas de dados a serem retornadas na solicitação. O valor máximo e padrão, se não for especificado, será 10.000. Se houver mais linhas na consulta, o corpo da resposta incluirá um proximo link que você poderá usar para solicitar a próxima página de dados. Não
pular int O número de linhas a serem ignoradas na consulta. Use esse parâmetro para percorrer grandes conjuntos de dados. Por exemplo, top=10000 e skip=0 recupera as primeiras 10.000 mil linhas de dados, top=10000 e skip=10000 recupera as próximas dez mil linhas de dados, e assim por diante. Não
filtro cadeia de caracteres 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. Você pode especificar os seguintes campos no corpo da resposta:
  • mercado
  • tipoDeDispositivo
  • Versão do pacote
 Não
pedido por cadeia de caracteres Uma instrução que ordena os valores dos dados de resultado. A sintaxe é orderby=field [order],field [order],.... O parâmetro campo pode ser uma das seguintes caracteres:
  • data
  • ID do aplicativo
  • nome_do_aplicativo
  • mercado
  • Versão do pacote
  • tipoDeDispositivo
  • nome_da_assinatura
  • monthlySessionCount
  • duracaoDoEngajamentoMinutos
  • usuários ativos mensais
  • monthlyActiveDevices
  • novos usuários mensais
  • usuários ativos diários médios
  • dispositivos ativos diários médios
  • mensalNewDevices

O parâmetro order é opcional e pode ser asc ou desc para especificar ordem crescente ou decrescente para cada campo. O padrão é asc.

Aqui está um exemplo de string orderby: orderby=date,market

 Não
groupby cadeia de caracteres Uma instrução que aplica agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos no corpo da resposta:
  • nome_do_aplicativo
  • nome_da_assinatura
  • tipoDeDispositivo
  • Versão do pacote
  • mercado
  • data

As linhas de dados retornadas conterão os campos especificados no parâmetro groupby , bem como o seguinte:

  • ID do aplicativo
  • nome_da_assinatura
  • monthlySessionCount
  • duracaoDoEngajamentoMinutos
  • usuários ativos mensais
  • monthlyActiveDevices
  • novos usuários mensais
  • usuários ativos diários médios
  • dispositivos ativos diários médios
  • mensalNewDevices

O parâmetro groupby pode ser usado com o parâmetro aggregationLevel . Por exemplo: &groupby=ageGroup,market&aggregationLevel=week

 Não

Exemplo de solicitação

O exemplo a seguir demonstra uma solicitação para a obtenção de dados de uso mensal de aplicativos. Substitua o valor applicationId pela ID da Loja para seu aplicativo.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=XXXXXXXXXXXX&startDate=2018-06-01&endDate=2018-07-01 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 uso agregados. Para obter mais informações sobre os dados em cada objeto, consulte a tabela a seguir.
@nextLink cadeia de caracteres Se houver páginas adicionais de dados, essa sequência conterá um URI que você poderá usar para solicitar a próxima página de dados. Por exemplo, esse valor será retornado se o parâmetro superior da solicitação for definido como 10000, mas houver mais de 10.000 linhas de dados de revisões para a consulta.
ContagemTotal int O número total de linhas no resultado de dados da consulta.

 

Valores de uso

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

Valor Tipo Descrição Disponibilidade da UWP Disponibilidade do PWA baseado em Anaheim Disponibilidade do Xbox
data cadeia de caracteres A primeira data no intervalo de datas para os dados de uso. 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. Sim Sim Sim
ID do aplicativo cadeia de caracteres O ID da Store do aplicativo para o qual você está recuperando os dados de uso. Sim Sim Sim
Nome do aplicativo cadeia de caracteres O nome de exibição do aplicativo. Sim Sim Sim
mercado cadeia de caracteres O código de país ISO 3166 do mercado no qual o cliente usou o seu aplicativo. Sim Sim Sim
versão do pacote cadeia de caracteres A versão do pacote em que o uso ocorreu. Sim Sim Não
tipo de dispositivo cadeia de caracteres Uma das seguintes sequências que especifica o tipo de dispositivo em que o uso ocorreu:
  • Computador pessoal
  • Telefone
  • Console-Xbox Um
  • SérieConsole-Xbox X
  • Tabuleta
  • Muito
  • Servidor
  • Holográfico
  • Desconhecido
 Sim Sim Sim
Nome da Assinatura cadeia de caracteres Indica se o uso foi por meio do Xbox Game Pass. Sim Não Não
contagemMensalDeSessoes longo O número de sessões de usuário durante esse mês. Sim Sim Sim
duraçãoDoEngajamentoMinutos duplo Os minutos em que os usuários estão usando ativamente o seu aplicativo, medidos por um período distinto, começando quando o aplicativo é iniciado (início do processo) e terminando quando ele finaliza (fim do processo) ou após um período de inatividade. Sim Sim Sim
usuários ativos mensais longo O número de clientes que usaram o aplicativo naquele mês. Sim Não Sim
dispositivosAtivosMensalmente longo O número de dispositivos que estão executando o seu aplicativo, para um período distinto, começando quando o aplicativo é iniciado (início do processo) e terminando quando ele finaliza (fim do processo) ou após um período de inatividade. Sim Sim Sim
novosUsuáriosMensais longo O número de clientes que usaram o seu aplicativo pela primeira vez naquele mês. Sim Não Sim
usuários ativos diários médios duplo O número médio de clientes que usam o aplicativo diariamente. Sim Não Sim
dispositivos ativos diários médios duplo O número de dispositivos diários usados para interagir com o seu aplicativo por todos os usuários, mensalmente. Sim Sim Sim
novos dispositivos mensais longo O número de dispositivos que usaram o aplicativo pela primeira vez naquele mês. Não Sim Não

Observação

Se um campo for inválido para um produto específico, o valor para esses campos será enviado como 0 ou nulo na resposta. A computação de novos usuários e novos dispositivos é feita com a janela contínua de 3 anos, ou seja, se um usuário/dispositivo não usar o aplicativo por 3 anos ou mais, ele será tratado como novo usuário/dispositivo após 3 anos.

Exemplo de solicitação e resposta

Os snippets de código a seguir demonstram alguns exemplos de solicitações e o corpo da resposta JSON para estas solicitações.

Solicitação de Exemplo

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

Resposta de exemplo

{
    "Value": [
        {
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "deviceType": "All",
            "packageVersion": "All",
            "market": "All",
            "engagementDurationMinutes": 2828568.3,
            "monthlyActiveUsers": 165249,
            "monthlyActiveDevices": 165753,
            "monthlyNewUsers": 95787,
            "monthlySessionCount": 314263,
            "averageDailyActiveUsers": 192.506111111111,
            "averageDailyActiveDevices": 191.199722222222,
            "monthlyNewDevices": 0
        }
    ],
    "TotalCount": 1
}

Solicitação de Exemplo

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=9NBLGGGZ5QDR&startDate=2022-06-01&endDate=2022-07-01&groupby=applicationName,subscriptionName,deviceType,packageVersion,market,date&top=10&skip=0
HTTP/1.1
Authorization: Bearer <your access token>

Resposta de exemplo

{
    "Value": [
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "JP",
            "engagementDurationMinutes": 0.3,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "MX",
            "engagementDurationMinutes": 2.7,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "Unknown",
            "engagementDurationMinutes": 0.1,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "US",
            "engagementDurationMinutes": 0.2,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AE",
            "engagementDurationMinutes": 3.2,
            "monthlyActiveUsers": 2,
            "monthlyActiveDevices": 2,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 3,
            "averageDailyActiveUsers": 0.07,
            "averageDailyActiveDevices": 0.07,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AO",
            "engagementDurationMinutes": 1.2,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AR",
            "engagementDurationMinutes": 574.7,
            "monthlyActiveUsers": 39,
            "monthlyActiveDevices": 39,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 53,
            "averageDailyActiveUsers": 1.43,
            "averageDailyActiveDevices": 1.43,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AT",
            "engagementDurationMinutes": 5.3,
            "monthlyActiveUsers": 4,
            "monthlyActiveDevices": 4,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 9,
            "averageDailyActiveUsers": 0.17,
            "averageDailyActiveDevices": 0.17,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AU",
            "engagementDurationMinutes": 434.7,
            "monthlyActiveUsers": 22,
            "monthlyActiveDevices": 22,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 36,
            "averageDailyActiveUsers": 0.9,
            "averageDailyActiveDevices": 0.9,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AZ",
            "engagementDurationMinutes": 13.5,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        }
    ],
    "TotalCount": 10
}
  • Last updated on