Skip to content

armgit / umami

Public Imported from GitHub
0

Umami is a privacy-first web and product analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place. No cookies, no surveillance, self-hosted or in the cloud.

chore(tracker): :label: add types for tracker

C-A de Salaberryd00d4f7343f0
diff --git a/tracker/index.d.ts b/tracker/index.d.ts
new file mode 100644
index 000000000..67cebc083
--- /dev/null
+++ b/tracker/index.d.ts
@@ -0,0 +1,138 @@
+type TrackedProperties = {
+ /**
+ * Hostname of server
+ *
+ * @description extracted from `window.location.hostname`
+ * @example 'analytics.umami.is'
+ */
+ hostname: string;
+
+ /**
+ * Browser language
+ *
+ * @description extracted from `window.navigator.language`
+ * @example 'en-US', 'fr-FR'
+ */
+ language: string;
+
+ /**
+ * Page referrer
+ *
+ * @description extracted from `window.navigator.language`
+ * @example 'https://analytics.umami.is/docs/getting-started'
+ */
+ referrer: string;
+
+ /**
+ * Screen dimensions
+ *
+ * @description extracted from `window.screen.width` and `window.screen.height`
+ * @example '1920x1080', '2560x1440'
+ */
+ screen: string;
+
+ /**
+ * Page title
+ *
+ * @description extracted from `document.querySelector('head > title')`
+ * @example 'umami'
+ */
+ title: string;
+
+ /**
+ * Page url
+ *
+ * @description built from `${window.location.pathname}${window.location.search}`
+ * @example 'docs/getting-started'
+ */
+ url: string;
+
+ /**
+ * Website ID (required)
+ *
+ * @example 'b59e9c65-ae32-47f1-8400-119fcf4861c4'
+ */
+ website: string;
+};
+
+type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] }
+
+/**
+ *
+ * Event Data can work with any JSON data. There are a few rules in place to maintain performance.
+ * - Numbers have a max precision of 4.
+ * - Strings have a max length of 500.
+ * - Arrays are converted to a String, with the same max length of 500.
+ * - Objects have a max of 50 properties. Arrays are considered 1 property.
+ */
+type EventData = Record<string, object>;
+type EventProperties = {
+ name: string;
+ data?: EventData;
+} & WithRequired<TrackedProperties, 'website'>
+| WithRequired<TrackedProperties, 'website'>;
+
+interface Window {
+ umami: {
+ track: {
+ /**
+ * Track a page view
+ *
+ * @example ```
+ * umami.track();
+ * ```
+ */
+ (): Promise<string>;
+
+ /**
+ * Track an event with a given name
+ *
+ * @example ```
+ * umami.track('signup-button');
+ * ```
+ */
+ (eventName: string): Promise<string>;
+
+ /**
+ * Tracks an event with dynamic data.
+ *
+ * When tracking events, the default properties are included in the payload. This is equivalent to running:
+ *
+ * ```js
+ * umami.track(props => ({
+ * ...props,
+ * name: 'signup-button',
+ * data: {
+ * name: 'newsletter',
+ * id: 123
+ * }
+ * }));
+ * ```
+ *
+ * @example ```
+ * umami.track('signup-button', { name: 'newsletter', id: 123 });
+ * ```
+ */
+ (eventName: string, obj: EventData): Promise<string>;
+
+ /**
+ * Tracks a page view with custom properties
+ *
+ * @example ```
+ * umami.track({ website: 'e676c9b4-11e4-4ef1-a4d7-87001773e9f2', url: '/home', title: 'Home page' });
+ * ```
+ */
+ (properties: WithRequired<Partial<TrackedProperties>, 'website'>): Promise<string>;
+
+ /**
+ * Tracks an event with fully customizable dynamic data
+ * Ilf you don't specify any `name` and/or `data`, it will be treated as a page view
+ *
+ * @example ```
+ * umami.track((props) => ({ ...props, url: path }));
+ * ```
+ */
+ (eventFunction: (prop: TrackedProperties) => EventProperties): Promise<string>;
+ };
+ };
+}