iTunesConnectAnalytics

A nodejs module wrapping the AppStore (formerly iTunes) Connect Analytics API. Allows retrieving data available under the App Analytics section of AppStore Connect.

If you're building a dashboard for yourself or your company you might be better off with checking out Databox where we provide a super easy to set up iTunesConnect integration as well as a Google Play Developer Console integration.

Installation

$ npm install itunesconnectanalytics

Example usage

The usual boilerplate:

var itc = require('itunesconnectanalytics');
var Itunes = itc.Itunes;
var AnalyticsQuery = itc.AnalyticsQuery;

var username = 'UNAME';
var password = 'PASS';
var appId = '12345'; //Found in My Apps -> App -> Apple ID or read below on getting the app id.

var instance = new Itunes(username, password, {
  errorCallback: function(e) {
    console.log('Error logging in: ' + e);
  },
  successCallback: function(d) {
    console.log('Logged in');
  }
});

2FA

If you have 2 factor authentication enabled you'll be asked to enter the code when you call login first. Enter the code without any spaces and press enter. Rest will work normally.

Changing providers

If you have multiple accounts linked to your Apple ID you can change them using the changeProvider. Example:

const providerId = 'YOUR_PROVIDER_ID';
instance.changeProvider('880281', function (error, data) {
  //Done
});

Getting account information

Getting available apps. Useful for getting app IDs needed for later queries. The field you're interested in is adamId.

instance.getApps(function(error, data) {
  console.log(JSON.stringify(data, null, 2));
});

Getting the time interval for which data is available. Use dataEndDate property of the configuration object to know which is the most recent date that iTunesConnect has data for (the last day or two usually become available with a certain delay). You can use this date when making requests to avoid getting 0 values for days which do not have data yet.

instance.getSettings(function(error, data) {
  // To get end date:
  // var end = data.configuration.dataEndDate;

  console.log(JSON.stringify(data, null, 2));
});

Creating an instance and getting app units for the specified time interval.

var query = AnalyticsQuery.metrics(appId, {
  measures:  itc.measures.units,
}).date('2016-04-10','2016-05-10');

instance.request(query, function(error, result) {
  console.log(JSON.stringify(result, null, 2));
});

AnalyticsQuery

The AnalyticsQuery object is used to describe what kind of data should be retrieved. Each query must contain the following properties (they are set by default but you can customize them):

• start - Date in format YYYY-MM-DD.
• end - Date in format YYYY-MM-DD.
• frequency - Day, week or month.
• measures - metrics to be fetched.

Metrics are specified under measures key in query options. They can also be an array measures: [itc.measures.units, itc.measures.sales].

Available metrics:

• installs
• sessions
• pageViews
• activeDevices
• crashes
• payingUsers
• units
• sales
• iap (in app purchases)
• impressions
• impressionsUnique

Query types

There are two query types. One is metrics and the other is sources.

Metrics

Metrics query is used to retrieve data under the Metrics section in analytics.

Example metrics query:

Fetches installs and crashes for the past day.

var query = new AnalyticsQuery.metrics(appId, {
  measures: [itc.measures.installs, itc.measures.crashes]
}).time(1, 'days');

The full query can pretty much pull all data that can be accessed from the metrics tab of iTunes Analytics -

var query = new AnalyticsQuery.metrics(appId, {
	measures: [itc.measures.impressionsUnique /* First key required, Second key is optional for comparison */ , itc.measures.pageViewUnique],
	frequency: itc.frequency.months,  /* Optional - default is days */
	/* Grouping is optional - you can leave it out if you don't want data grouped by anything. 
	This is same as selecting "view by" in Analytics */
	group: {
		metric: itc.measures.impressionsUnique /* This is optional - it has to be one of the metric you add in
		measures above, else it will error. 
												
		If you leave it blank, we'll default it to the first measures, which is normally what you need. */, 
		dimension: itc.dimension.territory,  /* this is the main thing you need to add when grouping */
		rank: "", /* Optional - not really sure how it works, but else leave it alone and we will default it to blank. 
		TODO: Find out what this actually does */
		
		limit: 10 /* Optional - default is 200. TODO: Find out what this actually does */ 
	},
	/* Filtering is optional - you can leave it out if you don't want data filtered by anything. This is same as 
	selecting filtered by in Analytics */
	
	/* You can choose at most 2 filters if you don't use group by, and 1 filter if you use group by */

	/* NOTE: every metric cannot be grouped/filtered by every dimension/dimensionFilterKey - for e.g. for app
	impressions, app version is irrelevant - using incompatible dimensions with metrics will lead to errored responses.
	This is currently not checked by this module and is your responsibility. When in doubt, try out the Analytics
	interface and see what is allowed and what isn't. */
	
	dimensionFilters: [
		{dimensionKey: itc.dimensionFilterKey.device, optionKeys: [itc.platform.iPad]}
	]
}).date('2016-05-01', '2016-06-30'); //can be date or time like above. 

Sources

Sources query is used to retrieve data under the Sources section in analytics.

From sources you can retrieve top websites or top campaigns. This can be specified using the dimension setting in options.

You can also specify a limit which limits the number of results.

Example sources query:

Get app store views for the last day from Top websites.

var query = new AnalyticsQuery.sources(appId, {
  measures: itc.measures.pageViews,
  dimension: itc.dimension.websites,
  limit 100
}).time(1, 'days');

Some other examples

// Get App Store Views for last 7 days by website sources
var query = AnalyticsQuery.sources('940584421', {
  measures:  itc.measures.pageViews,
  dimension: itc.dimension.websites
}).time(7,itc.frequency.day);

instance.request(query, function(error, result) {
  console.log(JSON.stringify(result, null, 2));
});

// Get installs for each day in date range 2016-04-10 to 2016-05-10
var query = AnalyticsQuery.metrics('940584421', {
  measures:  itc.measures.installs,
}).date('2016-04-10','2016-05-10');

instance.request(query, function(error, result) {
  console.log(JSON.stringify(result, null, 2));
});

// Get sessions for each day in last month
var query = AnalyticsQuery.metrics('940584421', {
  measures:  itc.measures.sessions,
}).time(1,itc.frequency.month);


instance.request(query, function(error, result) {
  console.log(JSON.stringify(result, null, 2));
});

// Get sessions for each day in last month, but filtered to only the region = "US and Canada"
var query = AnalyticsQuery.metrics('940584421', {
  measures:  itc.measures.sessions,
  dimensionFilters: [{ dimensionKey: itc.dimensionFilterKey.region,  optionKeys: [itc.region.usaCanada] }]
}).time(1, itc.frequency.month);


instance.request(query, function(error, result) {
  console.log(JSON.stringify(result, null, 2));
});

// Get sessions for each day in last month, but filtered to only the territory = "Canada"
var query = AnalyticsQuery.metrics('940584421', {
  measures:  itc.measures.sessions,
  dimensionFilters: [{ dimensionKey: itc.dimensionFilterKey.territory,  optionKeys: [itc.territory.canada] }]
}).time(1, itc.frequency.month);


instance.request(query, function(error, result) {
  console.log(JSON.stringify(result, null, 2));
});

//Make an arbitrary GET request to the itunes connect API
var url = 'https://analytics.itunes.apple.com/analytics/api/v1/settings/user-info'; //Get info about yourself :)
instance.getAPIURL(url, function(error, result) {
  console.log(JSON.stringify(result, null, 2));
});

TODO

• More examples
• Tests

Authors

• JanHalozan