From b539c5e3c0cf33de474cda4b31a399308abebbaa Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Mon, 11 Sep 2023 02:35:51 -0700 Subject: [PATCH 01/14] feat(global user properties): add global properties plugin base code without tests --- packages/analytics-types/src/base-event.ts | 1 + packages/analytics-types/src/event.ts | 10 +- .../CHANGELOG.md | 0 .../README.md | 96 +++++++++++++++++++ .../jest.config.js | 10 ++ .../package.json | 57 +++++++++++ .../rollup.config.js | 3 + .../src/global-user-properties.ts | 30 ++++++ .../src/helpers.ts | 7 ++ .../src/index.ts | 2 + .../src/typings/global-user-properties.ts | 12 +++ .../test/web-attribution.test.ts | 0 .../tsconfig.es5.json | 10 ++ .../tsconfig.esm.json | 10 ++ .../tsconfig.json | 11 +++ 15 files changed, 254 insertions(+), 5 deletions(-) create mode 100644 packages/plugin-global-user-properties.ts/CHANGELOG.md create mode 100644 packages/plugin-global-user-properties.ts/README.md create mode 100644 packages/plugin-global-user-properties.ts/jest.config.js create mode 100644 packages/plugin-global-user-properties.ts/package.json create mode 100644 packages/plugin-global-user-properties.ts/rollup.config.js create mode 100644 packages/plugin-global-user-properties.ts/src/global-user-properties.ts create mode 100644 packages/plugin-global-user-properties.ts/src/helpers.ts create mode 100644 packages/plugin-global-user-properties.ts/src/index.ts create mode 100644 packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts create mode 100644 packages/plugin-global-user-properties.ts/test/web-attribution.test.ts create mode 100644 packages/plugin-global-user-properties.ts/tsconfig.es5.json create mode 100644 packages/plugin-global-user-properties.ts/tsconfig.esm.json create mode 100644 packages/plugin-global-user-properties.ts/tsconfig.json diff --git a/packages/analytics-types/src/base-event.ts b/packages/analytics-types/src/base-event.ts index 8585c3fb3..32cbd51ec 100644 --- a/packages/analytics-types/src/base-event.ts +++ b/packages/analytics-types/src/base-event.ts @@ -3,6 +3,7 @@ import { IngestionMetadataEventProperty } from './ingestion-metadata'; export interface BaseEvent extends EventOptions { event_type: string; + global_user_properties?: { [key: string]: any } | undefined; event_properties?: { [key: string]: any } | undefined; user_properties?: { [key: string]: any } | undefined; group_properties?: { [key: string]: any } | undefined; diff --git a/packages/analytics-types/src/event.ts b/packages/analytics-types/src/event.ts index 3bd456abb..03c65f525 100644 --- a/packages/analytics-types/src/event.ts +++ b/packages/analytics-types/src/event.ts @@ -64,6 +64,10 @@ export interface IdentifyUserProperties { [IdentifyOperation.REMOVE]?: BaseOperationConfig; } +export type UserProperties = IdentifyUserProperties | { + [key in Exclude]: any; +} + export interface Revenue { getEventProperties(): RevenueEventProperties; setProductId(productId: string): Revenue; @@ -107,11 +111,7 @@ export interface TrackEvent extends BaseEvent { export interface IdentifyEvent extends BaseEvent { event_type: SpecialEventType.IDENTIFY; - user_properties: - | IdentifyUserProperties - | { - [key in Exclude]: any; - }; + user_properties: UserProperties; } export interface GroupIdentifyEvent extends BaseEvent { diff --git a/packages/plugin-global-user-properties.ts/CHANGELOG.md b/packages/plugin-global-user-properties.ts/CHANGELOG.md new file mode 100644 index 000000000..e69de29bb diff --git a/packages/plugin-global-user-properties.ts/README.md b/packages/plugin-global-user-properties.ts/README.md new file mode 100644 index 000000000..3dd4f9d37 --- /dev/null +++ b/packages/plugin-global-user-properties.ts/README.md @@ -0,0 +1,96 @@ +

+ + + +
+

+ +# @amplitude/plugin-web-attribution-browser + +Official Browser SDK plugin for web attribution tracking + +## Installation + +This package is published on NPM registry and is available to be installed using npm and yarn. + +```sh +# npm +npm install @amplitude/plugin-web-attribution-browser + +# yarn +yarn add @amplitude/plugin-web-attribution-browser +``` + +## Usage + +This plugin works on top of Amplitude Browser SDK and adds web attribution tracking features to built-in features. To use this plugin, you need to install `@amplitude/analytics-browser` version `v2.0.0` or later. + +### 1. Import Amplitude packages + +* `@amplitude/plugin-web-attribution-browser` + +```typescript +import { webAttributionPlugin } from '@amplitude/plugin-web-attribution-browser'; +``` + +### 2. Instantiate page view plugin + +The plugin accepts an optional parameter of type `Object` to configure the plugin based on your use case. + +```typescript +const webAttributionTracking = webAttributionPlugin(amplitude, { + excludeReferrers: undefined, + initialEmptyValue: undefined, + resetSessionOnNewCampaign: undefined, +}); +``` + +#### Options + +|Name|Type|Default|Description| +|-|-|-|-| +|`excludeReferrers`|`(string \| RegExp)[]`|`[]`|Use this option to prevent the plugin from tracking campaigns parameters from specific referrers. For example: `subdomain.domain.com`.| +|`initialEmptyValue`|`string`|`"EMPTY"`|Use this option to specify empty values for [first-touch attribution](https://www.docs.developers.amplitude.com/data/sdks/marketing-analytics-browser/#first-touch-attribution).| +|`resetSessionOnNewCampaign`|`boolean`|`false`|Use this option to control whether a new session should start on a new campaign.| + +### 3. Install plugin to Amplitude SDK + +```typescript +amplitude.add(webAttributionTracking); +``` + +### 4. Initialize Amplitude SDK + +```typescript +amplitude.init('API_KEY'); +``` + +## Resulting web attribution event + +This plugin tracks campaign parameters based on your configuration. A web attribution event is composed of the following values: + +#### Event type +* `"$idenfity"` + +#### User properties + +|Property|Description| +|-|-| +|`utm_source`|URL query parameter value for `utm_source`| +|`utm_medium`|URL query parameter value for `utm_medium`| +|`utm_campaign`|URL query parameter value for `utm_campaign`| +|`utm_term`|URL query parameter value for `utm_term`| +|`utm_content`|URL query parameter value for `utm_content`| +|`referrer`|Referring webstite or `document.referrer`| +|`referring_domain`|Referring website's domain, including subdomain| +|`dclid`|URL query parameter value for `dclid`| +|`gbraid`|URL query parameter value for `gbraid`| +|`gclid`|URL query parameter value for `gclid`| +|`fbclid`|URL query parameter value for `fbclid`| +|`ko_click_id`|URL query parameter value for `ko_click_id`| +|`li_fat_id`|URL query parameter value for `li_fat_id`| +|`msclkid`|URL query parameter value for `msclkid`| +|`rtd_cid`|URL query parameter value for `rtd_cid`| +|`ttclid`|URL query parameter value for `ttclid`| +|`twclid`|URL query parameter value for `twclid`| +|`wbraid`|URL query parameter value for `wbraid`| diff --git a/packages/plugin-global-user-properties.ts/jest.config.js b/packages/plugin-global-user-properties.ts/jest.config.js new file mode 100644 index 000000000..dc4094b18 --- /dev/null +++ b/packages/plugin-global-user-properties.ts/jest.config.js @@ -0,0 +1,10 @@ +const baseConfig = require('../../jest.config.js'); +const package = require('./package'); + +module.exports = { + ...baseConfig, + displayName: package.name, + rootDir: '.', + testEnvironment: 'jsdom', + coveragePathIgnorePatterns: ['index.ts'], +}; diff --git a/packages/plugin-global-user-properties.ts/package.json b/packages/plugin-global-user-properties.ts/package.json new file mode 100644 index 000000000..aa0974b92 --- /dev/null +++ b/packages/plugin-global-user-properties.ts/package.json @@ -0,0 +1,57 @@ +{ + "name": "@amplitude/plugin-global-user-properties", + "version": "2.1.0", + "description": "", + "author": "Amplitude Inc", + "homepage": "https://github.com/amplitude/Amplitude-TypeScript", + "license": "MIT", + "main": "lib/cjs/index.js", + "module": "lib/esm/index.js", + "types": "lib/esm/index.d.ts", + "sideEffects": false, + "publishConfig": { + "access": "public", + "tag": "latest" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/amplitude/Amplitude-TypeScript.git" + }, + "scripts": { + "build": "yarn bundle && yarn build:es5 && yarn build:esm", + "bundle": "rollup --config rollup.config.js", + "build:es5": "tsc -p ./tsconfig.es5.json", + "build:esm": "tsc -p ./tsconfig.esm.json", + "clean": "rimraf node_modules lib coverage", + "fix": "yarn fix:eslint & yarn fix:prettier", + "fix:eslint": "eslint '{src,test}/**/*.ts' --fix", + "fix:prettier": "prettier --write \"{src,test}/**/*.ts\"", + "lint": "yarn lint:eslint & yarn lint:prettier", + "lint:eslint": "eslint '{src,test}/**/*.ts'", + "lint:prettier": "prettier --check \"{src,test}/**/*.ts\"", + "test": "jest", + "typecheck": "tsc -p ./tsconfig.json" + }, + "bugs": { + "url": "https://github.com/amplitude/Amplitude-TypeScript/issues" + }, + "dependencies": { + "@amplitude/analytics-client-common": "^2.0.5", + "@amplitude/analytics-core": "^2.0.4", + "@amplitude/analytics-types": "^2.1.2", + "tslib": "^2.4.1" + }, + "devDependencies": { + "@amplitude/analytics-browser": "^2.2.3", + "@rollup/plugin-commonjs": "^23.0.4", + "@rollup/plugin-node-resolve": "^15.0.1", + "@rollup/plugin-typescript": "^10.0.1", + "rollup": "^2.79.1", + "rollup-plugin-execute": "^1.1.1", + "rollup-plugin-gzip": "^3.1.0", + "rollup-plugin-terser": "^7.0.2" + }, + "files": [ + "lib" + ] +} diff --git a/packages/plugin-global-user-properties.ts/rollup.config.js b/packages/plugin-global-user-properties.ts/rollup.config.js new file mode 100644 index 000000000..2718b91d7 --- /dev/null +++ b/packages/plugin-global-user-properties.ts/rollup.config.js @@ -0,0 +1,3 @@ +import { umd } from '../../scripts/build/rollup.config'; + +export default [umd]; diff --git a/packages/plugin-global-user-properties.ts/src/global-user-properties.ts b/packages/plugin-global-user-properties.ts/src/global-user-properties.ts new file mode 100644 index 000000000..bd0acc1ff --- /dev/null +++ b/packages/plugin-global-user-properties.ts/src/global-user-properties.ts @@ -0,0 +1,30 @@ +import { BeforePlugin, Event } from '@amplitude/analytics-types'; +import { GlobalUserPropertiesPlugin, Options } from './typings/global-user-properties'; +import { isSpecialAmplitudeEvent } from 'src/helpers'; + + +export const globalUserPropertiesPlugin: GlobalUserPropertiesPlugin = function (options: Options = {}) { + const plugin: BeforePlugin = { + name: '@amplitude/plugin-web-attribution-browser', + type: 'before', + + setup: () => {}, + + execute: (event: Event): Event => { + // Skip amplitude special events + if (isSpecialAmplitudeEvent(event)) { + return event; + }; + + event.global_user_properties = event.user_properties; + + if (!options.shouldKeepOriginalUserProperties) { + delete event.global_user_properties; + } + + return event; + }, + }; + + return plugin; +}; diff --git a/packages/plugin-global-user-properties.ts/src/helpers.ts b/packages/plugin-global-user-properties.ts/src/helpers.ts new file mode 100644 index 000000000..33a6c6640 --- /dev/null +++ b/packages/plugin-global-user-properties.ts/src/helpers.ts @@ -0,0 +1,7 @@ +import { Event, BaseEvent, SpecialEventType } from "@amplitude/analytics-types" + +const specialAmplitudeEvents = new Set(Object.values(SpecialEventType)); + +export const isSpecialAmplitudeEvent = (event: Event): event is BaseEvent => { + return specialAmplitudeEvents.has(event.event_type as SpecialEventType); +} \ No newline at end of file diff --git a/packages/plugin-global-user-properties.ts/src/index.ts b/packages/plugin-global-user-properties.ts/src/index.ts new file mode 100644 index 000000000..3475d4f06 --- /dev/null +++ b/packages/plugin-global-user-properties.ts/src/index.ts @@ -0,0 +1,2 @@ +export { webAttributionPlugin } from './global-user-properties'; +export { webAttributionPlugin as plugin } from './global-user-properties'; diff --git a/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts b/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts new file mode 100644 index 000000000..f32386ca5 --- /dev/null +++ b/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts @@ -0,0 +1,12 @@ +import { BeforePlugin } from '@amplitude/analytics-types'; + +export interface Options { + /** + * Whether or not the orignal user_properties field should be kept on the event + */ + shouldKeepOriginalUserProperties?: boolean; +} + +export interface GlobalUserPropertiesPlugin { + (options?: Options): BeforePlugin; +} diff --git a/packages/plugin-global-user-properties.ts/test/web-attribution.test.ts b/packages/plugin-global-user-properties.ts/test/web-attribution.test.ts new file mode 100644 index 000000000..e69de29bb diff --git a/packages/plugin-global-user-properties.ts/tsconfig.es5.json b/packages/plugin-global-user-properties.ts/tsconfig.es5.json new file mode 100644 index 000000000..77e041d3f --- /dev/null +++ b/packages/plugin-global-user-properties.ts/tsconfig.es5.json @@ -0,0 +1,10 @@ +{ + "extends": "./tsconfig.json", + "include": ["src/**/*"], + "compilerOptions": { + "module": "commonjs", + "noEmit": false, + "outDir": "lib/cjs", + "rootDir": "./src" + } +} diff --git a/packages/plugin-global-user-properties.ts/tsconfig.esm.json b/packages/plugin-global-user-properties.ts/tsconfig.esm.json new file mode 100644 index 000000000..bec981eee --- /dev/null +++ b/packages/plugin-global-user-properties.ts/tsconfig.esm.json @@ -0,0 +1,10 @@ +{ + "extends": "./tsconfig.json", + "include": ["src/**/*"], + "compilerOptions": { + "module": "es6", + "noEmit": false, + "outDir": "lib/esm", + "rootDir": "./src" + } +} diff --git a/packages/plugin-global-user-properties.ts/tsconfig.json b/packages/plugin-global-user-properties.ts/tsconfig.json new file mode 100644 index 000000000..955dcce78 --- /dev/null +++ b/packages/plugin-global-user-properties.ts/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../tsconfig.json", + "include": ["src/**/*", "test/**/*"], + "compilerOptions": { + "baseUrl": ".", + "esModuleInterop": true, + "lib": ["dom"], + "noEmit": true, + "rootDir": ".", + } +} From 6a432d2c60260976f55e728a3eee8fec189715d6 Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Mon, 11 Sep 2023 02:51:18 -0700 Subject: [PATCH 02/14] fix(global user properties): type fixes from building --- .../package.json | 2 -- .../src/global-user-properties.ts | 29 +++++++++---------- .../src/helpers.ts | 4 +-- .../src/index.ts | 5 ++-- .../src/typings/global-user-properties.ts | 4 +-- ...tion.test.ts => global-user-properties.ts} | 0 6 files changed, 21 insertions(+), 23 deletions(-) rename packages/plugin-global-user-properties.ts/test/{web-attribution.test.ts => global-user-properties.ts} (100%) diff --git a/packages/plugin-global-user-properties.ts/package.json b/packages/plugin-global-user-properties.ts/package.json index aa0974b92..fd15c99ac 100644 --- a/packages/plugin-global-user-properties.ts/package.json +++ b/packages/plugin-global-user-properties.ts/package.json @@ -36,8 +36,6 @@ "url": "https://github.com/amplitude/Amplitude-TypeScript/issues" }, "dependencies": { - "@amplitude/analytics-client-common": "^2.0.5", - "@amplitude/analytics-core": "^2.0.4", "@amplitude/analytics-types": "^2.1.2", "tslib": "^2.4.1" }, diff --git a/packages/plugin-global-user-properties.ts/src/global-user-properties.ts b/packages/plugin-global-user-properties.ts/src/global-user-properties.ts index bd0acc1ff..ec329b9be 100644 --- a/packages/plugin-global-user-properties.ts/src/global-user-properties.ts +++ b/packages/plugin-global-user-properties.ts/src/global-user-properties.ts @@ -1,26 +1,25 @@ -import { BeforePlugin, Event } from '@amplitude/analytics-types'; +import { EnrichmentPlugin, Event } from '@amplitude/analytics-types'; import { GlobalUserPropertiesPlugin, Options } from './typings/global-user-properties'; -import { isSpecialAmplitudeEvent } from 'src/helpers'; +import { isNotSpecialAmplitudeEvent } from 'src/helpers'; export const globalUserPropertiesPlugin: GlobalUserPropertiesPlugin = function (options: Options = {}) { - const plugin: BeforePlugin = { - name: '@amplitude/plugin-web-attribution-browser', - type: 'before', + const plugin: EnrichmentPlugin = { + name: '@amplitude/plugin-global-user-properties', + type: 'enrichment', - setup: () => {}, + setup: async () => {}, - execute: (event: Event): Event => { + /* Note: The promise is because of the interface, not because this has any asynchronous behavior */ + execute: async (event: Event): Promise => { // Skip amplitude special events - if (isSpecialAmplitudeEvent(event)) { - return event; - }; - - event.global_user_properties = event.user_properties; + if (isNotSpecialAmplitudeEvent(event)) { + event.global_user_properties = event.user_properties; - if (!options.shouldKeepOriginalUserProperties) { - delete event.global_user_properties; - } + if (!options.shouldKeepOriginalUserProperties) { + delete event.global_user_properties; + } + }; return event; }, diff --git a/packages/plugin-global-user-properties.ts/src/helpers.ts b/packages/plugin-global-user-properties.ts/src/helpers.ts index 33a6c6640..0d1ed8123 100644 --- a/packages/plugin-global-user-properties.ts/src/helpers.ts +++ b/packages/plugin-global-user-properties.ts/src/helpers.ts @@ -2,6 +2,6 @@ import { Event, BaseEvent, SpecialEventType } from "@amplitude/analytics-types" const specialAmplitudeEvents = new Set(Object.values(SpecialEventType)); -export const isSpecialAmplitudeEvent = (event: Event): event is BaseEvent => { - return specialAmplitudeEvents.has(event.event_type as SpecialEventType); +export const isNotSpecialAmplitudeEvent = (event: Event): event is BaseEvent => { + return !specialAmplitudeEvents.has(event.event_type as SpecialEventType); } \ No newline at end of file diff --git a/packages/plugin-global-user-properties.ts/src/index.ts b/packages/plugin-global-user-properties.ts/src/index.ts index 3475d4f06..5f28586cd 100644 --- a/packages/plugin-global-user-properties.ts/src/index.ts +++ b/packages/plugin-global-user-properties.ts/src/index.ts @@ -1,2 +1,3 @@ -export { webAttributionPlugin } from './global-user-properties'; -export { webAttributionPlugin as plugin } from './global-user-properties'; +export { globalUserPropertiesPlugin } from './global-user-properties'; +export { globalUserPropertiesPlugin as plugin } from './global-user-properties'; +export { GlobalUserPropertiesPlugin, Options } from './typings/global-user-properties' diff --git a/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts b/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts index f32386ca5..86cab15aa 100644 --- a/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts +++ b/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts @@ -1,4 +1,4 @@ -import { BeforePlugin } from '@amplitude/analytics-types'; +import { EnrichmentPlugin } from '@amplitude/analytics-types'; export interface Options { /** @@ -8,5 +8,5 @@ export interface Options { } export interface GlobalUserPropertiesPlugin { - (options?: Options): BeforePlugin; + (options?: Options): EnrichmentPlugin; } diff --git a/packages/plugin-global-user-properties.ts/test/web-attribution.test.ts b/packages/plugin-global-user-properties.ts/test/global-user-properties.ts similarity index 100% rename from packages/plugin-global-user-properties.ts/test/web-attribution.test.ts rename to packages/plugin-global-user-properties.ts/test/global-user-properties.ts From 84bdbef3697aba4838ac5cfdddefa85f50420dd7 Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Mon, 11 Sep 2023 04:46:27 -0700 Subject: [PATCH 03/14] fix(global user properties): test, and fix filename --- packages/analytics-types/src/event.ts | 9 ++- .../src/helpers.ts | 7 -- .../test/global-user-properties.ts | 0 .../CHANGELOG.md | 0 .../README.md | 0 .../jest.config.js | 0 .../package.json | 0 .../rollup.config.js | 0 .../src/global-user-properties.ts | 14 ++-- .../src/helpers.ts | 11 +++ .../src/index.ts | 2 +- .../src/typings/global-user-properties.ts | 6 +- .../test/global-user-properties.test.ts | 72 +++++++++++++++++++ .../tsconfig.es5.json | 0 .../tsconfig.esm.json | 0 .../tsconfig.json | 0 16 files changed, 98 insertions(+), 23 deletions(-) delete mode 100644 packages/plugin-global-user-properties.ts/src/helpers.ts delete mode 100644 packages/plugin-global-user-properties.ts/test/global-user-properties.ts rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/CHANGELOG.md (100%) rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/README.md (100%) rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/jest.config.js (100%) rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/package.json (100%) rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/rollup.config.js (100%) rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/src/global-user-properties.ts (74%) create mode 100644 packages/plugin-global-user-properties/src/helpers.ts rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/src/index.ts (90%) rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/src/typings/global-user-properties.ts (90%) create mode 100644 packages/plugin-global-user-properties/test/global-user-properties.test.ts rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/tsconfig.es5.json (100%) rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/tsconfig.esm.json (100%) rename packages/{plugin-global-user-properties.ts => plugin-global-user-properties}/tsconfig.json (100%) diff --git a/packages/analytics-types/src/event.ts b/packages/analytics-types/src/event.ts index 03c65f525..8866e3cf6 100644 --- a/packages/analytics-types/src/event.ts +++ b/packages/analytics-types/src/event.ts @@ -64,9 +64,11 @@ export interface IdentifyUserProperties { [IdentifyOperation.REMOVE]?: BaseOperationConfig; } -export type UserProperties = IdentifyUserProperties | { - [key in Exclude]: any; -} +export type UserProperties = + | IdentifyUserProperties + | { + [key in Exclude]: any; + }; export interface Revenue { getEventProperties(): RevenueEventProperties; @@ -111,6 +113,7 @@ export interface TrackEvent extends BaseEvent { export interface IdentifyEvent extends BaseEvent { event_type: SpecialEventType.IDENTIFY; + global_user_properties?: UserProperties; user_properties: UserProperties; } diff --git a/packages/plugin-global-user-properties.ts/src/helpers.ts b/packages/plugin-global-user-properties.ts/src/helpers.ts deleted file mode 100644 index 0d1ed8123..000000000 --- a/packages/plugin-global-user-properties.ts/src/helpers.ts +++ /dev/null @@ -1,7 +0,0 @@ -import { Event, BaseEvent, SpecialEventType } from "@amplitude/analytics-types" - -const specialAmplitudeEvents = new Set(Object.values(SpecialEventType)); - -export const isNotSpecialAmplitudeEvent = (event: Event): event is BaseEvent => { - return !specialAmplitudeEvents.has(event.event_type as SpecialEventType); -} \ No newline at end of file diff --git a/packages/plugin-global-user-properties.ts/test/global-user-properties.ts b/packages/plugin-global-user-properties.ts/test/global-user-properties.ts deleted file mode 100644 index e69de29bb..000000000 diff --git a/packages/plugin-global-user-properties.ts/CHANGELOG.md b/packages/plugin-global-user-properties/CHANGELOG.md similarity index 100% rename from packages/plugin-global-user-properties.ts/CHANGELOG.md rename to packages/plugin-global-user-properties/CHANGELOG.md diff --git a/packages/plugin-global-user-properties.ts/README.md b/packages/plugin-global-user-properties/README.md similarity index 100% rename from packages/plugin-global-user-properties.ts/README.md rename to packages/plugin-global-user-properties/README.md diff --git a/packages/plugin-global-user-properties.ts/jest.config.js b/packages/plugin-global-user-properties/jest.config.js similarity index 100% rename from packages/plugin-global-user-properties.ts/jest.config.js rename to packages/plugin-global-user-properties/jest.config.js diff --git a/packages/plugin-global-user-properties.ts/package.json b/packages/plugin-global-user-properties/package.json similarity index 100% rename from packages/plugin-global-user-properties.ts/package.json rename to packages/plugin-global-user-properties/package.json diff --git a/packages/plugin-global-user-properties.ts/rollup.config.js b/packages/plugin-global-user-properties/rollup.config.js similarity index 100% rename from packages/plugin-global-user-properties.ts/rollup.config.js rename to packages/plugin-global-user-properties/rollup.config.js diff --git a/packages/plugin-global-user-properties.ts/src/global-user-properties.ts b/packages/plugin-global-user-properties/src/global-user-properties.ts similarity index 74% rename from packages/plugin-global-user-properties.ts/src/global-user-properties.ts rename to packages/plugin-global-user-properties/src/global-user-properties.ts index ec329b9be..42efdeb79 100644 --- a/packages/plugin-global-user-properties.ts/src/global-user-properties.ts +++ b/packages/plugin-global-user-properties/src/global-user-properties.ts @@ -1,25 +1,21 @@ import { EnrichmentPlugin, Event } from '@amplitude/analytics-types'; import { GlobalUserPropertiesPlugin, Options } from './typings/global-user-properties'; -import { isNotSpecialAmplitudeEvent } from 'src/helpers'; - +import { isAmplitudeIdentifyEvent, isNotSpecialAmplitudeEvent } from './helpers'; export const globalUserPropertiesPlugin: GlobalUserPropertiesPlugin = function (options: Options = {}) { const plugin: EnrichmentPlugin = { name: '@amplitude/plugin-global-user-properties', type: 'enrichment', - setup: async () => {}, - /* Note: The promise is because of the interface, not because this has any asynchronous behavior */ execute: async (event: Event): Promise => { - // Skip amplitude special events - if (isNotSpecialAmplitudeEvent(event)) { + if (isNotSpecialAmplitudeEvent(event) || isAmplitudeIdentifyEvent(event)) { event.global_user_properties = event.user_properties; if (!options.shouldKeepOriginalUserProperties) { - delete event.global_user_properties; - } - }; + delete event.user_properties; + } + } return event; }, diff --git a/packages/plugin-global-user-properties/src/helpers.ts b/packages/plugin-global-user-properties/src/helpers.ts new file mode 100644 index 000000000..8a59b16b0 --- /dev/null +++ b/packages/plugin-global-user-properties/src/helpers.ts @@ -0,0 +1,11 @@ +import { Event, BaseEvent, SpecialEventType, IdentifyEvent } from '@amplitude/analytics-types'; + +const specialAmplitudeEvents = new Set(Object.values(SpecialEventType)); + +export const isNotSpecialAmplitudeEvent = (event: Event): event is BaseEvent => { + return !specialAmplitudeEvents.has(event.event_type as SpecialEventType); +}; + +export const isAmplitudeIdentifyEvent = (event: Event): event is IdentifyEvent => { + return event.event_type === SpecialEventType.IDENTIFY; +}; diff --git a/packages/plugin-global-user-properties.ts/src/index.ts b/packages/plugin-global-user-properties/src/index.ts similarity index 90% rename from packages/plugin-global-user-properties.ts/src/index.ts rename to packages/plugin-global-user-properties/src/index.ts index 5f28586cd..6600552d2 100644 --- a/packages/plugin-global-user-properties.ts/src/index.ts +++ b/packages/plugin-global-user-properties/src/index.ts @@ -1,3 +1,3 @@ export { globalUserPropertiesPlugin } from './global-user-properties'; export { globalUserPropertiesPlugin as plugin } from './global-user-properties'; -export { GlobalUserPropertiesPlugin, Options } from './typings/global-user-properties' +export { GlobalUserPropertiesPlugin, Options } from './typings/global-user-properties'; diff --git a/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts b/packages/plugin-global-user-properties/src/typings/global-user-properties.ts similarity index 90% rename from packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts rename to packages/plugin-global-user-properties/src/typings/global-user-properties.ts index 86cab15aa..54b6905dd 100644 --- a/packages/plugin-global-user-properties.ts/src/typings/global-user-properties.ts +++ b/packages/plugin-global-user-properties/src/typings/global-user-properties.ts @@ -1,9 +1,9 @@ import { EnrichmentPlugin } from '@amplitude/analytics-types'; export interface Options { - /** - * Whether or not the orignal user_properties field should be kept on the event - */ + /** + * Whether or not the orignal user_properties field should be kept on the event + */ shouldKeepOriginalUserProperties?: boolean; } diff --git a/packages/plugin-global-user-properties/test/global-user-properties.test.ts b/packages/plugin-global-user-properties/test/global-user-properties.test.ts new file mode 100644 index 000000000..c5f8dc7fd --- /dev/null +++ b/packages/plugin-global-user-properties/test/global-user-properties.test.ts @@ -0,0 +1,72 @@ +import { globalUserPropertiesPlugin } from '../src/global-user-properties'; +import { BaseEvent, IdentifyEvent, RevenueEvent, SpecialEventType } from '@amplitude/analytics-types'; + +describe('globalUserPropertiesPlugin', () => { + const TEST_USER_PROPERTIES = { + USER_PROPERTY_ONE: 'TEST_VALUE_ONE', + }; + + const TEST_USER_IDENTIFY_PROPERTIES = { + $set: { + USER_PROPERTY_ONE: 'TEST_VALUE_ONE', + }, + }; + + test('adds global properties on regular events', async () => { + const plugin = globalUserPropertiesPlugin(); + + const event: BaseEvent = { + event_type: 'NOT A REAL EVENT TYPE', + user_properties: TEST_USER_PROPERTIES, + }; + + const newEvent = await plugin.execute?.({ ...event }); + + expect(newEvent?.event_type).toEqual(event.event_type); + expect(newEvent?.global_user_properties).toStrictEqual(TEST_USER_PROPERTIES); + expect(newEvent?.user_properties).toStrictEqual(undefined); + }); + + test('adds global properties on identify events', async () => { + const plugin = globalUserPropertiesPlugin(); + + const event: IdentifyEvent = { + event_type: SpecialEventType.IDENTIFY, + user_properties: TEST_USER_IDENTIFY_PROPERTIES, + }; + + const newEvent = await plugin.execute?.({ ...event }); + + expect(newEvent?.global_user_properties).toStrictEqual(TEST_USER_IDENTIFY_PROPERTIES); + expect(newEvent?.user_properties).toStrictEqual(undefined); + }); + + test('does not add global properties on revenue events', async () => { + const plugin = globalUserPropertiesPlugin(); + + const event: RevenueEvent = { + event_type: SpecialEventType.REVENUE, + revenue: 3, + event_properties: {}, + }; + + const newEvent = await plugin.execute?.({ ...event }); + + expect(newEvent?.global_user_properties).toStrictEqual(undefined); + expect(newEvent?.user_properties).toStrictEqual(event.user_properties); + }); + + test('adds global properties and user properties on identify events with shouldKeepOriginalUserProperties option', async () => { + const plugin = globalUserPropertiesPlugin({ shouldKeepOriginalUserProperties: true }); + + const event: IdentifyEvent = { + event_type: SpecialEventType.IDENTIFY, + user_properties: TEST_USER_IDENTIFY_PROPERTIES, + }; + + const newEvent = await plugin.execute?.({ ...event }); + + expect(newEvent?.global_user_properties).toStrictEqual(TEST_USER_IDENTIFY_PROPERTIES); + expect(newEvent?.user_properties).toStrictEqual(TEST_USER_IDENTIFY_PROPERTIES); + }); +}); diff --git a/packages/plugin-global-user-properties.ts/tsconfig.es5.json b/packages/plugin-global-user-properties/tsconfig.es5.json similarity index 100% rename from packages/plugin-global-user-properties.ts/tsconfig.es5.json rename to packages/plugin-global-user-properties/tsconfig.es5.json diff --git a/packages/plugin-global-user-properties.ts/tsconfig.esm.json b/packages/plugin-global-user-properties/tsconfig.esm.json similarity index 100% rename from packages/plugin-global-user-properties.ts/tsconfig.esm.json rename to packages/plugin-global-user-properties/tsconfig.esm.json diff --git a/packages/plugin-global-user-properties.ts/tsconfig.json b/packages/plugin-global-user-properties/tsconfig.json similarity index 100% rename from packages/plugin-global-user-properties.ts/tsconfig.json rename to packages/plugin-global-user-properties/tsconfig.json From 91e741fb72a76af8c3305023e6312456decade50 Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Mon, 11 Sep 2023 09:54:30 -0700 Subject: [PATCH 04/14] feat: add readme docs --- .../plugin-global-user-properties/README.md | 51 +++++-------------- 1 file changed, 12 insertions(+), 39 deletions(-) diff --git a/packages/plugin-global-user-properties/README.md b/packages/plugin-global-user-properties/README.md index 3dd4f9d37..44ed93920 100644 --- a/packages/plugin-global-user-properties/README.md +++ b/packages/plugin-global-user-properties/README.md @@ -5,9 +5,9 @@

-# @amplitude/plugin-web-attribution-browser +# @amplitude/plugin-global-user-properties -Official Browser SDK plugin for web attribution tracking +Official SDK plugin for adding global user properties to events ## Installation @@ -15,22 +15,26 @@ This package is published on NPM registry and is available to be installed using ```sh # npm -npm install @amplitude/plugin-web-attribution-browser +npm install @amplitude/plugin-global-user-properties # yarn -yarn add @amplitude/plugin-web-attribution-browser +yarn add @amplitude/plugin-global-user-properties ``` ## Usage -This plugin works on top of Amplitude Browser SDK and adds web attribution tracking features to built-in features. To use this plugin, you need to install `@amplitude/analytics-browser` version `v2.0.0` or later. +This plugin works on top of Amplitude Browser SDK and adds web attribution tracking features to built-in features. To use this plugin, you need to install `@amplitude/plugin-global-user-properties `v2.1.0` or later. ### 1. Import Amplitude packages -* `@amplitude/plugin-web-attribution-browser` +* `@amplitude/plugin-global-user-properties` ```typescript -import { webAttributionPlugin } from '@amplitude/plugin-web-attribution-browser'; +import * as Amplitude from '@amplitude/analytics-browser' +import { globalUserPropertiesPlugin } from '@amplitude/plugin-global-user-properties'; + +const amplitude = Amplitude.init(...); +await amplitude.add(globalUserPropertiesPlugin).promise ``` ### 2. Instantiate page view plugin @@ -49,9 +53,7 @@ const webAttributionTracking = webAttributionPlugin(amplitude, { |Name|Type|Default|Description| |-|-|-|-| -|`excludeReferrers`|`(string \| RegExp)[]`|`[]`|Use this option to prevent the plugin from tracking campaigns parameters from specific referrers. For example: `subdomain.domain.com`.| -|`initialEmptyValue`|`string`|`"EMPTY"`|Use this option to specify empty values for [first-touch attribution](https://www.docs.developers.amplitude.com/data/sdks/marketing-analytics-browser/#first-touch-attribution).| -|`resetSessionOnNewCampaign`|`boolean`|`false`|Use this option to control whether a new session should start on a new campaign.| +|`shouldKeepOriginalUserProperties`|`boolean`| `false` | Use this option if you want the user properties to be sent along with the global user properties. This would do nothing for analyses but as of the beta version, global user properties do not appear in Data Governance.| ### 3. Install plugin to Amplitude SDK @@ -65,32 +67,3 @@ amplitude.add(webAttributionTracking); amplitude.init('API_KEY'); ``` -## Resulting web attribution event - -This plugin tracks campaign parameters based on your configuration. A web attribution event is composed of the following values: - -#### Event type -* `"$idenfity"` - -#### User properties - -|Property|Description| -|-|-| -|`utm_source`|URL query parameter value for `utm_source`| -|`utm_medium`|URL query parameter value for `utm_medium`| -|`utm_campaign`|URL query parameter value for `utm_campaign`| -|`utm_term`|URL query parameter value for `utm_term`| -|`utm_content`|URL query parameter value for `utm_content`| -|`referrer`|Referring webstite or `document.referrer`| -|`referring_domain`|Referring website's domain, including subdomain| -|`dclid`|URL query parameter value for `dclid`| -|`gbraid`|URL query parameter value for `gbraid`| -|`gclid`|URL query parameter value for `gclid`| -|`fbclid`|URL query parameter value for `fbclid`| -|`ko_click_id`|URL query parameter value for `ko_click_id`| -|`li_fat_id`|URL query parameter value for `li_fat_id`| -|`msclkid`|URL query parameter value for `msclkid`| -|`rtd_cid`|URL query parameter value for `rtd_cid`| -|`ttclid`|URL query parameter value for `ttclid`| -|`twclid`|URL query parameter value for `twclid`| -|`wbraid`|URL query parameter value for `wbraid`| From cc06fa8f2127a809a0fa1d122afbfd8c6f9738f7 Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Mon, 11 Sep 2023 09:56:16 -0700 Subject: [PATCH 05/14] fix: correct flow of readme --- packages/plugin-global-user-properties/README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/packages/plugin-global-user-properties/README.md b/packages/plugin-global-user-properties/README.md index 44ed93920..67e048263 100644 --- a/packages/plugin-global-user-properties/README.md +++ b/packages/plugin-global-user-properties/README.md @@ -32,9 +32,6 @@ This plugin works on top of Amplitude Browser SDK and adds web attribution track ```typescript import * as Amplitude from '@amplitude/analytics-browser' import { globalUserPropertiesPlugin } from '@amplitude/plugin-global-user-properties'; - -const amplitude = Amplitude.init(...); -await amplitude.add(globalUserPropertiesPlugin).promise ``` ### 2. Instantiate page view plugin @@ -42,7 +39,7 @@ await amplitude.add(globalUserPropertiesPlugin).promise The plugin accepts an optional parameter of type `Object` to configure the plugin based on your use case. ```typescript -const webAttributionTracking = webAttributionPlugin(amplitude, { +const globalUserPropertiesPlugin = globalUserPropertiesPlugin({ excludeReferrers: undefined, initialEmptyValue: undefined, resetSessionOnNewCampaign: undefined, @@ -58,7 +55,7 @@ const webAttributionTracking = webAttributionPlugin(amplitude, { ### 3. Install plugin to Amplitude SDK ```typescript -amplitude.add(webAttributionTracking); +amplitude.add(globalUserPropertiesPlugin); ``` ### 4. Initialize Amplitude SDK From 488832f618c77b81f7ed318aa0af2a92caacae1a Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Wed, 13 Sep 2023 17:14:08 -0700 Subject: [PATCH 06/14] fix: dont modify types in analytics-types --- packages/analytics-types/src/base-event.ts | 1 - packages/analytics-types/src/event.ts | 1 - packages/plugin-global-user-properties/README.md | 8 +++----- packages/plugin-global-user-properties/src/index.d.ts | 11 +++++++++++ 4 files changed, 14 insertions(+), 7 deletions(-) create mode 100644 packages/plugin-global-user-properties/src/index.d.ts diff --git a/packages/analytics-types/src/base-event.ts b/packages/analytics-types/src/base-event.ts index 32cbd51ec..8585c3fb3 100644 --- a/packages/analytics-types/src/base-event.ts +++ b/packages/analytics-types/src/base-event.ts @@ -3,7 +3,6 @@ import { IngestionMetadataEventProperty } from './ingestion-metadata'; export interface BaseEvent extends EventOptions { event_type: string; - global_user_properties?: { [key: string]: any } | undefined; event_properties?: { [key: string]: any } | undefined; user_properties?: { [key: string]: any } | undefined; group_properties?: { [key: string]: any } | undefined; diff --git a/packages/analytics-types/src/event.ts b/packages/analytics-types/src/event.ts index 8866e3cf6..918fdbba5 100644 --- a/packages/analytics-types/src/event.ts +++ b/packages/analytics-types/src/event.ts @@ -113,7 +113,6 @@ export interface TrackEvent extends BaseEvent { export interface IdentifyEvent extends BaseEvent { event_type: SpecialEventType.IDENTIFY; - global_user_properties?: UserProperties; user_properties: UserProperties; } diff --git a/packages/plugin-global-user-properties/README.md b/packages/plugin-global-user-properties/README.md index 67e048263..7d7e8ccd8 100644 --- a/packages/plugin-global-user-properties/README.md +++ b/packages/plugin-global-user-properties/README.md @@ -23,7 +23,7 @@ yarn add @amplitude/plugin-global-user-properties ## Usage -This plugin works on top of Amplitude Browser SDK and adds web attribution tracking features to built-in features. To use this plugin, you need to install `@amplitude/plugin-global-user-properties `v2.1.0` or later. +This plugin works on top of Amplitude Browser SDK and adds web attribution tracking features to built-in features. To use this plugin, you need to install `@amplitude/plugin-global-user-properties `v0.1.0` or later. ### 1. Import Amplitude packages @@ -40,9 +40,7 @@ The plugin accepts an optional parameter of type `Object` to configure the plugi ```typescript const globalUserPropertiesPlugin = globalUserPropertiesPlugin({ - excludeReferrers: undefined, - initialEmptyValue: undefined, - resetSessionOnNewCampaign: undefined, + shouldKeepOriginalUserProperties: true, }); ``` @@ -50,7 +48,7 @@ const globalUserPropertiesPlugin = globalUserPropertiesPlugin({ |Name|Type|Default|Description| |-|-|-|-| -|`shouldKeepOriginalUserProperties`|`boolean`| `false` | Use this option if you want the user properties to be sent along with the global user properties. This would do nothing for analyses but as of the beta version, global user properties do not appear in Data Governance.| +|`shouldKeepOriginalUserProperties`|`boolean`| `false` | Use this option if you want the user properties to be sent along with the global user properties. Since global user properties do not appear in Governance yet, this would | ### 3. Install plugin to Amplitude SDK diff --git a/packages/plugin-global-user-properties/src/index.d.ts b/packages/plugin-global-user-properties/src/index.d.ts new file mode 100644 index 000000000..ebb1be906 --- /dev/null +++ b/packages/plugin-global-user-properties/src/index.d.ts @@ -0,0 +1,11 @@ +import { BaseEvent, IdentifyEvent } from "@amplitude/analytics-types"; + +declare module '@amplitude/analytics-types' { + export interface BaseEvent { + global_user_properties?: { [key: string]: any } | undefined; + } + + export interface IdentifyEvent { + global_user_properties?: { [key: string]: any } | undefined; + } +} \ No newline at end of file From 1a28e0b8a24dc5d2e214cb64d66ce5c2fd6358ba Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Wed, 13 Sep 2023 17:15:19 -0700 Subject: [PATCH 07/14] fix: refactor event.ts --- packages/analytics-types/src/event.ts | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/packages/analytics-types/src/event.ts b/packages/analytics-types/src/event.ts index 918fdbba5..83ee9bbf9 100644 --- a/packages/analytics-types/src/event.ts +++ b/packages/analytics-types/src/event.ts @@ -118,11 +118,7 @@ export interface IdentifyEvent extends BaseEvent { export interface GroupIdentifyEvent extends BaseEvent { event_type: SpecialEventType.GROUP_IDENTIFY; - group_properties: - | IdentifyUserProperties - | { - [key in Exclude]: any; - }; + group_properties: UserProperties; } export interface RevenueEvent extends BaseEvent { From 919947bcb62eed4144ac4d0d9f5cb3e9fb614286 Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Wed, 13 Sep 2023 17:18:13 -0700 Subject: [PATCH 08/14] fix: version --- packages/plugin-global-user-properties/README.md | 2 +- packages/plugin-global-user-properties/package.json | 2 +- packages/plugin-web-attribution-browser/package.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/plugin-global-user-properties/README.md b/packages/plugin-global-user-properties/README.md index 7d7e8ccd8..49f9e9101 100644 --- a/packages/plugin-global-user-properties/README.md +++ b/packages/plugin-global-user-properties/README.md @@ -23,7 +23,7 @@ yarn add @amplitude/plugin-global-user-properties ## Usage -This plugin works on top of Amplitude Browser SDK and adds web attribution tracking features to built-in features. To use this plugin, you need to install `@amplitude/plugin-global-user-properties `v0.1.0` or later. +This plugin works on top of Amplitude Browser SDK and adds web attribution tracking features to built-in features. To use this plugin, you need to install `@amplitude/plugin-global-user-properties `v0.0.0` or later. ### 1. Import Amplitude packages diff --git a/packages/plugin-global-user-properties/package.json b/packages/plugin-global-user-properties/package.json index fd15c99ac..68634c1a9 100644 --- a/packages/plugin-global-user-properties/package.json +++ b/packages/plugin-global-user-properties/package.json @@ -1,6 +1,6 @@ { "name": "@amplitude/plugin-global-user-properties", - "version": "2.1.0", + "version": "0.1.0", "description": "", "author": "Amplitude Inc", "homepage": "https://github.com/amplitude/Amplitude-TypeScript", diff --git a/packages/plugin-web-attribution-browser/package.json b/packages/plugin-web-attribution-browser/package.json index d57c8835e..9d6b3e2c3 100644 --- a/packages/plugin-web-attribution-browser/package.json +++ b/packages/plugin-web-attribution-browser/package.json @@ -1,6 +1,6 @@ { "name": "@amplitude/plugin-web-attribution-browser", - "version": "2.0.9", + "version": "0.0.0", "description": "", "author": "Amplitude Inc", "homepage": "https://github.com/amplitude/Amplitude-TypeScript", From 0f632d25329c9d04188c41350c03ded78ba57b93 Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Wed, 13 Sep 2023 17:32:09 -0700 Subject: [PATCH 09/14] fix: import statement preventing rollup --- packages/plugin-global-user-properties/src/index.d.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/plugin-global-user-properties/src/index.d.ts b/packages/plugin-global-user-properties/src/index.d.ts index ebb1be906..3bc6c39bd 100644 --- a/packages/plugin-global-user-properties/src/index.d.ts +++ b/packages/plugin-global-user-properties/src/index.d.ts @@ -1,6 +1,7 @@ -import { BaseEvent, IdentifyEvent } from "@amplitude/analytics-types"; declare module '@amplitude/analytics-types' { + import { BaseEvent, IdentifyEvent } from "@amplitude/analytics-types"; + export interface BaseEvent { global_user_properties?: { [key: string]: any } | undefined; } From c2d1e37865cdfbe9776457d849dbb4e2172be2cf Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Thu, 14 Sep 2023 02:41:49 -0700 Subject: [PATCH 10/14] fix(docs): fix broken language in docs, pr comments --- packages/plugin-global-user-properties/README.md | 6 ++++-- packages/plugin-global-user-properties/package.json | 2 +- yarn.lock | 10 ++++++++++ 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/packages/plugin-global-user-properties/README.md b/packages/plugin-global-user-properties/README.md index 49f9e9101..df59ff5a0 100644 --- a/packages/plugin-global-user-properties/README.md +++ b/packages/plugin-global-user-properties/README.md @@ -23,7 +23,9 @@ yarn add @amplitude/plugin-global-user-properties ## Usage -This plugin works on top of Amplitude Browser SDK and adds web attribution tracking features to built-in features. To use this plugin, you need to install `@amplitude/plugin-global-user-properties `v0.0.0` or later. +This plugin works on top of the Amplitude SDK and sends user properties as global user properties, a beta feature for that allows projects to share user properties (i.e. user properties can become "global" across multiple projects). + +To use this plugin, you need to install `@amplitude/plugin-global-user-properties `v1.0.0` or later. ### 1. Import Amplitude packages @@ -48,7 +50,7 @@ const globalUserPropertiesPlugin = globalUserPropertiesPlugin({ |Name|Type|Default|Description| |-|-|-|-| -|`shouldKeepOriginalUserProperties`|`boolean`| `false` | Use this option if you want the user properties to be sent along with the global user properties. Since global user properties do not appear in Governance yet, this would | +|`shouldKeepOriginalUserProperties`|`boolean`| `false` | Use this option if you want the user properties to be sent along with the global user properties. Since global user properties do not appear in Data yet, this would allow indirect governance (by observing the same properties as regular user properties). | ### 3. Install plugin to Amplitude SDK diff --git a/packages/plugin-global-user-properties/package.json b/packages/plugin-global-user-properties/package.json index 68634c1a9..9774a9e99 100644 --- a/packages/plugin-global-user-properties/package.json +++ b/packages/plugin-global-user-properties/package.json @@ -1,6 +1,6 @@ { "name": "@amplitude/plugin-global-user-properties", - "version": "0.1.0", + "version": "1.0.0", "description": "", "author": "Amplitude Inc", "homepage": "https://github.com/amplitude/Amplitude-TypeScript", diff --git a/yarn.lock b/yarn.lock index 33a296cca..2be390f76 100644 --- a/yarn.lock +++ b/yarn.lock @@ -7,6 +7,16 @@ resolved "https://registry.yarnpkg.com/@amplitude/analytics-connector/-/analytics-connector-1.4.8.tgz#dd801303db2662bc51be7e0194eeb8bd72267c42" integrity sha512-dFW7c7Wb6Ng7vbmzwbaXZSpqfBx37ukamJV9ErFYYS8vGZK/Hkbt3M7fZHBI4WFU6CCwakr2ZXPme11uGPYWkQ== +"@amplitude/plugin-web-attribution-browser@^2.0.9": + version "2.0.9" + resolved "https://registry.yarnpkg.com/@amplitude/plugin-web-attribution-browser/-/plugin-web-attribution-browser-2.0.9.tgz#0d24f2da764846601f59484a8651d58918ef89d7" + integrity sha512-QrNgieAEXEBbtnsxYzfeJl2U/5XwCCvO3Dg0hntAtnTdu1A3HlN5ItRtoHg0jGBbu4jpSbvag72UlkCotqJ+Yg== + dependencies: + "@amplitude/analytics-client-common" "^2.0.5" + "@amplitude/analytics-core" "^2.0.4" + "@amplitude/analytics-types" "^2.1.2" + tslib "^2.4.1" + "@amplitude/ua-parser-js@^0.7.31": version "0.7.31" resolved "https://registry.yarnpkg.com/@amplitude/ua-parser-js/-/ua-parser-js-0.7.31.tgz#749bf7cb633cfcc7ff3c10805bad7c5f6fbdbc61" From c1a5424d37fa98bb513fa66ea3142ebd9f91608c Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Thu, 14 Sep 2023 02:57:06 -0700 Subject: [PATCH 11/14] fix: rename modules, move import --- .../src/global-user-properties.ts | 4 ++-- .../plugin-global-user-properties/src/helpers.ts | 4 ++-- .../plugin-global-user-properties/src/index.d.ts | 12 ------------ .../plugin-global-user-properties/src/modules.d.ts | 12 ++++++++++++ 4 files changed, 16 insertions(+), 16 deletions(-) delete mode 100644 packages/plugin-global-user-properties/src/index.d.ts create mode 100644 packages/plugin-global-user-properties/src/modules.d.ts diff --git a/packages/plugin-global-user-properties/src/global-user-properties.ts b/packages/plugin-global-user-properties/src/global-user-properties.ts index 42efdeb79..35303ec24 100644 --- a/packages/plugin-global-user-properties/src/global-user-properties.ts +++ b/packages/plugin-global-user-properties/src/global-user-properties.ts @@ -1,6 +1,6 @@ import { EnrichmentPlugin, Event } from '@amplitude/analytics-types'; import { GlobalUserPropertiesPlugin, Options } from './typings/global-user-properties'; -import { isAmplitudeIdentifyEvent, isNotSpecialAmplitudeEvent } from './helpers'; +import { isAmplitudeIdentifyEvent, isTrackEvent } from './helpers'; export const globalUserPropertiesPlugin: GlobalUserPropertiesPlugin = function (options: Options = {}) { const plugin: EnrichmentPlugin = { @@ -9,7 +9,7 @@ export const globalUserPropertiesPlugin: GlobalUserPropertiesPlugin = function ( /* Note: The promise is because of the interface, not because this has any asynchronous behavior */ execute: async (event: Event): Promise => { - if (isNotSpecialAmplitudeEvent(event) || isAmplitudeIdentifyEvent(event)) { + if (isTrackEvent(event) || isAmplitudeIdentifyEvent(event)) { event.global_user_properties = event.user_properties; if (!options.shouldKeepOriginalUserProperties) { diff --git a/packages/plugin-global-user-properties/src/helpers.ts b/packages/plugin-global-user-properties/src/helpers.ts index 8a59b16b0..5bc3ff026 100644 --- a/packages/plugin-global-user-properties/src/helpers.ts +++ b/packages/plugin-global-user-properties/src/helpers.ts @@ -1,8 +1,8 @@ -import { Event, BaseEvent, SpecialEventType, IdentifyEvent } from '@amplitude/analytics-types'; +import { Event, TrackEvent, SpecialEventType, IdentifyEvent } from '@amplitude/analytics-types'; const specialAmplitudeEvents = new Set(Object.values(SpecialEventType)); -export const isNotSpecialAmplitudeEvent = (event: Event): event is BaseEvent => { +export const isTrackEvent = (event: Event): event is TrackEvent => { return !specialAmplitudeEvents.has(event.event_type as SpecialEventType); }; diff --git a/packages/plugin-global-user-properties/src/index.d.ts b/packages/plugin-global-user-properties/src/index.d.ts deleted file mode 100644 index 3bc6c39bd..000000000 --- a/packages/plugin-global-user-properties/src/index.d.ts +++ /dev/null @@ -1,12 +0,0 @@ - -declare module '@amplitude/analytics-types' { - import { BaseEvent, IdentifyEvent } from "@amplitude/analytics-types"; - - export interface BaseEvent { - global_user_properties?: { [key: string]: any } | undefined; - } - - export interface IdentifyEvent { - global_user_properties?: { [key: string]: any } | undefined; - } -} \ No newline at end of file diff --git a/packages/plugin-global-user-properties/src/modules.d.ts b/packages/plugin-global-user-properties/src/modules.d.ts new file mode 100644 index 000000000..23b1251a3 --- /dev/null +++ b/packages/plugin-global-user-properties/src/modules.d.ts @@ -0,0 +1,12 @@ +// eslint-disable-next-line @typescript-eslint/no-unused-vars +import { TrackEvent, IdentifyEvent } from '@amplitude/analytics-types'; + +declare module '@amplitude/analytics-types' { + export interface TrackEvent { + global_user_properties?: { [key: string]: any } | undefined; + } + + export interface IdentifyEvent { + global_user_properties?: { [key: string]: any } | undefined; + } +} From ed195715b53b505f39c2a4dc91bcf6f816675d47 Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Thu, 14 Sep 2023 12:42:10 -0700 Subject: [PATCH 12/14] fix: type hacks for tests --- .../test/global-user-properties.test.ts | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/packages/plugin-global-user-properties/test/global-user-properties.test.ts b/packages/plugin-global-user-properties/test/global-user-properties.test.ts index c5f8dc7fd..74e31f952 100644 --- a/packages/plugin-global-user-properties/test/global-user-properties.test.ts +++ b/packages/plugin-global-user-properties/test/global-user-properties.test.ts @@ -1,6 +1,7 @@ import { globalUserPropertiesPlugin } from '../src/global-user-properties'; -import { BaseEvent, IdentifyEvent, RevenueEvent, SpecialEventType } from '@amplitude/analytics-types'; +import { TrackEvent, IdentifyEvent, RevenueEvent, SpecialEventType } from '@amplitude/analytics-types'; +// ts-jest is having difficulty finding the module declaration types, so there are some any's describe('globalUserPropertiesPlugin', () => { const TEST_USER_PROPERTIES = { USER_PROPERTY_ONE: 'TEST_VALUE_ONE', @@ -15,12 +16,12 @@ describe('globalUserPropertiesPlugin', () => { test('adds global properties on regular events', async () => { const plugin = globalUserPropertiesPlugin(); - const event: BaseEvent = { + const event: TrackEvent = { event_type: 'NOT A REAL EVENT TYPE', user_properties: TEST_USER_PROPERTIES, }; - const newEvent = await plugin.execute?.({ ...event }); + const newEvent: any = await plugin.execute?.({ ...event }); expect(newEvent?.event_type).toEqual(event.event_type); expect(newEvent?.global_user_properties).toStrictEqual(TEST_USER_PROPERTIES); @@ -34,8 +35,8 @@ describe('globalUserPropertiesPlugin', () => { event_type: SpecialEventType.IDENTIFY, user_properties: TEST_USER_IDENTIFY_PROPERTIES, }; - - const newEvent = await plugin.execute?.({ ...event }); + + const newEvent: any = await plugin.execute?.({ ...event }); expect(newEvent?.global_user_properties).toStrictEqual(TEST_USER_IDENTIFY_PROPERTIES); expect(newEvent?.user_properties).toStrictEqual(undefined); @@ -50,7 +51,7 @@ describe('globalUserPropertiesPlugin', () => { event_properties: {}, }; - const newEvent = await plugin.execute?.({ ...event }); + const newEvent: any = await plugin.execute?.({ ...event }); expect(newEvent?.global_user_properties).toStrictEqual(undefined); expect(newEvent?.user_properties).toStrictEqual(event.user_properties); @@ -64,7 +65,7 @@ describe('globalUserPropertiesPlugin', () => { user_properties: TEST_USER_IDENTIFY_PROPERTIES, }; - const newEvent = await plugin.execute?.({ ...event }); + const newEvent: any = await plugin.execute?.({ ...event }); expect(newEvent?.global_user_properties).toStrictEqual(TEST_USER_IDENTIFY_PROPERTIES); expect(newEvent?.user_properties).toStrictEqual(TEST_USER_IDENTIFY_PROPERTIES); From 42103902e0a457be373aa4714a1341ce26326406 Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Thu, 14 Sep 2023 12:44:42 -0700 Subject: [PATCH 13/14] docs: add description --- packages/plugin-global-user-properties/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/plugin-global-user-properties/package.json b/packages/plugin-global-user-properties/package.json index 9774a9e99..5175fa6e7 100644 --- a/packages/plugin-global-user-properties/package.json +++ b/packages/plugin-global-user-properties/package.json @@ -1,7 +1,7 @@ { "name": "@amplitude/plugin-global-user-properties", "version": "1.0.0", - "description": "", + "description": "An event enrichment plugin that adds the experimental global user properties field to events", "author": "Amplitude Inc", "homepage": "https://github.com/amplitude/Amplitude-TypeScript", "license": "MIT", From 5d33946752521c9b51e4653dbcaf51adb0f3b30b Mon Sep 17 00:00:00 2001 From: Kelvin Lu Date: Fri, 15 Sep 2023 12:46:23 -0700 Subject: [PATCH 14/14] lint: prettier --- .../test/global-user-properties.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/plugin-global-user-properties/test/global-user-properties.test.ts b/packages/plugin-global-user-properties/test/global-user-properties.test.ts index 74e31f952..8485516cc 100644 --- a/packages/plugin-global-user-properties/test/global-user-properties.test.ts +++ b/packages/plugin-global-user-properties/test/global-user-properties.test.ts @@ -35,7 +35,7 @@ describe('globalUserPropertiesPlugin', () => { event_type: SpecialEventType.IDENTIFY, user_properties: TEST_USER_IDENTIFY_PROPERTIES, }; - + const newEvent: any = await plugin.execute?.({ ...event }); expect(newEvent?.global_user_properties).toStrictEqual(TEST_USER_IDENTIFY_PROPERTIES);