Complete guide about Windows Store Analytics API with Sample Code

Dev Center released the Windows Store analytics API, which provides analytics information for your Windows Store apps without requiring logging into Dev Center. Using a REST API you can retrieve the same information you see in Dev Center for app and in-app purchase acquisitions, ratings and reviews, as well as app health.

Prerequisites for using the Windows Store analytics API

1. The Windows Store analytics API requires an Azure Active Directory (Azure AD) account that is associated with your Dev Center account. If you already use Office 365 or other business services from Microsoft, you already have Azure AD directory. Otherwise, you can get one for free.

2. You must have a user account in the Azure AD directory that you want to associate with your Windows Dev Center account.

Using the Windows Store analytics API

Before you can use the Windows Store analytics API, you must associate an Azure AD application with your Dev Center account and obtain an Azure AD access token.

To obtain an Azure AD access token:

1. Associate an Azure AD application with your Dev Center account.

• Under Manage users in Account settings in Dev Center, click Add Azure AD applications. If the application already exists in your Azure AD, select it. If not, click New Azure AD application and enter the required field values.

  

  • Reply URL: Enter the Reply URL for the new Azure AD application. This is the URL where users can sign in and use your Azure AD application. To find the application’s reply URL, in the Azure Management Portal, click Active Directory, click the directory, and then click the application, and then click Configure. The Reply URL field is in the Single Sign-on section of the Configure page.

  • App ID URI: enter a URL in this format:

         https://YOURTENANTNAME.onmicrosoft.com/YOURAPPNAME  
    

    YOURTENANTNAME should be your organization’s tenant name in Azure AD
    YOURAPPNAME should be the name of the app you would like to pull data for with the API

  • In the Roles section, select Manager, then save.
    

• Return to the Manage users page, select the Azure AD application you just created, and click Add new key.

• Copy the Client ID and Key provided, as you will not be able to access this information again. You will need both of these in order to obtain the Azure AD token to use when calling the analytics API.

2. Obtain an Azure AD access token by sending a service-to-service access token request to the following Azure AD endpoint:

    https://login.microsoftonline.com/<tenant id>/oauth2/token.   
   

• To find the tenant ID, log in to the Azure Portal, navigate to Active Directory, and select the directory linked to your Dev Center account. The tenant ID is embedded in the URL for this page, as shown by the your_tenant_ID string example:

       https://manage.windowsazure.com/@<your_tenant_name>#workspaces/
       ActiveDirectoryExtension/Directory/<your_tenant_ID>/direcotryQuickStart
  

• The client_id and client_secret parameters are the Client ID and Key values that you copied in step 1.d.
  The resource parameter is: https://manage.devcenter.microsoft.com

3. Call the Windows Store analytics API.

• Set your call code parameters and pass the access token to the Authorization header.
• Required parameters for each request include the app or IAP ID.
• You can specify the date range and the number of rows you would like returned, as well as choose additional filters based on the data you would like to see.
  Data is returned in JSON format.

Data available with the Windows Store analytics API

Once you have completed the API setup and obtained an access token, use the REST call to obtain the specific data you need from your apps. Read the documentation for each of the data sources for additional information on how to set the parameters as well as to view examples of data that is returned by each call:

App Acquisitions: Aggregate acquisition data for an app by day, week, or month including type, age group, gender, market, OS version, and Store client.

IAP Acquisitions: Aggregate acquisition data for all IAPs in an app or a specific IAP by day, week, or month including type, age group, gender, market, OS version, and Store client.

Ratings: Ratings data for an app by day, week, or month including market, OS version, device type, and if the rating is new or revised.

Reviews: Review data for an app including market, OS version, package version, device details, if the review is new or revised, the review title, text, and author, helpful/not helpful votes, and the date and text of any responses.

App Health: App failure data for an app by day including name, hash, symbol, market, OS version, event type, device type, package name and version, hit count and machine count.

Code example

The following code example demonstrates how to obtain an Azure AD access token and call the Windows Store analytics API from a C# console app. To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. This example requires the Json.NET package from Newtonsoft to deserialize the JSON data returned by the Windows Store analytics API.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace TestAnalyticsAPI
{
    class Program
    {
        static void Main(string[] args)
        {
            string tenantId = "<your tenant ID>";
            string clientId = "<your client ID>";
            string clientSecret = "<your secret>";

            string scope = "https://manage.devcenter.microsoft.com";

            // Retrieve an Azure AD access token
            string accessToken = GetClientCredentialAccessToken(
                    tenantId,
                    clientId,
                    clientSecret,
                    scope).Result;

            // This is your app&#39;s product ID. This ID is embedded in the app&#39;s listing link
            // on the App identity page of the Dev Center dashboard.
            string appID = "<your app&#39;s product ID>";

            DateTime startDate = DateTime.Parse("08-01-2015");
            DateTime endDate = DateTime.Parse("11-01-2015");
            int pageSize = 1000;
            int startPageIndex = 0;

            // Call the Windows Store analytics API
            CallAnalyticsAPI(accessToken, appID, startDate, endDate, pageSize, startPageIndex);

            Console.Read();
        }

        private static void CallAnalyticsAPI(string accessToken, string appID, DateTime startDate, DateTime endDate, int top, int skip)
        {
            string requestURI;

            // Get app acquisitions
            requestURI = string.Format(
                "https://manage.devcenter.microsoft.com/v1.0/my/analytics/appacquisitions?applicationId={0}&amp;startDate={1}&amp;endDate={2}&amp;top={3}&amp;skip={4}",
                appID, startDate, endDate, top, skip);

            //// Get IAP acquisitions
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId={0}&amp;startDate={1}&amp;endDate={2}&amp;top={3}&amp;skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app failures
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/failurehits?applicationId={0}&amp;startDate={1}&amp;endDate={2}&amp;top={3}&amp;skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app ratings
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings?applicationId={0}&amp;startDate={1}&amp;endDate={2}&amp;top={3}&amp;skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app reviews
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/reviews?applicationId={0}&amp;startDate={1}&amp;endDate={2}&amp;top={3}&amp;skip={4}",
            //    appID, startDate, endDate, top, skip);

            HttpRequestMessage requestMessage = new HttpRequestMessage(HttpMethod.Get, requestURI);
            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

            WebRequestHandler handler = new WebRequestHandler();
            HttpClient httpClient = new HttpClient(handler);

            HttpResponseMessage response = httpClient.SendAsync(requestMessage).Result;

            Console.WriteLine(response);
            Console.WriteLine(response.Content.ReadAsStringAsync().Result);

            response.Dispose();
        }

        public static async Task<string> GetClientCredentialAccessToken(string tenantId, string clientId, string clientSecret, string scope)
        {
            string tokenEndpointFormat = "https://login.microsoftonline.com/{0}/oauth2/token";
            string tokenEndpoint = string.Format(tokenEndpointFormat, tenantId);

            dynamic result;
            using (HttpClient client = new HttpClient())
            {
                string tokenUrl = tokenEndpoint;
                using (
                    HttpRequestMessage request = new HttpRequestMessage(
                        HttpMethod.Post,
                        tokenUrl))
                {
                    string content =
                        string.Format(
                            "grant_type=client_credentials&amp;client_id={0}&amp;client_secret={1}&amp;resource={2}",
                            clientId,
                            clientSecret,
                            scope);

                    request.Content = new StringContent(content, Encoding.UTF8, "application/x-www-form-urlencoded");

                    using (HttpResponseMessage response = await client.SendAsync(request))
                    {
                        string responseContent = await response.Content.ReadAsStringAsync();
                        result = JsonConvert.DeserializeObject(responseContent);
                    }
                }
            }

            return result.access_token;
        }
    }
}

Error responses

The Windows Store analytics API returns error responses in a JSON object that contains error codes and messages. The following example demonstrates an error response caused by an invalid parameter.

{
    "code":"BadRequest",
    "data":[],
    "details":[],
    "innererror":{
        "code":"InvalidQueryParameters",
        "data":[
            "top parameter cannot be more than 10000"
        ],
        "details":[],
        "message":"One or More Query Parameters has invalid values.",
        "source":"AnalyticsAPI"
    },
    "message":"The calling client sent a bad request to the service.",
    "source":"AnalyticsAPI"
}

References

1. https://msdn.microsoft.com/en-us/windows/uwp/monetize/access-analytics-data-using-windows-store-services
2. https://msdn.microsoft.com/en-us/windows/uwp/monetize/get-app-acquisitions
3. https://msdn.microsoft.com/en-us/windows/uwp/monetize/get-in-app-acquisitions
4. https://msdn.microsoft.com/en-us/windows/uwp/monetize/get-error-reporting-data
5. https://msdn.microsoft.com/en-us/windows/uwp/monetize/get-app-ratings
6. https://msdn.microsoft.com/en-us/windows/uwp/monetize/get-app-reviews