Add tracking to Google Analytics

Add new methods to track information in Google Analytics(GA). As the data that we want to track is different than the one we track in Eqatec Analytics, call the new methods whenever we want to send some information to GA.
Change the broker process to send information to Eqatec Analytics when we want to track feature or exception and to GA only when the new method for tracking there is called.

In Google Analytics (GA) we track two types of data - pages (called pageviews) and events. Each command is tracked as a page - we only track the name of the command as a page:
* `tns build android` will be tracked as visited page - `build android`
* `tns run` will be tracked as visited page - `run`

When we want to track some additional actions that happen during execution of each command, we send events to GA. Each event has the following data:
* category - currently we do not have a specific category for each action, so it is hardcoded to "CLI".
* action - this is the real action that will be tracked, for example `Build`, `LiveSync`, `Deploy`, etc.
* label - contains specific inforamation for the current action, for example what is the platform, device type, etc. In many cases we send labels with a lot of information, but as the value must be string, we use `_` as a separator. For example:
  * Action `Build` may have the following label: `Android_Debug_Incremental`. This is `<platform>_<build configuration>_<build type>`.
  * Action `LiveSync` may have the following label: `Android_Emulator_5.1`. This is `<platform>_<device type>_<device os version>`.

Custom dimensions
For each additional data may be send to GA via Custom Dimensions. More about them can be found [here](https://support.google.com/analytics/answer/2709828). We are using several custom dimensions, most of them have hit scope, i.e. their values are saved for the current hit (event or page), but may be changed for the next time. The only exclusion is `session id` - it has session scope, so whenever it is sent, the new value overwrites the values of the "session id" property in all hits of the current session.
One interesting custom dimension is `Client` - it will be set to the value of `--analyticsClient` in case it is passed. In case not, we'll set it to "CLI" when terminal is interactive and "Unknown" when terminal is not interactive.

Sessions - what is session for GA
In Eqatec Analytics we call `stopMonitor` at the end of each command. So the session there is one command. In GA we've decided to keep the default way of measuring a session - a session is stopped when there are 30 inactive minutes, i.e. no data is sent from 30 minutes. This allows us to investigate the behavior and the flow of commands a user is executing in a single session (during the day for example).

Client ID and User ID:
Currently we do not send User ID to GA, we use Client ID instead as sending User IDs requires different logic and agreements. For us all users are anonymous.

User-Agent
When sending requests to GA, we need to set correct User-Agent, so GA will be able to understand the Operating System. For each OS the string is painfully specific... Current implementation works fine for Windows, Linux and macOS.

Implementation
In order to send data to GA, we are using a `universal-analytics` npm package. We cannot use Google's default libraries (`analytics.js`, `gtag.js`) as they are written for browser. So the only way to track data is to use the Measurement Protocol (directly send http requests). However, `universal-analytics` package provides a very good abstraction over the Measurement Protocol, so we are using it instead of implementing each call.

More information about Measurement protocol:
https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters

Author: rosen-vladimirov

lib/bootstrap.ts

@@ -30,8 +30,9 @@ $injector.require("androidDebugService", "./services/android-debug-service");
 
 $injector.require("userSettingsService", "./services/user-settings-service");
 $injector.require("analyticsSettingsService", "./services/analytics-settings-service");
-$injector.requirePublic("analyticsService", "./services/analytics/analytics-service");
+$injector.require("analyticsService", "./services/analytics/analytics-service");
 $injector.require("eqatecAnalyticsProvider", "./services/analytics/eqatec-analytics-provider");
+$injector.require("googleAnalyticsProvider", "./services/analytics/google-analytics-provider");
 
 $injector.require("emulatorSettingsService", "./services/emulator-settings-service");
 

lib/common

@@ -103,3 +103,21 @@ export const enum NativePlatformStatus {
 	requiresPrepare = "2",
 	alreadyPrepared = "3"
 }
+
+export const enum DebugTools {
+	Chrome = "Chrome",
+	Inspector = "Inspector"
+}
+
+export const enum TrackActionNames {
+	Build = "Build",
+	CreateProject = "Create project",
+	Debug = "Debug",
+	Deploy = "Deploy",
+	LiveSync = "LiveSync"
+}
+
+export const enum BuildStates {
+	Clean = "Clean",
+	Incremental = "Incremental"
+}

lib/constants.ts

@@ -13,3 +13,4 @@ $injector.requirePublicClass("localBuildService", "./services/local-build-servic
 // We need this because some services check if (!$options.justlaunch) to start the device log after some operation.
 // We don't want this behaviour when the CLI is required as library.
 $injector.resolve("options").justlaunch = true;
+$injector.resolve<IStaticConfig>("staticConfig").disableAnalytics = true;

lib/nativescript-cli-lib-bootstrap.ts

@@ -11,16 +11,12 @@ class AnalyticsSettingsService implements IAnalyticsSettingsService {
 		return true;
 	}
 
-	public async getUserId(): Promise<string> {
-		let currentUserId = await this.$userSettingsService.getSettingValue<string>("USER_ID");
-		if (!currentUserId) {
-			currentUserId = createGUID(false);
-
-			this.$logger.trace(`Setting new USER_ID: ${currentUserId}.`);
-			await this.$userSettingsService.saveSetting<string>("USER_ID", currentUserId);
-		}
+	public getUserId(): Promise<string> {
+		return this.getSettingValueOrDefault("USER_ID");
+	}
 
-		return currentUserId;
+	public getClientId(): Promise<string> {
+		return this.getSettingValueOrDefault(this.$staticConfig.ANALYTICS_INSTALLATION_ID_SETTING_NAME);
 	}
 
 	public getClientName(): string {
@@ -43,5 +39,17 @@ class AnalyticsSettingsService implements IAnalyticsSettingsService {
 	private getSessionsProjectKey(projectName: string): string {
 		return `${AnalyticsSettingsService.SESSIONS_STARTED_KEY_PREFIX}${projectName}`;
 	}
+
+	private async getSettingValueOrDefault(settingName: string): Promise<string> {
+		let guid = await this.$userSettingsService.getSettingValue<string>(settingName);
+		if (!guid) {
+			guid = createGUID(false);
+
+			this.$logger.trace(`Setting new ${settingName}: ${guid}.`);
+			await this.$userSettingsService.saveSetting<string>(settingName, guid);
+		}
+
+		return guid;
+	}
 }
 $injector.register("analyticsSettingsService", AnalyticsSettingsService);

lib/services/analytics-settings-service.ts

@@ -3,38 +3,41 @@ import { cache } from "../../common/decorators";
 export class AnalyticsBroker implements IAnalyticsBroker {
 
 	@cache()
-	private get $eqatecAnalyticsProvider(): IAnalyticsProvider {
-		return this.$injector.resolve("eqatecAnalyticsProvider", { pathToBootstrap: this.pathToBootstrap });
+	private async getEqatecAnalyticsProvider(): Promise<IAnalyticsProvider> {
+		return this.$injector.resolve("eqatecAnalyticsProvider");
 	}
 
-	constructor(private pathToBootstrap: string,
-		private $injector: IInjector) { }
-
-	private get analyticsProviders(): IAnalyticsProvider[] {
-		return [
-			this.$eqatecAnalyticsProvider
-		];
+	@cache()
+	private async getGoogleAnalyticsProvider(): Promise<IGoogleAnalyticsProvider> {
+		const clientId = await this.$analyticsSettingsService.getClientId();
+		return this.$injector.resolve("googleAnalyticsProvider", { clientId });
 	}
 
-	public async sendDataForTracking(trackInfo: ITrackingInformation): Promise<void> {
-		for (const provider of this.analyticsProviders) {
-			switch (trackInfo.type) {
-				case TrackingTypes.Exception:
-					await provider.trackError(<IExceptionsTrackingInformation>trackInfo);
-					break;
-				case TrackingTypes.Feature:
-					await provider.trackInformation(<IFeatureTrackingInformation>trackInfo);
-					break;
-				case TrackingTypes.AcceptTrackFeatureUsage:
-					await provider.acceptFeatureUsageTracking(<IAcceptUsageReportingInformation>trackInfo);
-					break;
-				case TrackingTypes.Finish:
-					await provider.finishTracking();
-					break;
-				default:
-					throw new Error(`Invalid tracking type: ${trackInfo.type}`);
-			}
+	constructor(private $analyticsSettingsService: IAnalyticsSettingsService,
+		private $injector: IInjector) { }
 
+	public async sendDataForTracking(trackInfo: ITrackingInformation): Promise<void> {
+		const eqatecProvider = await this.getEqatecAnalyticsProvider();
+		const googleProvider = await this.getGoogleAnalyticsProvider();
+
+		switch (trackInfo.type) {
+			case TrackingTypes.Exception:
+				await eqatecProvider.trackError(<IExceptionsTrackingInformation>trackInfo);
+				break;
+			case TrackingTypes.Feature:
+				await eqatecProvider.trackInformation(<IFeatureTrackingInformation>trackInfo);
+				break;
+			case TrackingTypes.AcceptTrackFeatureUsage:
+				await eqatecProvider.acceptFeatureUsageTracking(<IAcceptUsageReportingInformation>trackInfo);
+				break;
+			case TrackingTypes.GoogleAnalyticsData:
+				await googleProvider.trackHit(<IGoogleAnalyticsTrackingInformation>trackInfo);
+				break;
+			case TrackingTypes.Finish:
+				await eqatecProvider.finishTracking();
+				break;
+			default:
+				throw new Error(`Invalid tracking type: ${trackInfo.type}`);
 		}
 
 	}

lib/services/analytics/analytics-broker.ts

@@ -2,6 +2,8 @@ import { AnalyticsServiceBase } from "../../common/services/analytics-service-ba
 import { ChildProcess } from "child_process";
 import * as path from "path";
 import { cache } from "../../common/decorators";
+import { isInteractive } from '../../common/helpers';
+import { DeviceTypes, AnalyticsClients } from "../../common/constants";
 
 export class AnalyticsService extends AnalyticsServiceBase implements IAnalyticsService {
 	private static ANALYTICS_BROKER_START_TIMEOUT = 30 * 1000;
@@ -14,26 +16,100 @@ export class AnalyticsService extends AnalyticsServiceBase implements IAnalytics
 		$analyticsSettingsService: IAnalyticsSettingsService,
 		$osInfo: IOsInfo,
 		private $childProcess: IChildProcess,
-		private $processService: IProcessService) {
+		private $processService: IProcessService,
+		private $projectDataService: IProjectDataService,
+		private $mobileHelper: Mobile.IMobileHelper) {
 		super($logger, $options, $staticConfig, $prompter, $userSettingsService, $analyticsSettingsService, $osInfo);
 	}
 
 	public track(featureName: string, featureValue: string): Promise<void> {
-		return this.sendDataForTracking(featureName, featureValue);
+		const data: IFeatureTrackingInformation = {
+			type: TrackingTypes.Feature,
+			featureName: featureName,
+			featureValue: featureValue
+		};
+
+		return this.sendInfoForTracking(data, this.$staticConfig.TRACK_FEATURE_USAGE_SETTING_NAME);
 	}
 
 	public trackException(exception: any, message: string): Promise<void> {
-		return this.sendExceptionForTracking(exception, message);
+		const data: IExceptionsTrackingInformation = {
+			type: TrackingTypes.Exception,
+			exception,
+			message
+		};
+
+		return this.sendInfoForTracking(data, this.$staticConfig.ERROR_REPORT_SETTING_NAME);
 	}
 
 	public async trackAcceptFeatureUsage(settings: { acceptTrackFeatureUsage: boolean }): Promise<void> {
-
-		this.sendMessageToBroker(<IAcceptUsageReportingInformation> {
+		this.sendMessageToBroker(<IAcceptUsageReportingInformation>{
 			type: TrackingTypes.AcceptTrackFeatureUsage,
 			acceptTrackFeatureUsage: settings.acceptTrackFeatureUsage
 		});
 	}
 
+	public async trackInGoogleAnalytics(gaSettings: IGoogleAnalyticsData): Promise<void> {
+		await this.initAnalyticsStatuses();
+
+		if (!this.$staticConfig.disableAnalytics && this.analyticsStatuses[this.$staticConfig.TRACK_FEATURE_USAGE_SETTING_NAME] === AnalyticsStatus.enabled) {
+			gaSettings.customDimensions = gaSettings.customDimensions || {};
+			gaSettings.customDimensions[GoogleAnalyticsCustomDimensions.client] = this.$options.analyticsClient || (isInteractive() ? AnalyticsClients.Cli : AnalyticsClients.Unknown);
+
+			const googleAnalyticsData: IGoogleAnalyticsTrackingInformation = _.merge({ type: TrackingTypes.GoogleAnalyticsData }, gaSettings, { category: AnalyticsClients.Cli });
+			return this.sendMessageToBroker(googleAnalyticsData);
+		}
+	}
+
+	public async trackEventActionInGoogleAnalytics(data: IEventActionData): Promise<void> {
+		const device = data.device;
+		const platform = device ? device.deviceInfo.platform : data.platform;
+		const isForDevice = device ? !device.isEmulator : data.isForDevice;
+
+		let label: string = "";
+		label = this.addDataToLabel(label, platform);
+
+		if (isForDevice !== null) {
+			// In case action is Build and platform is Android, we do not know if the deviceType is emulator or device.
+			// Just exclude the device_type in this case.
+			const deviceType = isForDevice ? DeviceTypes.Device : (this.$mobileHelper.isAndroidPlatform(platform) ? DeviceTypes.Emulator : DeviceTypes.Simulator);
+			label = this.addDataToLabel(label, deviceType);
+		}
+
+		if (device) {
+			label = this.addDataToLabel(label, device.deviceInfo.version);
+		}
+
+		if (data.additionalData) {
+			label = this.addDataToLabel(label, data.additionalData);
+		}
+
+		const customDimensions: IStringDictionary = {};
+		if (data.projectDir) {
+			const projectData = this.$projectDataService.getProjectData(data.projectDir);
+			customDimensions[GoogleAnalyticsCustomDimensions.projectType] = projectData.projectType;
+		}
+
+		const googleAnalyticsEventData: IGoogleAnalyticsEventData = {
+			googleAnalyticsDataType: GoogleAnalyticsDataType.Event,
+			action: data.action,
+			label,
+			customDimensions
+		};
+
+		this.$logger.trace("Will send the following information to Google Analytics:", googleAnalyticsEventData);
+
+		await this.trackInGoogleAnalytics(googleAnalyticsEventData);
+	}
+
+	private addDataToLabel(label: string, newData: string): string {
+		if (newData && label) {
+			return `${label}_${newData}`;
+		}
+
+		return label || newData || "";
+	}
+
 	@cache()
 	private getAnalyticsBroker(): Promise<ChildProcess> {
 		return new Promise<ChildProcess>((resolve, reject) => {
@@ -73,44 +149,25 @@ export class AnalyticsService extends AnalyticsServiceBase implements IAnalytics
 
 					if (!isSettled) {
 						isSettled = true;
+
+						this.$processService.attachToProcessExitSignals(this, () => {
+							broker.send({
+								type: TrackingTypes.Finish
+							});
+						});
+
 						resolve(broker);
 					}
 				}
 			});
-
-			this.$processService.attachToProcessExitSignals(this, () => {
-				broker.send({
-					type: TrackingTypes.Finish
-				});
-			});
 		});
 	}
 
-	private async sendDataForTracking(featureName: string, featureValue: string): Promise<void> {
-		await this.initAnalyticsStatuses();
-
-		if (this.analyticsStatuses[this.$staticConfig.TRACK_FEATURE_USAGE_SETTING_NAME] === AnalyticsStatus.enabled) {
-			return this.sendMessageToBroker(
-				<IFeatureTrackingInformation> {
-					type: TrackingTypes.Feature,
-					featureName: featureName,
-					featureValue: featureValue
-				}
-			);
-		}
-	}
-
-	private async sendExceptionForTracking(exception: Error, message: string): Promise<void> {
+	private async sendInfoForTracking(trackingInfo: ITrackingInformation, settingName: string): Promise<void> {
 		await this.initAnalyticsStatuses();
 
-		if (this.analyticsStatuses[this.$staticConfig.ERROR_REPORT_SETTING_NAME] === AnalyticsStatus.enabled) {
-			return this.sendMessageToBroker(
-				<IExceptionsTrackingInformation> {
-					type: TrackingTypes.Exception,
-					exception,
-					message
-				}
-			);
+		if (!this.$staticConfig.disableAnalytics && this.analyticsStatuses[settingName] === AnalyticsStatus.enabled) {
+			return this.sendMessageToBroker(trackingInfo);
 		}
 	}
 

lib/services/analytics/analytics-service.ts

@@ -81,3 +81,17 @@ interface IAnalyticsProvider {
 	 */
 	finishTracking(): Promise<void>;
 }
+
+interface IGoogleAnalyticsTrackingInformation extends IGoogleAnalyticsData, ITrackingInformation { }
+
+/**
+ * Describes methods required to track in Google Analytics.
+ */
+interface IGoogleAnalyticsProvider {
+	/**
+	 * Tracks hit types.
+	 * @param {IGoogleAnalyticsData} data Data that has to be tracked.
+	 * @returns {Promise<void>}
+	 */
+	trackHit(data: IGoogleAnalyticsData): Promise<void>;
+}

lib/services/analytics/analytics.d.ts

@@ -0,0 +1,8 @@
+const enum GoogleAnalyticsCustomDimensions {
+	cliVersion = "cd1",
+	projectType = "cd2",
+	clientID = "cd3",
+	sessionID = "cd4",
+	client = "cd5",
+	nodeVersion = "cd6"
+}