diff --git a/apps/docs/src/components/brand-logo.tsx b/apps/docs/src/components/brand-logo.tsx new file mode 100644 index 00000000..5c7d1057 --- /dev/null +++ b/apps/docs/src/components/brand-logo.tsx @@ -0,0 +1,15 @@ +interface Props { + src: string; + isDark?: boolean; +} +export function BrandLogo({ src, isDark }: Props) { + if (isDark) { + return ( +
+ +
+ ); + } + + return ; +} diff --git a/apps/docs/src/pages/docs/_meta.json b/apps/docs/src/pages/docs/_meta.json index 75350419..1f71ac39 100644 --- a/apps/docs/src/pages/docs/_meta.json +++ b/apps/docs/src/pages/docs/_meta.json @@ -1,14 +1,21 @@ { "index": "Get Started", - "-- Implementation": { + "-- Frameworks": { "type": "separator", - "title": "Implementation" + "title": "Frameworks" }, "script": "Script", - "javascript": "Javascript SDK", "nextjs": "Next.js", "react": "React", "react-native": "React-Native", "remix": "Remix", - "vue": "Vue" + "vue": "Vue", + "astro": "Astro", + "node": "Node (backend)", + "-- Others": { + "type": "separator", + "title": "Others" + }, + "javascript": "Javascript SDK", + "web": "Web SDK" } diff --git a/apps/docs/src/pages/docs/astro.mdx b/apps/docs/src/pages/docs/astro.mdx new file mode 100644 index 00000000..3c22b8d3 --- /dev/null +++ b/apps/docs/src/pages/docs/astro.mdx @@ -0,0 +1,5 @@ +import Link from 'next/link'; + +# Astro + +You can use script tag or Web SDK to track events in Astro. diff --git a/apps/docs/src/pages/docs/index.mdx b/apps/docs/src/pages/docs/index.mdx index 464c5565..56e001a2 100644 --- a/apps/docs/src/pages/docs/index.mdx +++ b/apps/docs/src/pages/docs/index.mdx @@ -1,4 +1,5 @@ import { Card, Cards } from 'nextra/components'; +import { BrandLogo } from 'src/components/brand-logo'; # Get started @@ -7,22 +8,16 @@ Create an account on [Openpanel](https://openpanel.dev) and setup your first pro + } - title="General / Script" - href="/docs/general" + title="HTML / Script" + href="/docs/script" > {' '} + } title="React" href="/docs/react" @@ -31,10 +26,7 @@ Create an account on [Openpanel](https://openpanel.dev) and setup your first pro + } title="React-Native" href="/docs/react-native" @@ -43,8 +35,8 @@ Create an account on [Openpanel](https://openpanel.dev) and setup your first pro } @@ -55,8 +47,8 @@ Create an account on [Openpanel](https://openpanel.dev) and setup your first pro } @@ -67,14 +59,23 @@ Create an account on [Openpanel](https://openpanel.dev) and setup your first pro + } title="Vue" href="/docs/vue" > {' '} + + } + title="Astro" + href="/docs/vue" + > + {' '} + diff --git a/apps/docs/src/pages/docs/javascript.mdx b/apps/docs/src/pages/docs/javascript.mdx index 3069d40b..e7f85066 100644 --- a/apps/docs/src/pages/docs/javascript.mdx +++ b/apps/docs/src/pages/docs/javascript.mdx @@ -7,7 +7,7 @@ import SdkConfig from 'src/components/sdk-config.mdx'; # Javascript SDK -This is the base SDK for Openpanel. All other SDKs are built on top of this one. +This is the base SDK for Openpanel. All other SDKs/frameworks are built on top of this one. ## Installation @@ -21,9 +21,9 @@ pnpm install @openpanel/sdk ### Initialize ```tsx -import { Openpanel } from '@openpanel/sdk'; +import { OpenpanelSdk } from '@openpanel/sdk'; -const op = new Openpanel({ +const op = new OpenpanelSdk({ url: 'https://api.openpanel.dev', clientId: '{YOUR_CLIENT_ID}', // mostly for backend and apps that can't rely on CORS @@ -84,10 +84,8 @@ Keep track of your users by identifying them with a unique id. This is a good fe ```typescript -import { setProfileId } from '@openpanel/nextjs'; - const profileId = '123'; -setProfileId(profileId); +op.setProfileId(profileId); ``` #### Additional data @@ -97,10 +95,8 @@ This method does the same as `setProfileId` but also allows you to update the pr ```typescript -import { setProfile } from '@openpanel/nextjs'; - const profileId = '123'; -setProfile({ +op.setProfile({ profileId, // firstName?: string; // lastName?: string; @@ -115,13 +111,11 @@ setProfile({ Increment a property on the profile. ```typescript -import { increment } from '@openpanel/nextjs'; - // Increment by 1 -increment('app_opened'); +op.increment('app_opened'); // Increment by 5 -increment('app_opened', 5); +op.increment('app_opened', 5); ``` #### Decrement property @@ -129,11 +123,17 @@ increment('app_opened', 5); Decrement a property on the profile. ```typescript -import { decrement } from '@openpanel/nextjs'; - // Increment by 1 -decrement('app_opened'); +op.decrement('app_opened'); // Increment by 5 -decrement('app_opened', 5); +op.decrement('app_opened', 5); +``` + +#### Clear / Logout + +Clear the profile id and all the data. + +```typescript +op.clear(); ``` diff --git a/apps/docs/src/pages/docs/nextjs.mdx b/apps/docs/src/pages/docs/nextjs.mdx index 10e82fe3..494a3453 100644 --- a/apps/docs/src/pages/docs/nextjs.mdx +++ b/apps/docs/src/pages/docs/nextjs.mdx @@ -7,7 +7,9 @@ import SdkConfig from 'src/components/sdk-config.mdx'; # Next.js -Keep in mind that all tracking here happens on the client! If you want to track server-side events, you should use the node SDK 👀. +Keep in mind that all tracking here happens on the client! + +Read more about server side tracking in the [Server Side Tracking](#track-server-events) section. ## Installation @@ -170,3 +172,32 @@ decrement('app_opened'); // Increment by 5 decrement('app_opened', 5); ``` + +#### Clear / Logout + +Clear the profile id and all the data. + +```typescript +import { clear } from '@openpanel/nextjs'; + +clear(); +``` + +### Track server events + +If you want to track server-side events, you should create an instance of our Javascript SDK. It's exported from `@openpanel/nextjs` + +```typescript +import { OpenpanelSdk } from '@openpanel/nextjs'; + +const opServer = new OpenpanelSdk({ + url: 'https://api.openpanel.dev', + clientId: '{YOUR_CLIENT_ID}', + clientSecret: '{YOUR_CLIENT_SECRET}', +}); + +opServer.event('my_server_event', { ok: '✅' }); + +// Pass `profileId` to track events for a specific user +opServer.event('my_server_event', { profileId: '123', ok: '✅' }); +``` diff --git a/apps/docs/src/pages/docs/node.mdx b/apps/docs/src/pages/docs/node.mdx new file mode 100644 index 00000000..7c7063c7 --- /dev/null +++ b/apps/docs/src/pages/docs/node.mdx @@ -0,0 +1,5 @@ +import Link from 'next/link'; + +# Node + +Use Javascript SDK to track events in Node. diff --git a/apps/docs/src/pages/docs/react-native.mdx b/apps/docs/src/pages/docs/react-native.mdx index e4ea54f5..1a103133 100644 --- a/apps/docs/src/pages/docs/react-native.mdx +++ b/apps/docs/src/pages/docs/react-native.mdx @@ -194,3 +194,11 @@ 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(); +``` diff --git a/apps/docs/src/pages/docs/react.mdx b/apps/docs/src/pages/docs/react.mdx index 66bee19c..6b660228 100644 --- a/apps/docs/src/pages/docs/react.mdx +++ b/apps/docs/src/pages/docs/react.mdx @@ -2,4 +2,4 @@ import Link from 'next/link'; # React -Use script tag or Javascript SDK for now. We'll add a dedicated react sdk soon. +Use script tag or Web SDK for now. We'll add a dedicated react sdk soon. diff --git a/apps/docs/src/pages/docs/remix.mdx b/apps/docs/src/pages/docs/remix.mdx index 8b3221ce..7e34cd88 100644 --- a/apps/docs/src/pages/docs/remix.mdx +++ b/apps/docs/src/pages/docs/remix.mdx @@ -2,4 +2,4 @@ import Link from 'next/link'; # Remix -Use script tag or Javascript SDK for now. We'll add a dedicated react sdk soon. +Use script tag or Web SDK for now. We'll add a dedicated remix sdk soon. diff --git a/apps/docs/src/pages/docs/script.mdx b/apps/docs/src/pages/docs/script.mdx index d7f9c234..ba992857 100644 --- a/apps/docs/src/pages/docs/script.mdx +++ b/apps/docs/src/pages/docs/script.mdx @@ -104,6 +104,14 @@ window.op('decrement', 'app_opened'); window.op('decrement', 'app_opened', 5); ``` +#### Clear / Logout + +Clear the profile id and all the data. + +```typescript +window.op('clear'); +``` + ### Typescript Is your IDE mad at you for not using typescript? We got you covered. diff --git a/apps/docs/src/pages/docs/vue.mdx b/apps/docs/src/pages/docs/vue.mdx index e7de0406..dad0be92 100644 --- a/apps/docs/src/pages/docs/vue.mdx +++ b/apps/docs/src/pages/docs/vue.mdx @@ -2,4 +2,4 @@ import Link from 'next/link'; # Vue -Use script tag or Javascript SDK for now. We'll add a dedicated react sdk soon. +Use script tag or Web SDK for now. We'll add a dedicated react sdk soon. diff --git a/apps/docs/src/pages/docs/web.mdx b/apps/docs/src/pages/docs/web.mdx new file mode 100644 index 00000000..8f9b9b81 --- /dev/null +++ b/apps/docs/src/pages/docs/web.mdx @@ -0,0 +1,138 @@ +import Link from 'next/link'; +import { Callout, Steps, Tabs } from 'nextra/components'; +import { DeviceIdWarning } from 'src/components/device-id-warning'; +import { PersonalDataWarning } from 'src/components/personal-data-warning'; + +import SdkConfig from 'src/components/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. + +## Installation + + +### Install dependencies + +```bash +pnpm install @openpanel/web +``` + +### Initialize + +```tsx +import { Openpanel } from '@openpanel/web'; + +const op = new Openpanel({ + url: 'https://api.openpanel.dev', + clientId: '{YOUR_CLIENT_ID}', + trackScreenViews: true, + // trackAttributes: true, + // trackOutgoingLinks: true, +}); +``` + +#### Config + + + +### Ready! + +You're now ready to use the library. + +```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 +``` + + + +## 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(); +```