@codecademy/tracking 1.0.2 → 1.0.3-alpha.37044bcdd.0

package/dist/README.md

@@ -0,0 +1,100 @@
+# `@codecademy/tracking`
+
+This package contains our user "telemetry" (tracking metrics such as `click` and `visit`) integrations that are shared across multiple web properties.
+
+We've consolidated them here for a few reasons:
+
+- To standardize APIs around events like tracking user clicks
+- To make sure any third party integrations are CCPA & GDPR compliant
+- Because this repository already has a sweet CI setup for previewing and auto-publishing new versions 😎
+
+There are two kinds of tracking we package in this library:
+
+- **Internal** tracking ([`createTracker`](#createTracker)): sent directly to our `/analytics/` endpoint
+- **External** tracking ([`useTrackingIntegrations`](#useTrackingIntegrations)): scripts loaded via Google Tag Manager
+
+## `createTracker`
+
+Creates a "tracker" object that includes methods for user telemetry such as `click` and `visit`.
+
+```ts
+import { createTracker } from '@codecademy/tracking';
+
+const tracker = createTracker('apiBaseUrl', 'authToken');
+```
+
+### Event Usage
+
+#### `click`
+
+Tracks that a user has clicked an element on the page.
+
+```ts
+tracker.click({
+  page_name: 'my_page',
+  target: 'my_button',
+});
+```
+
+Calls to _`event`_ internally.
+
+#### `visit`
+
+Tracks that a user has visited a page or sub-page.
+
+```ts
+tracker.visit({
+  page_name: 'my_page',
+});
+```
+
+Calls to _`event`_ internally.
+
+#### `event`
+
+Generic event for any other event.
+Events that are allowed to be used here are strongly typed in the `types.d.ts` file included in the package.
+
+```ts
+tracker.event('calendar', 'reminder', data);
+```
+
+### Miscellaneous Usage
+
+#### `pushDataLayerEvent`
+
+Adds a [GTM `dataLayer` event](https://developers.google.com/tag-manager/devguide) to the global `dataLayer` array.
+If `dataLayer` does not exist, it will be created.
+
+```ts
+tracker.pushDataLayerEvent('user_sign_up');
+```
+
+## `initializeTrackingIntegrations`
+
+> See [GDPR Compliance on Notion](https://www.notion.so/codecademy/GDPR-Compliance-141ebcc7ffa542daa0da56e35f482b41) for full docs on external tracking.
+
+Starts the initialization process for our third-party integrations.
+
+Integrations are loaded in an intentionally layered manner for CCPA/GDPR compliance:
+
+1. Wait 1000ms to allow any other post-hydration logic to run first
+2. Load in OneTrust's banner and wait for its `OptanonWrapper` callback
+3. [Segment's copy-and-paste snippet](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/quickstart/#step-2-copy-the-segment-snippet) is run to load the Segment global library
+4. Destination integrations for Segment are fetched
+5. Those integrations are compared against the user's consent decisions into a list of allowed destinations
+6. We load only those allowed destinations using Segment's `analytics.load`
+
+```ts
+import { initializeTrackingIntegrations } from '@codecademy/tracking';
+
+setTimeout(() => {
+  initializeTrackingIntegrations({
+    onError: logger.error,
+    production: true,
+    scope: window,
+    user: { email: 'my@email.com', id: 'my-user-id' },
+    writeKey: 'my-segment-write-key',
+  });
+}, 1000);
+```

package/dist/events/index.d.ts

@@ -1,3 +1,3 @@
-export * from './track';
-export * from './user';
-export * from './types';
+export * from './track';
+export * from './user';
+export * from './types';

package/dist/events/track.d.ts

@@ -1,12 +1,12 @@
-import type { BaseEventData, EventDataTypes, TrackingOptions, UserClickData, UserImpressionData, UserVisitData } from './types';
-export declare type TrackerOptions = {
-    apiBaseUrl: string;
-    verbose?: boolean;
-};
-export declare const createTracker: ({ apiBaseUrl, verbose }: TrackerOptions) => {
-    event: <Category extends keyof EventDataTypes, Event_1 extends string & keyof EventDataTypes[Category], Data extends EventDataTypes[Category][Event_1] & BaseEventData>(category: Category, event: Event_1, userData: Data, options?: TrackingOptions) => void;
-    click: (data: UserClickData) => void;
-    impression: (data: UserImpressionData) => void;
-    visit: (data: UserVisitData) => void;
-    pushDataLayerEvent: (eventName: string) => void;
-};
+import type { BaseEventData, EventDataTypes, TrackingOptions, UserClickData, UserImpressionData, UserVisitData } from './types';
+export declare type TrackerOptions = {
+    apiBaseUrl: string;
+    verbose?: boolean;
+};
+export declare const createTracker: ({ apiBaseUrl, verbose }: TrackerOptions) => {
+    event: <Category extends keyof EventDataTypes, Event_1 extends string & keyof EventDataTypes[Category], Data extends EventDataTypes[Category][Event_1] & BaseEventData>(category: Category, event: Event_1, userData: Data, options?: TrackingOptions) => void;
+    click: (data: UserClickData) => void;
+    impression: (data: UserImpressionData) => void;
+    visit: (data: UserVisitData) => void;
+    pushDataLayerEvent: (eventName: string) => void;
+};

package/dist/events/types.d.ts

@@ -1,250 +1,250 @@
-/**
- * The Data types for all of our events.
- * Follows the format EventDataTypes[Category].[Event].EventData
- * Category + Event gives the corresponding event table in redshift
- */
-export declare type EventDataTypes = {
-    user: {
-        click: UserClickData;
-        visit: UserVisitData;
-        impression: UserImpressionData;
-        email_trigger: BaseEventAnyData;
-        content_completed: BaseEventAnyData;
-        submit: BaseEventAnyData;
-        workspace_init: BaseEventAnyData;
-        meaningful_content_loaded: BaseEventAnyData;
-        practice_completed: BaseEventAnyData;
-    };
-    ad: {
-        click: BaseEventAnyData;
-        impression: BaseEventAnyData;
-    };
-    calendar: {
-        reminder: BaseEventAnyData;
-    };
-    notification: {
-        clicked: BaseEventAnyData;
-        ion: BaseEventAnyData;
-    };
-    form: {
-        submit: BaseEventAnyData;
-    };
-    sorting_quiz: {
-        result: BaseEventAnyData;
-        impression: BaseEventAnyData;
-        answer: EventAnswerData;
-    };
-    onboarding_survey: {
-        answer: BaseEventAnyData;
-        recommendation: BaseEventAnyData;
-        user_selected_recommendation: BaseEventAnyData;
-    };
-    exercise: {
-        force_pass: BaseEventAnyData;
-    };
-    experiment: {
-        contentful_experiment_assignment_event: BaseEventAnyData;
-    };
-    payments: {
-        cancel_survey: BaseEventAnyData;
-    };
-    search: {
-        visit: BaseEventAnyData;
-        click: BaseEventAnyData;
-        query: BaseEventAnyData;
-        result: BaseEventAnyData;
-    };
-    page: {
-        career_path_visited: PagePathVisitedData;
-        skill_path_visited: PagePathVisitedData;
-        course_page_visited: CoursePageVisitedData;
-    };
-    business: {
-        filter_event: BusinessFilterData;
-        search_event: BusinessSearchData;
-    };
-};
-/**
- * Base event data shared by all events
- */
-export declare type BaseEventData = {
-    fullpath?: null;
-    search?: null;
-    path?: null;
-    title?: null;
-    url?: null;
-    referrer?: string | null;
-    id?: null;
-};
-/**
- * Generic type to use for event data not typed yet
- */
-export declare type BaseEventAnyData = BaseEventData & {
-    [key: string]: any;
-};
-/**
- * Options to pass to the tracking function
- */
-export declare type TrackingOptions = {
-    /** tells backend not to merge user-identifying data onto the event payload */
-    gdprSafe?: boolean;
-};
-/**
- * The Content IDs related to the current event, to help build the content context of the event.
- * These IDs get hashed into a single value and overwrite content_id before they are sent to
- * redshift in lib/content_group_id.rb
- */
-export declare type TrackingContentIds = {
-    assessment_id?: string;
-    content_item_id?: string;
-    exercise_id?: string;
-    learning_standard_id?: string;
-    module_id?: string;
-    path_id?: string;
-    program_id?: string;
-    program_unit_id?: string;
-    review_card_id?: string;
-    track_id?: string;
-    journey_id?: string;
-};
-/**
- * Shared data relevant for all user events
- */
-export declare type UserSharedData = BaseEventData & {
-    /** the click target of the event */
-    target?: string;
-    /** the page the event is coming from */
-    page_name?: string;
-    /** a context id for the event, for events that occur in more than one place */
-    context?: string;
-    /** the link being clicked on */
-    href?: string;
-    /** a version id for the element (ex. different version ids for redesigns) */
-    version?: string;
-    /** an object of content ids related to this event */
-    content_ids?: TrackingContentIds;
-    /** the repo that this event is being fired from */
-    source_codebase?: string;
-    /** Should be used for arbitrary JSON that has been passed through JSON.stringify. */
-    misc?: string;
-};
-/**
- * Data sent to user click event table
- * NOTE: avoid adding additional properties to these objects
- * Instead, reuse existing properties, or make any additional properties generic so that they can be reused.
- * https://www.notion.so/codecademy/Guide-to-Event-Tracking-Schema-5d40b09a297743f7a30a2690208194c8#800bbf6cdf2e44de9823cd75bcc574e5
- */
-export declare type UserClickData = UserSharedData & {
-    target: string;
-    id?: string;
-    distinct_id?: string;
-    content_id?: string;
-    slug?: string;
-    name?: string;
-    action?: string;
-    type?: string;
-    location?: string;
-    element?: string;
-    weekly_goal?: string | number;
-    complete?: string;
-    video_url?: string;
-    path_id?: string;
-    path_slug?: string;
-    event_name?: string;
-    onboarding_entrypoint?: string;
-    content_slug?: string;
-    module_id?: string;
-    track_slug?: string;
-    module_slug?: string;
-    button?: string;
-    current_challenge_day?: string | number;
-    track_id?: string;
-    course?: string;
-    path_name?: string;
-    event_id?: string;
-    unit?: string;
-    lesson?: string;
-    community_prompt?: string;
-    contentItem?: any;
-    unit_slug?: string;
-    course_slug?: string;
-    course_progress?: number;
-    assessment_id?: string;
-    container_slugs?: string[];
-    search_id?: string;
-    is_ugc?: boolean;
-    business_user?: BaseEventAnyData;
-};
-/**
- * Data sent to user visit event table
- * NOTE: avoid adding additional properties to these objects
- * Instead, reuse existing properties, or make any additional properties generic so that they can be reused.
- * https://www.notion.so/codecademy/Guide-to-Event-Tracking-Schema-5d40b09a297743f7a30a2690208194c8#800bbf6cdf2e44de9823cd75bcc574e5
- */
-export declare type UserVisitData = UserSharedData & {
-    page_name: string;
-    category?: string;
-    distinct_id?: string;
-    type?: string;
-    target?: string;
-    section?: string;
-    plan?: string;
-    path_id?: string;
-    post?: string;
-    story_type?: string;
-    path_title?: string;
-    onboarding_entrypoint?: string;
-    course_slug?: string;
-    course?: string;
-    interstitial_name?: string;
-    content_id?: string;
-    story_slug?: string;
-    unit?: string;
-    lesson?: string;
-    is_ugc?: boolean;
-};
-export declare type UserImpressionData = Pick<UserSharedData, 'context' | 'source_codebase' | 'content_ids'> & {
-    page_name: string;
-    target: string;
-    slug?: string;
-    is_ugc?: boolean;
-};
-export declare type EventAnswerData = BaseEventData & {
-    question_index: number;
-    answer_index: number;
-    answer: any;
-    answer_slug: string;
-};
-export declare type User = {
-    id?: string;
-    auth_token: string;
-    profile_image_url?: string;
-    email?: string;
-    is_pro?: boolean;
-    username?: string;
-    location: {
-        in_eu: boolean;
-        geo_country: string;
-    };
-    features: string[];
-};
-export declare type UseUserResponse = {
-    user?: User;
-    status: string;
-};
-export declare type PagePathVisitedData = BaseEventData & {
-    path_id: string;
-    path_full_title: string;
-};
-export declare type CoursePageVisitedData = BaseEventData & {
-    course_id: string;
-    course_full_title: string;
-};
-export declare type FilterType = string | string[] | number | boolean;
-export declare type BusinessFilterData = BaseEventData & {
-    filter_key: string;
-    filter_value: FilterType;
-};
-export declare type BusinessSearchData = BaseEventData & {
-    search_query: string;
-};
+/**
+ * The Data types for all of our events.
+ * Follows the format EventDataTypes[Category].[Event].EventData
+ * Category + Event gives the corresponding event table in redshift
+ */
+export declare type EventDataTypes = {
+    user: {
+        click: UserClickData;
+        visit: UserVisitData;
+        impression: UserImpressionData;
+        email_trigger: BaseEventAnyData;
+        content_completed: BaseEventAnyData;
+        submit: BaseEventAnyData;
+        workspace_init: BaseEventAnyData;
+        meaningful_content_loaded: BaseEventAnyData;
+        practice_completed: BaseEventAnyData;
+    };
+    ad: {
+        click: BaseEventAnyData;
+        impression: BaseEventAnyData;
+    };
+    calendar: {
+        reminder: BaseEventAnyData;
+    };
+    notification: {
+        clicked: BaseEventAnyData;
+        ion: BaseEventAnyData;
+    };
+    form: {
+        submit: BaseEventAnyData;
+    };
+    sorting_quiz: {
+        result: BaseEventAnyData;
+        impression: BaseEventAnyData;
+        answer: EventAnswerData;
+    };
+    onboarding_survey: {
+        answer: BaseEventAnyData;
+        recommendation: BaseEventAnyData;
+        user_selected_recommendation: BaseEventAnyData;
+    };
+    exercise: {
+        force_pass: BaseEventAnyData;
+    };
+    experiment: {
+        contentful_experiment_assignment_event: BaseEventAnyData;
+    };
+    payments: {
+        cancel_survey: BaseEventAnyData;
+    };
+    search: {
+        visit: BaseEventAnyData;
+        click: BaseEventAnyData;
+        query: BaseEventAnyData;
+        result: BaseEventAnyData;
+    };
+    page: {
+        career_path_visited: PagePathVisitedData;
+        skill_path_visited: PagePathVisitedData;
+        course_page_visited: CoursePageVisitedData;
+    };
+    business: {
+        filter_event: BusinessFilterData;
+        search_event: BusinessSearchData;
+    };
+};
+/**
+ * Base event data shared by all events
+ */
+export declare type BaseEventData = {
+    fullpath?: null;
+    search?: null;
+    path?: null;
+    title?: null;
+    url?: null;
+    referrer?: string | null;
+    id?: null;
+};
+/**
+ * Generic type to use for event data not typed yet
+ */
+export declare type BaseEventAnyData = BaseEventData & {
+    [key: string]: any;
+};
+/**
+ * Options to pass to the tracking function
+ */
+export declare type TrackingOptions = {
+    /** tells backend not to merge user-identifying data onto the event payload */
+    gdprSafe?: boolean;
+};
+/**
+ * The Content IDs related to the current event, to help build the content context of the event.
+ * These IDs get hashed into a single value and overwrite content_id before they are sent to
+ * redshift in lib/content_group_id.rb
+ */
+export declare type TrackingContentIds = {
+    assessment_id?: string;
+    content_item_id?: string;
+    exercise_id?: string;
+    learning_standard_id?: string;
+    module_id?: string;
+    path_id?: string;
+    program_id?: string;
+    program_unit_id?: string;
+    review_card_id?: string;
+    track_id?: string;
+    journey_id?: string;
+};
+/**
+ * Shared data relevant for all user events
+ */
+export declare type UserSharedData = BaseEventData & {
+    /** the click target of the event */
+    target?: string;
+    /** the page the event is coming from */
+    page_name?: string;
+    /** a context id for the event, for events that occur in more than one place */
+    context?: string;
+    /** the link being clicked on */
+    href?: string;
+    /** a version id for the element (ex. different version ids for redesigns) */
+    version?: string;
+    /** an object of content ids related to this event */
+    content_ids?: TrackingContentIds;
+    /** the repo that this event is being fired from */
+    source_codebase?: string;
+    /** Should be used for arbitrary JSON that has been passed through JSON.stringify. */
+    misc?: string;
+};
+/**
+ * Data sent to user click event table
+ * NOTE: avoid adding additional properties to these objects
+ * Instead, reuse existing properties, or make any additional properties generic so that they can be reused.
+ * https://www.notion.so/codecademy/Guide-to-Event-Tracking-Schema-5d40b09a297743f7a30a2690208194c8#800bbf6cdf2e44de9823cd75bcc574e5
+ */
+export declare type UserClickData = UserSharedData & {
+    target: string;
+    id?: string;
+    distinct_id?: string;
+    content_id?: string;
+    slug?: string;
+    name?: string;
+    action?: string;
+    type?: string;
+    location?: string;
+    element?: string;
+    weekly_goal?: string | number;
+    complete?: string;
+    video_url?: string;
+    path_id?: string;
+    path_slug?: string;
+    event_name?: string;
+    onboarding_entrypoint?: string;
+    content_slug?: string;
+    module_id?: string;
+    track_slug?: string;
+    module_slug?: string;
+    button?: string;
+    current_challenge_day?: string | number;
+    track_id?: string;
+    course?: string;
+    path_name?: string;
+    event_id?: string;
+    unit?: string;
+    lesson?: string;
+    community_prompt?: string;
+    contentItem?: any;
+    unit_slug?: string;
+    course_slug?: string;
+    course_progress?: number;
+    assessment_id?: string;
+    container_slugs?: string[];
+    search_id?: string;
+    is_ugc?: boolean;
+    business_user?: BaseEventAnyData;
+};
+/**
+ * Data sent to user visit event table
+ * NOTE: avoid adding additional properties to these objects
+ * Instead, reuse existing properties, or make any additional properties generic so that they can be reused.
+ * https://www.notion.so/codecademy/Guide-to-Event-Tracking-Schema-5d40b09a297743f7a30a2690208194c8#800bbf6cdf2e44de9823cd75bcc574e5
+ */
+export declare type UserVisitData = UserSharedData & {
+    page_name: string;
+    category?: string;
+    distinct_id?: string;
+    type?: string;
+    target?: string;
+    section?: string;
+    plan?: string;
+    path_id?: string;
+    post?: string;
+    story_type?: string;
+    path_title?: string;
+    onboarding_entrypoint?: string;
+    course_slug?: string;
+    course?: string;
+    interstitial_name?: string;
+    content_id?: string;
+    story_slug?: string;
+    unit?: string;
+    lesson?: string;
+    is_ugc?: boolean;
+};
+export declare type UserImpressionData = Pick<UserSharedData, 'context' | 'source_codebase' | 'content_ids'> & {
+    page_name: string;
+    target: string;
+    slug?: string;
+    is_ugc?: boolean;
+};
+export declare type EventAnswerData = BaseEventData & {
+    question_index: number;
+    answer_index: number;
+    answer: any;
+    answer_slug: string;
+};
+export declare type User = {
+    id?: string;
+    auth_token: string;
+    profile_image_url?: string;
+    email?: string;
+    is_pro?: boolean;
+    username?: string;
+    location: {
+        in_eu: boolean;
+        geo_country: string;
+    };
+    features: string[];
+};
+export declare type UseUserResponse = {
+    user?: User;
+    status: string;
+};
+export declare type PagePathVisitedData = BaseEventData & {
+    path_id: string;
+    path_full_title: string;
+};
+export declare type CoursePageVisitedData = BaseEventData & {
+    course_id: string;
+    course_full_title: string;
+};
+export declare type FilterType = string | string[] | number | boolean;
+export declare type BusinessFilterData = BaseEventData & {
+    filter_key: string;
+    filter_value: FilterType;
+};
+export declare type BusinessSearchData = BaseEventData & {
+    search_query: string;
+};

package/dist/events/user.d.ts

@@ -1,2 +1,2 @@
-import { User } from './types';
-export declare const fetchUser: (apiBaseUrl: string) => Promise<User>;
+import { User } from './types';
+export declare const fetchUser: (apiBaseUrl: string) => Promise<User>;