@minecraft/creator-tools
Version:
Minecraft Creator Tools command line and libraries.
300 lines (299 loc) • 9.72 kB
JavaScript
"use strict";
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
Object.defineProperty(exports, "__esModule", { value: true });
const TelemetryConstants_1 = require("./TelemetryConstants");
const Constants_1 = require("../core/Constants");
class TelemetryService {
_isInitialized = false;
_oneDSInstance = null;
_activeProjectCount = 0;
_mctoolsVersion = "0.0.1-dev";
window = globalThis;
/**
* Whether telemetry is allowed by the compile-time ENABLE_ANALYTICS flag.
* This is the primary gate — if false, no telemetry methods will do anything.
*/
// @ts-ignore - ENABLE_ANALYTICS is injected by webpack and vite configs
_analyticsAllowed = typeof ENABLE_ANALYTICS !== "undefined" && ENABLE_ANALYTICS === true;
constructor() {
if (this._analyticsAllowed) {
this._checkInitialization();
}
this._loadVersion();
}
/**
* Load the version from constants
*/
_loadVersion() {
this._mctoolsVersion = Constants_1.constants.version;
}
/**
* Set the active project count
*/
setActiveProjectCount(count) {
this._activeProjectCount = count;
}
/**
* Get common properties and measurements to include with every event
*/
_getCommonPropertiesAndMeasurements() {
const properties = {};
const measurements = {};
if (this._mctoolsVersion) {
properties[TelemetryConstants_1.TelemetryProperties.MCTOOLS_VERSION] = this._mctoolsVersion;
}
if (this._activeProjectCount > 0) {
measurements[TelemetryConstants_1.TelemetryMeasurements.ACTIVE_PROJECT_COUNT] = this._activeProjectCount;
}
return { properties, measurements };
}
/**
* Check if 1DS is initialized and available on the window object
*/
_checkInitialization() {
if (typeof this.window !== "undefined" && this.window.oneDSInstance) {
this._oneDSInstance = this.window.oneDSInstance;
this._isInitialized = true;
}
}
/**
* Get the 1DS instance, checking initialization if not already done.
* Returns null immediately if ENABLE_ANALYTICS is false at compile time.
*/
_getInstance() {
if (!this._analyticsAllowed) {
return null;
}
if (!this._isInitialized) {
this._checkInitialization();
}
if (!this._isInitialized && typeof this.window !== "undefined" && this.window.oneDSInstance) {
this._oneDSInstance = this.window.oneDSInstance;
this._isInitialized = true;
}
return this._oneDSInstance;
}
/**
* Check if telemetry is enabled and available
*/
isEnabled() {
return this._getInstance() !== null;
}
/**
* Track a custom event
* Only accepts predefined event names, property keys, and measurement keys from TelemetryConstants
* @param event Event with strictly typed properties and measurements
*/
trackEvent(event) {
const instance = this._getInstance();
if (!instance) {
return;
}
try {
const commonData = this._getCommonPropertiesAndMeasurements();
const eventData = {
name: event.name,
};
const mergedProperties = {
...commonData.properties,
...(event.properties || {}),
};
if (Object.keys(mergedProperties).length > 0) {
eventData.data = mergedProperties;
}
const mergedMeasurements = {
...commonData.measurements,
...(event.measurements || {}),
};
if (Object.keys(mergedMeasurements).length > 0) {
eventData.measurements = mergedMeasurements;
}
instance.trackEvent(eventData);
}
catch (error) {
console.error("Error tracking event:", error);
}
}
/**
* Track a page view
* @param pageView Page view name and optional properties
*/
trackPageView(pageView) {
const instance = this._getInstance();
if (!instance) {
return;
}
try {
const commonData = this._getCommonPropertiesAndMeasurements();
const pageViewData = {
name: pageView.name,
uri: pageView.uri ||
(typeof this.window !== "undefined" && this.window.location
? this.window.location.href
: ""),
};
const mergedProperties = {
...commonData.properties,
...(pageView.properties || {}),
};
if (Object.keys(mergedProperties).length > 0) {
pageViewData.data = mergedProperties;
}
const mergedMeasurements = {
...commonData.measurements,
...(pageView.measurements || {}),
};
if (Object.keys(mergedMeasurements).length > 0) {
pageViewData.measurements = mergedMeasurements;
}
instance.trackPageView(pageViewData);
}
catch (error) {
console.error("Error tracking page view:", error);
}
}
/**
* Track an exception
* @param exception Exception details
*/
trackException(exception) {
const instance = this._getInstance();
if (!instance) {
return;
}
try {
const commonData = this._getCommonPropertiesAndMeasurements();
const exceptionData = {
exception: exception.exception,
severityLevel: exception.severityLevel || 3,
};
const mergedProperties = {
...commonData.properties,
...(exception.properties || {}),
};
if (Object.keys(mergedProperties).length > 0) {
exceptionData.data = mergedProperties;
}
instance.trackException(exceptionData);
}
catch (error) {
console.error("Error tracking exception:", error);
}
}
/**
* Track a metric/measurement
* @param name Metric name from TelemetryMeasurements
* @param value Metric value
* @param properties Optional properties
*/
trackMetric(name, value, properties) {
const instance = this._getInstance();
if (!instance) {
return;
}
try {
const commonData = this._getCommonPropertiesAndMeasurements();
const metricData = {
name,
average: value,
};
const mergedProperties = {
...commonData.properties,
...(properties || {}),
};
if (Object.keys(mergedProperties).length > 0) {
metricData.data = mergedProperties;
}
instance.trackMetric(metricData);
}
catch (error) {
console.error("Error tracking metric:", error);
}
}
/**
* Track a trace/log message
* @param message Log message
* @param severityLevel Severity level
* @param properties Optional properties
*/
trackTrace(message, severityLevel, properties) {
const instance = this._getInstance();
if (!instance) {
return;
}
try {
const commonData = this._getCommonPropertiesAndMeasurements();
const traceData = {
message,
severityLevel: severityLevel || 1,
};
const mergedProperties = {
...commonData.properties,
...(properties || {}),
};
if (Object.keys(mergedProperties).length > 0) {
traceData.data = mergedProperties;
}
instance.trackTrace(traceData);
}
catch (error) {
console.error("Error tracking trace:", error);
}
}
/**
* Flush any pending telemetry data
*/
flush() {
const instance = this._getInstance();
if (!instance) {
return;
}
try {
if (instance.flush) {
instance.flush();
}
}
catch (error) {
console.error("Error flushing telemetry:", error);
}
}
/**
* Set authenticated user context
* @param authenticatedUserId User ID
* @param accountId Optional account ID
*/
setAuthenticatedUserContext(authenticatedUserId, accountId) {
const instance = this._getInstance();
if (!instance) {
return;
}
try {
if (instance.setAuthenticatedUserContext) {
instance.setAuthenticatedUserContext(authenticatedUserId, accountId);
}
}
catch (error) {
console.error("Error setting authenticated user context:", error);
}
}
/**
* Clear authenticated user context
*/
clearAuthenticatedUserContext() {
const instance = this._getInstance();
if (!instance) {
return;
}
try {
if (instance.clearAuthenticatedUserContext) {
instance.clearAuthenticatedUserContext();
}
}
catch (error) {
console.error("Error clearing authenticated user context:", error);
}
}
}
// Export singleton instance as default
exports.default = new TelemetryService();