diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000..b17149b3 --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +*.mdx \ No newline at end of file diff --git a/apps/dashboard/src/modals/Instructions.tsx b/apps/dashboard/src/modals/Instructions.tsx index 5c8d3880..7958923b 100644 --- a/apps/dashboard/src/modals/Instructions.tsx +++ b/apps/dashboard/src/modals/Instructions.tsx @@ -64,7 +64,7 @@ const Instructions = ({ framework, client }: Props) => {

Copy the code below and insert it to you website

+ code={` +```html filename="index.html" /clientId: 'YOUR_CLIENT_ID'/ + ``` -### Config +#### Options - + + ## Usage -You can let the library track screen views, outgoing links and attributes tracking by setting the `trackScreenViews`, `trackOutgoingLinks` and `trackAttributes` options to `true`. +### Tracking Events -### Track event +You can track events with two different methods: by calling the `window.op('track')` directly or by adding `data-track` attributes to your HTML elements. - - - ```javascript - window.op('event', 'my_event', { foo: 'bar' }); - ``` - - - For this to work you need to enable `trackAttributes` in the config. - ```html - - ``` - - - -### Identify - -#### Set Profile Id - -Keep track of your users by identifying them with a unique id. This is a good features if you have things behind a login and want to track user behavior. - - - -```javascript -const profileId = '123'; -window.op('setProfileId', profileId); +```html filename="index.html" + ``` -#### Additional data +```html filename="index.html" + +``` -This method does the same as `setProfileId` but also allows you to update the profile with additional data. +### Identifying Users - +To identify a user, call the `window.op('identify')` method with a unique identifier. -```javascript -const profileId = '123'; -window.op('setProfile', { - profileId, - // firstName?: string; - // lastName?: string; - // email?: string; - // avatar?: string; - // properties?: Record; +```js filename="main.js" +window.op('identify', { + profileId: '123', // Required + firstName: 'Joe', + lastName: 'Doe', + email: 'joe@doe.com', + properties: { + tier: 'premium', + }, }); ``` -#### Increment property +### Setting Global Properties -Increment a property on the profile. +To set properties that will be sent with every event: -```javascript -// Increment by 1 -window.op('increment', 'app_opened'); - -// Increment by 5 -window.op('increment', 'app_opened', 5); +```js filename="main.js" +window.op('setGlobalProperties', { + app_version: '1.0.2', + environment: 'production', +}); ``` -#### Decrement property +### Creating Aliases -Decrement a property on the profile. +To create an alias for a user: -```javascript -// Increment by 1 -window.op('decrement', 'app_opened'); - -// Increment by 5 -window.op('decrement', 'app_opened', 5); +```js filename="main.js" +window.op('alias', { + alias: 'a1', + profileId: '1' +}); ``` -#### Clear / Logout +### Incrementing Properties -Clear the profile id and all the data. +To increment a numeric property on a user profile. -```typescript +- `value` is the amount to increment the property by. If not provided, the property will be incremented by 1. + +```js filename="main.js" +window.op('increment', { + profileId: '1', + property: 'visits', + value: 1 // optional +}); +``` + +### Decrementing Properties + +To decrement a numeric property on a user profile. + +- `value` is the amount to decrement the property by. If not provided, the property will be decremented by 1. + +```js filename="main.js" +window.op('decrement', { + profileId: '1', + property: 'visits', + value: 1 // optional +}); +``` + +### Clearing User Data + +To clear the current user's data: + +```js filename="main.js" window.op('clear'); ``` +## Advanced Usage + +### Using the Web SDK with NPM + + +#### Step 1: Install the SDK + +```bash +npm install @openpanel/web +``` + +#### Step 2: Initialize the SDK + +```js filename="op.js" +import { OpenPanel } from '@openpanel/web'; + +const op = new OpenPanel({ + clientId: 'YOUR_CLIENT_ID', + trackScreenViews: true, + trackOutgoingLinks: true, + trackAttributes: true, +}); +``` + +#### Step 3: Use the SDK + +```js filename="main.js" +import { op } from './op.js'; + +op.track('my_event', { foo: 'bar' }); +``` + + ### Typescript -Is your IDE mad at you for not using typescript? We got you covered. +Getting ts errors when using the SDK? You can add a custom type definition file to your project. -Add this and it will stop complain about `window.op` not being defined. +#### Simple -```typescript +Just paste this code in any of your `.d.ts` files. + +```ts filename="op.d.ts" declare global { interface Window { op: { - q?: [string, ...any[]]; - (method: string, ...args: any[]): void; + q?: string[][]; + (...args: [ + 'init' | 'track' | 'identify' | 'setGlobalProperties' | 'alias' | 'increment' | 'decrement' | 'clear', + ...any[] + ]): void; }; } } ``` + +#### Strict typing (from sdk) + +Create a `op.d.ts`file and paste the following code: + +```ts filename="op.d.ts" +/// +``` \ No newline at end of file diff --git a/apps/docs/src/pages/docs/web.mdx b/apps/docs/src/pages/docs/web.mdx index 40d2caf3..385b3162 100644 --- a/apps/docs/src/pages/docs/web.mdx +++ b/apps/docs/src/pages/docs/web.mdx @@ -1,137 +1,48 @@ -import Link from 'next/link'; -import { Callout, Steps, Tabs } from 'nextra/components'; -import { DeviceIdWarning } from 'src/components/device-id-warning'; +import { Callout, Tabs, Steps } from 'nextra/components'; import { PersonalDataWarning } from 'src/components/personal-data-warning'; - -import SdkConfig from 'src/components/sdk-config.mdx'; +import CommonSdkConfig from 'src/components/common-sdk-config.mdx'; +import WebSdkConfig from 'src/components/web-sdk-config.mdx'; # Web SDK -This is a wrapper of Javascript SDK. It's a simple way to use the Openpanel SDK in your web application. +The OpenPanel Web SDK allows you to track user behavior on your website using a simple script tag. This guide provides instructions for installing and using the Web SDK in your project. ## Installation -### Install dependencies +### Step 1: Install ```bash -pnpm install @openpanel/web +npm install @openpanel/web ``` -### Initialize +### Step 2: Initialize -```tsx -import { Openpanel } from '@openpanel/web'; +```js filename="op.ts" +import { OpenPanel } from '@openpanel/web'; -const op = new Openpanel({ - clientId: '{YOUR_CLIENT_ID}', +const op = new OpenPanel({ + clientId: 'YOUR_CLIENT_ID', trackScreenViews: true, - // trackAttributes: true, - // trackOutgoingLinks: true, + trackOutgoingLinks: true, + trackAttributes: true, }); ``` -#### Config +#### Options - + + -### Ready! +### Step 3: Usage -You're now ready to use the library. +```js filename="main.ts" +import { op } from './op.js'; -```typescript -// Sends an event with payload foo: bar -op.event('my_event', { foo: 'bar' }); - -// Identify with profile id -op.setProfileId('123'); - -// or with additional data -op.setProfile({ - profileId: '123', - firstName: 'John', - lastName: 'Doe', - email: 'john.doe@openpanel.dev', -}); - -// Increment a property -op.increment('app_opened'); // increment by 1 -op.increment('app_opened', 5); // increment by 5 - -// Decrement a property -op.decrement('app_opened'); // decrement by 1 -op.decrement('app_opened', 5); // decrement by 5 +op.track('my_event', { foo: 'bar' }); ``` - ## Usage -### Track event - -```typescript -op.event('my_event', { foo: 'bar' }); -``` - -### Identify - -#### Set Profile Id - -Keep track of your users by identifying them with a unique id. This is a good features if you have things behind a login and want to track user behavior. - - - -```typescript -const profileId = '123'; -op.setProfileId(profileId); -``` - -#### Additional data - -This method does the same as `setProfileId` but also allows you to update the profile with additional data. - - - -```typescript -const profileId = '123'; -op.setProfile({ - profileId, - // firstName?: string; - // lastName?: string; - // email?: string; - // avatar?: string; - // properties?: Record; -}); -``` - -#### Increment property - -Increment a property on the profile. - -```typescript -// Increment by 1 -op.increment('app_opened'); - -// Increment by 5 -op.increment('app_opened', 5); -``` - -#### Decrement property - -Decrement a property on the profile. - -```typescript -// Increment by 1 -op.decrement('app_opened'); - -// Increment by 5 -op.decrement('app_opened', 5); -``` - -#### Clear / Logout - -Clear the profile id and all the data. - -```typescript -op.clear(); -``` +Refer to the [Javascript SDK](/docs/javascript#usage) for usage instructions. \ No newline at end of file diff --git a/apps/docs/theme.config.jsx b/apps/docs/theme.config.jsx index ce08d2a2..4eaa4b15 100644 --- a/apps/docs/theme.config.jsx +++ b/apps/docs/theme.config.jsx @@ -3,6 +3,14 @@ import { useRouter } from 'next/router'; import { useConfig } from 'nextra-theme-docs'; export default { + banner: { + key: '1.0-release', + text: ( + + 🎉 We have released v1. Read migration guide if needed! + + ), + }, logo: ( <> & { profileId?: string; diff --git a/packages/sdks/sdk/src/index.ts b/packages/sdks/sdk/src/index.ts index 4aa07eb8..66df67e0 100644 --- a/packages/sdks/sdk/src/index.ts +++ b/packages/sdks/sdk/src/index.ts @@ -67,12 +67,13 @@ export type OpenPanelOptions = { sdkVersion?: string; waitForProfile?: boolean; filter?: (payload: TrackHandlerPayload) => boolean; + disable?: boolean; }; export class OpenPanel { api: Api; profileId?: string; - global?: Record; + global?: Record; queue: TrackHandlerPayload[] = []; constructor(public options: OpenPanelOptions) { @@ -94,6 +95,7 @@ export class OpenPanel { }); } + // placeholder for future use init() { // empty } @@ -104,6 +106,10 @@ export class OpenPanel { } async send(payload: TrackHandlerPayload) { + if (this.options.disable) { + return Promise.resolve(); + } + if (this.options.filter && !this.options.filter(payload)) { return Promise.resolve(); } @@ -115,7 +121,7 @@ export class OpenPanel { return this.api.fetch('/track', payload); } - setGlobalProperties(properties: Record) { + setGlobalProperties(properties: Record) { this.global = { ...this.global, ...properties, @@ -179,18 +185,18 @@ export class OpenPanel { clear() { this.profileId = undefined; - // session end? + // should we force a session end here? } flush() { this.queue.forEach((item) => { this.send({ ...item, - // Not user why ts-expect-error is needed here + // Not sure why ts-expect-error is needed here // @ts-expect-error payload: { ...item.payload, - profileId: this.profileId, + profileId: item.payload.profileId ?? this.profileId, }, }); }); diff --git a/packages/sdks/web/src/index.ts b/packages/sdks/web/src/index.ts index 7bec688d..764797d2 100644 --- a/packages/sdks/web/src/index.ts +++ b/packages/sdks/web/src/index.ts @@ -6,7 +6,8 @@ import type { } from '@openpanel/sdk'; import { OpenPanel as OpenPanelBase } from '@openpanel/sdk'; -export * from '@openpanel/sdk'; +export type * from '@openpanel/sdk'; +export { OpenPanel as OpenPanelBase } from '@openpanel/sdk'; export type OpenPanelOptions = OpenPanelBaseOptions & { trackOutgoingLinks?: boolean; @@ -129,20 +130,20 @@ export class OpenPanel extends OpenPanelBase { const target = event.target as HTMLElement; const btn = target.closest('button'); const anchor = target.closest('a'); - const element = btn?.getAttribute('data-event') + const element = btn?.getAttribute('data-track') ? btn - : anchor?.getAttribute('data-event') + : anchor?.getAttribute('data-track') ? anchor : null; if (element) { const properties: Record = {}; for (const attr of element.attributes) { - if (attr.name.startsWith('data-') && attr.name !== 'data-event') { + if (attr.name.startsWith('data-') && attr.name !== 'data-track') { properties[toCamelCase(attr.name.replace(/^data-/, ''))] = attr.value; } } - const name = element.getAttribute('data-event'); + const name = element.getAttribute('data-track'); if (name) { super.track(name, properties); } diff --git a/packages/sdks/web/src/tracker.ts b/packages/sdks/web/src/tracker.ts index 27d7df0a..1b19e31c 100644 --- a/packages/sdks/web/src/tracker.ts +++ b/packages/sdks/web/src/tracker.ts @@ -18,7 +18,7 @@ import { OpenPanel } from './index'; // @ts-expect-error fn(...args); } else { - console.warn(`op.js: ${t} is not a function`); + console.warn(`OpenPanel: ${t} is not a function`); } }; diff --git a/tooling/publish/publish.ts b/tooling/publish/publish.ts index 307e3009..e6a25992 100644 --- a/tooling/publish/publish.ts +++ b/tooling/publish/publish.ts @@ -228,7 +228,7 @@ function main() { if (dependent === '@openpanel/web') { execSync( - `cp ${workspacePath('packages/sdks/web/dist/src/tracker.global.js')} ${workspacePath('./apps/public/public/tracker.js')}` + `cp ${workspacePath('packages/sdks/web/dist/src/tracker.global.js')} ${workspacePath('./apps/public/public/op1.js')}` ); } });