Skip to content

Adding code comments to analytics.ts #535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 23, 2019
Merged

Adding code comments to analytics.ts #535

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
49e68e1
Adding code comments to src/providers/analytics.ts
esmacik Jul 22, 2019
a7ef2e7
Merge branch 'master' into em-analytics
esmacik Jul 22, 2019
b0625cf
Tweaking some things requested by Eric, 'Function' instead of 'Cloud …
esmacik Jul 22, 2019
aecf2cc
Merge branch 'em-analytics' of github.com:firebase/firebase-functions…
esmacik Jul 22, 2019
f05ec4c
Merge branch 'master' into em-analytics
esmacik Jul 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 73 additions & 40 deletions src/providers/analytics.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,12 @@ export const provider = 'google.analytics';
export const service = 'app-measurement.com';

/**
* Select analytics events to listen to for events.
* @param analyticsEventType Name of the analytics event type.
* Registers a function to handle analytics events.
*
* @param analyticsEventType Name of the analytics event type to which
* this Cloud Function is scoped.
*
* @return Analytics event builder interface.
*/
export function event(analyticsEventType: string) {
return _eventWithOptions(analyticsEventType, {});
Expand All @@ -61,7 +65,7 @@ export function _eventWithOptions(
/**
* The Firebase Analytics event builder interface.
*
* Access via [`functions.analytics.event()`](functions.analytics#event).
* Access via [`functions.analytics.event()`](functions.analytics#.event).
*/
export class AnalyticsEventBuilder {
/** @hidden */
Expand All @@ -73,12 +77,10 @@ export class AnalyticsEventBuilder {
/**
* Event handler that fires every time a Firebase Analytics event occurs.
*
* @param {!function(!functions.Event<!functions.analytics.AnalyticsEvent>)}
* handler Event handler that fires every time a Firebase Analytics event
* @param handler Event handler that fires every time a Firebase Analytics event
* occurs.
*
* @return {!functions.CloudFunction<!functions.analytics.AnalyticsEvent>} A
* Cloud Function you can export.
* @return A function that you can export and deploy.
*/
onLog(
handler: (
Expand All @@ -102,13 +104,11 @@ export class AnalyticsEventBuilder {
}
}

/**
* Interface representing a Firebase Analytics event that was logged for a specific user.
*/
/** Interface representing a Firebase Analytics event that was logged for a specific user. */
Copy link
Contributor

@thechenky thechenky Jul 22, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this fit on one line? Can't tell

export class AnalyticsEvent {
/**
* The date on which the event.was logged.
* (`YYYYMMDD` format in the registered timezone of your app).
* The date on which the event.was logged.
* (`YYYYMMDD` format in the registered timezone of your app).
*/
reportingDate: string;

Expand Down Expand Up @@ -232,11 +232,9 @@ export class UserDimensions {
}
}

/**
* Predefined or custom properties stored on the client side.
*/
/** Predefined or custom properties stored on the client side. */
export class UserPropertyValue {
/** Last set value of a user property. */
/** The last set value of a user property. */
value: string;

/** UTC client time when the user property was last set. */
Expand All @@ -250,47 +248,55 @@ export class UserPropertyValue {
}

/**
* Interface representing the device that triggered these Firebase Analytics events.
* Interface representing the device that triggered these
* Firebase Analytics events.
*/
export interface DeviceInfo {
/**
* Device category.
*
* Examples: "tablet" or "mobile".
*/
deviceCategory?: string;

/**
* Device brand name.
*
* Examples: "Samsung", "HTC"
*/
mobileBrandName?: string;

/**
* Device model name in human-readable format.
*
* Example: "iPhone 7"
*/
mobileModelName?: string;

/**
* Device marketing name.
*
* Example: "Galaxy S4 Mini"
*/
mobileMarketingName?: string;

/**
* Device model, as read from the OS.
*
* Example: "iPhone9,1"
*/
deviceModel?: string;

/**
* Device OS version when data capture ended.
*
* Example: "4.4.2"
*/
platformVersion?: string;

/**
* Vendor specific device identifier. This is IDFV on iOS. Not used for Android.
*
* Example: '599F9C00-92DC-4B5C-9464-7971F01F8370'
*/
deviceId?: string;
Expand All @@ -313,69 +319,86 @@ export interface DeviceInfo {

/**
* The time zone of the device when data was uploaded, as seconds skew from UTC.
* Use this to calculate the device's local time for [`event.timestamp`](functions.Event#timestamp)`.
* Use this to calculate the device's local time for [`event.timestamp`](functions.Event#timestamp).
*/
deviceTimeZoneOffsetSeconds: number;

/**
* The device's Limit Ad Tracking setting.
* When `true`, you cannot use `resettableDeviceId` for remarketing, demographics or influencing ads serving
* behaviour. However, you can use resettableDeviceId for conversion tracking and campaign attribution.
* behaviour. However, you can use `resettableDeviceId` for conversion tracking and campaign attribution.
*/
limitedAdTracking: boolean;
}

/**
* Interface representing the geographic origin of the events.
*/
/** Interface representing the geographic origin of the events. */
export interface GeoInfo {
/** The geographic continent. Example: "Americas". */
/**
* The geographic continent.
*
* Example: "South America".
*/
continent?: string;

/** The geographic country. Example: "Brazil". */
/**
* The geographic country.
*
* Example: "Brazil".
*/
country?: string;

/** The geographic region. Example: "State of Sao Paulo". */
/**
* The geographic region.
*
* Example: "State of Sao Paulo".
*/
region?: string;

/** The geographic city. Example: "Sao Paulo". */
/**
* The geographic city.
*
* Example: "Sao Paulo".
*/
city?: string;
}

/**
* Interface representing the application that triggered these events.
*/
/** Interface representing the application that triggered these events. */
export interface AppInfo {
/**
* The app's version name.
* Examples: "1.0", "4.3.1.1.213361", "2.3 (1824253)", "v1.8b22p6".
* The app's version name.
*
* Examples: "1.0", "4.3.1.1.213361", "2.3 (1824253)", "v1.8b22p6".
*/
appVersion?: string;

/**
* Unique id for this instance of the app.
* Example: "71683BF9FA3B4B0D9535A1F05188BAF3".
* Unique ID for this instance of the app.
*
* Example: "71683BF9FA3B4B0D9535A1F05188BAF3".
*/
appInstanceId: string;

/**
* The identifier of the store that installed the app.
* Examples: "com.sec.android.app.samsungapps", "com.amazon.venezia", "com.nokia.nstore".
* The identifier of the store that installed the app.
*
* Examples: "com.sec.android.app.samsungapps", "com.amazon.venezia", "com.nokia.nstore".
*/
appStore?: string;

/** The app platform. Examples: "ANDROID", "IOS". */
/**
* The app platform.
*
* Examples: "ANDROID", "IOS".
*/
appPlatform: string;

/** Unique application identifier within an app store. */
appId?: string;
}

/**
* Interface representing the bundle in which these events were uploaded.
*/
/** Interface representing the bundle these events were uploaded to. */
export class ExportBundleInfo {
/** Monotonically increasing index for each bundle set by the Analytics SDK. */
/** Monotonically increasing index for each bundle set by the Analytics SDK. */
bundleSequenceId: number;

/** Timestamp offset (in milliseconds) between collection time and upload time. */
Expand All @@ -393,6 +416,7 @@ export class ExportBundleInfo {
}
}

/** @hidden */
function copyFieldTo<T, K extends keyof T>(
from: any,
to: T,
Expand All @@ -405,6 +429,7 @@ function copyFieldTo<T, K extends keyof T>(
}
}

/** @hidden */
function copyField<T, K extends keyof T>(
from: any,
to: T,
Expand All @@ -414,6 +439,7 @@ function copyField<T, K extends keyof T>(
copyFieldTo(from, to, field as string, field, transform);
}

/** @hidden */
function copyFields<T, K extends keyof T>(from: any, to: T, fields: K[]): void {
for (const field of fields) {
copyField(from, to, field);
Expand Down Expand Up @@ -449,10 +475,12 @@ function copyFields<T, K extends keyof T>(from: any, to: T, fields: K[]): void {
// is due to the encoding library, which renders int64 values as strings to avoid loss of precision. This
// method always returns a string, similarly to avoid loss of precision, unlike the less-conservative
// 'unwrapValue' method just below.
/** @hidden */
function unwrapValueAsString(wrapped: any): string {
const key: string = _.keys(wrapped)[0];
return _.toString(wrapped[key]);
}

// Ditto as the method above, but returning the values in the idiomatic JavaScript type (string for strings,
// number for numbers):
// {
Expand All @@ -466,7 +494,10 @@ function unwrapValueAsString(wrapped: any): string {
// purposes can be divided into 'number' versus 'string'. This method will render all the numbers as
// JavaScript's 'number' type, since we prefer using idiomatic types. Note that this may lead to loss
// in precision for int64 fields, so use with care.
/** @hidden */
const xValueNumberFields = ['intValue', 'floatValue', 'doubleValue'];

/** @hidden */
function unwrapValue(wrapped: any): any {
const key: string = _.keys(wrapped)[0];
const value: string = unwrapValueAsString(wrapped);
Expand All @@ -476,6 +507,7 @@ function unwrapValue(wrapped: any): any {
// The JSON payload delivers timestamp fields as strings of timestamps denoted in microseconds.
// The JavaScript convention is to use numbers denoted in milliseconds. This method
// makes it easy to convert a field of one type into the other.
/** @hidden */
function copyTimestampToMillis<T, K extends keyof T>(
from: any,
to: T,
Expand All @@ -490,6 +522,7 @@ function copyTimestampToMillis<T, K extends keyof T>(
// The JSON payload delivers timestamp fields as strings of timestamps denoted in microseconds.
// In our SDK, we'd like to present timestamp as ISO-format strings. This method makes it easy
// to convert a field of one type into the other.
/** @hidden */
function copyTimestampToString<T, K extends keyof T>(
from: any,
to: T,
Expand Down