zias/stats
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feature(public,docs): new public website and docs

Browse Source
This commit is contained in:
Carl-Gerhard Lindesvärd
2024-11-13 21:15:46 +01:00
parent fc2a019e1d
commit a022cb4831
234 changed files with 9341 additions and 6154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
apps/public/content/docs/sdks/astro.mdx Normal file
View File

@@ -0,0 +1,5 @@
---
title: Astro
---
You can use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) to track events in Astro.

80
apps/public/content/docs/sdks/express.mdx Normal file
View File

@@ -0,0 +1,80 @@
---
title: Express
description: The Express middleware is a basic wrapper around Javascript SDK. It provides a simple way to add the SDK to your Express application.
---
import Link from 'next/link';
import { DeviceIdWarning } from '@/components/device-id-warning';
import { PersonalDataWarning } from '@/components/personal-data-warning';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
## Installation
```bash
pnpm install @openpanel/express
```
## Usage
The default export of `@openpanel/express` is a function that returns an Express middleware. It will also append the Openpanel SDK to the `req` object.
You can access it via `req.op`.
```ts
import express from 'express';
import createOpenpanelMiddleware from '@openpanel/express';
const app = express();
app.use(
createOpenpanelMiddleware({
clientId: 'xxx',
clientSecret: 'xxx',
// trackRequest(url) {
// return url.includes('/v1')
// },
// getProfileId(req) {
// return req.user.id
// }
})
);
app.get('/sign-up', (req, res) => {
// track sign up events
req.op.track('sign-up', {
email: req.body.email,
});
res.send('Hello World');
});
app.listen(3000, () => {
console.log('Server is running on http://localhost:3000');
});
```
### Options
<CommonSdkConfig />
#### Express options
- `trackRequest` - A function that returns `true` if the request should be tracked.
- `getProfileId` - A function that returns the profile ID of the user making the request.
## Typescript
If `req.op` is not typed you can extend the `Request` interface.
```ts
import { OpenPanel } from '@openpanel/express';
declare global {
namespace Express {
export interface Request {
op: OpenPanel;
}
}
}
```

140
apps/public/content/docs/sdks/javascript.mdx Normal file
View File

@@ -0,0 +1,140 @@
---
title: Javascript (Node / Generic)
description: 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.
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { PersonalDataWarning } from '@/components/personal-data-warning';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
import WebSdkConfig from '@/components/web-sdk-config.mdx';
## Installation
<Steps>
### Step 1: Install
```bash
npm install @openpanel/sdk
```
### Step 2: Initialize
```js filename="op.ts"
import { OpenPanel } from '@openpanel/sdk';
const op = new OpenPanel({
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET',
});
```
#### Options
<CommonSdkConfig />
### Step 3: Usage
```js filename="main.ts"
import { op } from './op.js';
op.track('my_event', { foo: 'bar' });
```
</Steps>
## Usage
### Tracking Events
You can track events with two different methods: by calling the `op.track( directly or by adding `data-track` attributes to your HTML elements.
```ts filename="index.ts"
import { op } from './op.ts';
op.track('my_event', { foo: 'bar' });
```
### Identifying Users
To identify a user, call the `op.identify( method with a unique identifier.
```js filename="index.js"
import { op } from './op.ts';
op.identify({
profileId: '123', // Required
firstName: 'Joe',
lastName: 'Doe',
email: 'joe@doe.com',
properties: {
tier: 'premium',
},
});
```
### Setting Global Properties
To set properties that will be sent with every event:
```js filename="index.js"
import { op } from './op.ts'
op.setGlobalProperties({
app_version: '1.0.2',
environment: 'production',
});
```
### Creating Aliases
To create an alias for a user:
```js filename="index.js"
import { op } from './op.ts'
op.alias({
alias: 'a1',
profileId: '1'
});
```
### Incrementing Properties
To increment a numeric property on a user profile.
- `value` is the amount to increment the property by. If not provided, the property will be incremented by 1.
```js filename="index.js"
import { op } from './op.ts'
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="index.js"
import { op } from './op.ts'
op.decrement({
profileId: '1',
property: 'visits',
value: 1 // optional
});
```
### Clearing User Data
To clear the current user's data:
```js filename="index.js"
import { op } from './op.ts'
op.clear()
```

5
apps/public/content/docs/sdks/meta.json Normal file
View File

@@ -0,0 +1,5 @@
{
"title": "SDKs",
"pages": ["script", "web", "javascript", "node", "nextjs", "..."],
"defaultOpen": true
}

303
apps/public/content/docs/sdks/nextjs.mdx Normal file
View File

@@ -0,0 +1,303 @@
---
title: Next.js
---
import Link from 'next/link';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { DeviceIdWarning } from '@/components/device-id-warning';
import { PersonalDataWarning } from '@/components/personal-data-warning';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
import WebSdkConfig from '@/components/web-sdk-config.mdx';
## Good to know
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
<Steps>
### Install dependencies
```bash
pnpm install @openpanel/nextjs
```
### Initialize
Add `OpenPanelComponent` to your root layout component.
```tsx
import { OpenPanelComponent } from '@openpanel/nextjs';
export default RootLayout({ children }) {
return (
<>
<OpenPanelComponent
clientId="your-client-id"
trackScreenViews={true}
// trackAttributes={true}
// trackOutgoingLinks={true}
// If you have a user id, you can pass it here to identify the user
// profileId={'123'}
/>
{children}
</>
)
}
```
#### Options
<CommonSdkConfig />
<WebSdkConfig />
##### NextJS options
- `profileId` - If you have a user id, you can pass it here to identify the user
- `cdnUrl` - The url to the OpenPanel SDK (default: `https://openpanel.dev/op1.js`)
- `filter` - This is a function that will be called before tracking an event. If it returns false the event will not be tracked. [Read more](#filter)
- `globalProperties` - This is an object of properties that will be sent with every event.
##### `filter`
This options needs to be a stringified function and cannot access any variables outside of the function.
```tsx
<OpenPanelComponent
clientId="your-client-id"
filter={`
function filter(event) {
return event.name !== 'my_event';
}
`}
/>
```
To take advantage of typescript you can do the following. _Note `toString`_
```tsx /.toString();/
import { type OpenPanelOptions } from '@openpanel/nextjs';
const opFilter = ((event: TrackHandlerPayload) => {
return event.type === 'track' && event.payload.name === 'my_event';
}).toString();
<OpenPanelComponent
clientId="your-client-id"
filter={opFilter}
/>
```
</Steps>
## Usage
### Client components
For client components you can just use the `useOpenPanel` hook.
```tsx
import { useOpenPanel } from '@openpanel/nextjs';
function YourComponent() {
const op = useOpenPanel();
return <button type="button" onClick={() => op.track('my_event', { foo: 'bar' })}>Trigger event</button>
}
```
### Server components
Since you can't use hooks in server components, you need to create an instance of the SDK. This is exported from `@openpanel/nextjs`.
<Callout>Remember, your client secret is exposed here so do not use this on client side.</Callout>
```tsx filename="utils/op.ts"
import { OpenPanel } from '@openpanel/nextjs';
export const op = new OpenPanel({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
});
// Now you can use `op` to track events
op.track('my_event', { foo: 'bar' });
```
Refer to the [Javascript SDK](/docs/sdks/javascript#usage) for usage instructions.
### Tracking Events
You can track events with two different methods: by calling the `op.track( directly or by adding `data-track` attributes to your HTML elements.
```ts filename="index.ts"
useOpenPanel().track('my_event', { foo: 'bar' });
```
### Identifying Users
To identify a user, call the `op.identify( method with a unique identifier.
```js filename="index.js"
useOpenPanel().identify({
profileId: '123', // Required
firstName: 'Joe',
lastName: 'Doe',
email: 'joe@doe.com',
properties: {
tier: 'premium',
},
});
```
#### For server components
For server components you can use the `IdentifyComponent` component which is exported from `@openpanel/nextjs`.
> This component is great if you have the user data available on the server side.
```tsx filename="app/nested/layout.tsx"
import { IdentifyComponent } from '@openpanel/nextjs';
export default function Layout({ children }) {
const user = await getCurrentUser()
return (
<>
<IdentifyComponent
profileId={user.id}
firstName={user.firstName}
lastName={user.lastName}
email={user.email}
properties={{
tier: 'premium',
}}
/>
{children}
</>
)
}
```
### Setting Global Properties
To set properties that will be sent with every event:
```js filename="index.js"
useOpenPanel().setGlobalProperties({
app_version: '1.0.2',
environment: 'production',
});
```
### Creating Aliases
To create an alias for a user:
```js filename="index.js"
useOpenPanel().alias({
alias: 'a1',
profileId: '1'
});
```
### Incrementing Properties
To increment a numeric property on a user profile.
- `value` is the amount to increment the property by. If not provided, the property will be incremented by 1.
```js filename="index.js"
useOpenPanel().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="index.js"
useOpenPanel().decrement({
profileId: '1',
property: 'visits',
value: 1 // optional
});
```
### Clearing User Data
To clear the current user's data:
```js filename="index.js"
useOpenPanel().clear()
```
## Server side
If you want to track server-side events, you should create an instance of our Javascript SDK. It's exported from `@openpanel/nextjs`
<Callout>
When using server events it's important that you use a secret to authenticate the request. This is to prevent unauthorized requests since we cannot use cors headers.
You can use the same clientId but you should pass the associated client secret to the SDK.
</Callout>
```typescript
import { OpenpanelSdk } from '@openpanel/nextjs';
const opServer = new OpenpanelSdk({
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: '✅' });
```
### Serverless & Vercel
If you log events in a serverless environment like Vercel, you can use `waitUntil` to ensure the event is logged before the function is done.
Otherwise your function might close before the event is logged. Read more about it [here](https://vercel.com/docs/functions/functions-api-reference#waituntil).
```typescript
import { waitUntil } from '@vercel/functions';
import { opServer } from 'path/to/your-sdk-instance';
export function GET() {
// Returns a response immediately while keeping the function alive
waitUntil(opServer.event('my_server_event', { foo: 'bar' }));
return new Response(`You're event has been logged!`);
}
```
### Proxy events
With `createNextRouteHandler` you can proxy your events through your server, this will ensure all events are tracked since there is a lot of adblockers that block requests to third party domains.
```typescript filename="/app/api/op/route.ts"
import { createNextRouteHandler } from '@openpanel/nextjs/server';
export const POST = createNextRouteHandler();
```
Remember to change the `apiUrl` in the `OpenPanelComponent` to your own server.
```tsx {2}
<OpenPanelComponent
apiUrl="/api/op"
clientId="your-client-id"
trackScreenViews={true}
/>
```

115
apps/public/content/docs/sdks/react-native.mdx Normal file
View File

@@ -0,0 +1,115 @@
---
title: React Native
---
import Link from 'next/link';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { DeviceIdWarning } from '@/components/device-id-warning';
import { PersonalDataWarning } from '@/components/personal-data-warning';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
## Installation
<Steps>
### Install dependencies
We're dependent on `expo-application` for `buildNumber`, `versionNumber` (and `referrer` on android) and `expo-constants` to get the `user-agent`.
```bash
npm install @openpanel/react-native
npx expo install expo-application expo-constants
```
### Initialize
On native we use a clientSecret to authenticate the app.
```typescript
const op = new Openpanel({
clientId: '{YOUR_CLIENT_ID}',
clientSecret: '{YOUR_CLIENT_SECRET}',
});
```
#### Options
<CommonSdkConfig />
</Steps>
## Usage
### Track event
```typescript
op.track('my_event', { foo: 'bar' });
```
### Navigation / Screen views
<Tabs items={['expo-router', 'react-navigation (simple)']}>
<Tab value="expo-router">
```typescript
import { usePathname, useSegments } from 'expo-router';
const op = new Openpanel({ /* ... */ })
function RootLayout() {
// ...
const pathname = usePathname()
// Segments is optional but can be nice to have if you
// want to group routes together
// pathname = /posts/123
// segements = ['posts', '[id]']
const segments = useSegments()
useEffect(() => {
// Simple
op.screenView(pathname)
// With extra data
op.screenView(pathname, {
// segments is optional but nice to have
segments: segments.join('/'),
// other optional data you want to send with the screen view
})
}, [pathname,segments])
// ...
}
```
</Tab>
<Tab value="react-navigation (simple)">
```tsx
import { createNavigationContainerRef } from '@react-navigation/native'
import { Openpanel } from '@openpanel/react-native'
const op = new Openpanel({ /* ... */ })
const navigationRef = createNavigationContainerRef()
export function NavigationRoot() {
const handleNavigationStateChange = () => {
const current = navigationRef.getCurrentRoute()
if (current) {
op.screenView(current.name, {
params: current.params,
})
}
}
return (
<NavigationContainer
ref={navigationRef}
onReady={handleNavigationStateChange}
onStateChange={handleNavigationStateChange}
>
<Stack.Navigator />
</NavigationContainer>
)
}
```
</Tab>
</Tabs>
For more information on how to use the SDK, check out the [Javascript SDK](/docs/sdks/javascript#usage).

5
apps/public/content/docs/sdks/react.mdx Normal file
View File

@@ -0,0 +1,5 @@
---
title: React
---
Use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now. We'll add a dedicated react sdk soon.

5
apps/public/content/docs/sdks/remix.mdx Normal file
View File

@@ -0,0 +1,5 @@
---
title: Remix
---
Use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now. We'll add a dedicated remix sdk soon.

211
apps/public/content/docs/sdks/script.mdx Normal file
View File

@@ -0,0 +1,211 @@
---
title: Script Tag
description: 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.
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { PersonalDataWarning } from '@/components/personal-data-warning';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
import WebSdkConfig from '@/components/web-sdk-config.mdx';
## Installation
Just insert this snippet and replace `YOUR_CLIENT_ID` with your client id.
```html filename="index.html" /clientId: 'YOUR_CLIENT_ID'/
<script>
window.op = window.op||function(...args){(window.op.q=window.op.q||[]).push(args);};
window.op('init', {
clientId: 'YOUR_CLIENT_ID',
trackScreenViews: true,
trackOutgoingLinks: true,
trackAttributes: true,
});
</script>
<script src="https://openpanel.dev/op1.js" defer async></script>
```
#### Options
<CommonSdkConfig />
<WebSdkConfig />
## Usage
### Tracking Events
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.
```html filename="index.html"
<button type="button" onclick="window.op('track', 'my_event', { foo: 'bar' })">
Track event
</button>
```
```html filename="index.html"
<button type="button" data-track="my_event" data-foo="bar">Track event</button>
```
### Identifying Users
To identify a user, call the `window.op('identify')` method with a unique identifier.
```js filename="main.js"
window.op('identify', {
profileId: '123', // Required
firstName: 'Joe',
lastName: 'Doe',
email: 'joe@doe.com',
properties: {
tier: 'premium',
},
});
```
### Setting Global Properties
To set properties that will be sent with every event:
```js filename="main.js"
window.op('setGlobalProperties', {
app_version: '1.0.2',
environment: 'production',
});
```
### Creating Aliases
To create an alias for a user:
```js filename="main.js"
window.op('alias', {
alias: 'a1',
profileId: '1'
});
```
### Incrementing Properties
To increment a numeric property on a user profile.
- `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
### Filtering events
You can filter out events by adding a `filter` property to the `init` method.
Below is an example of how to disable tracking for users who have a `disable_tracking` item in their local storage.
```js filename="main.js"
window.op('init', {
clientId: 'YOUR_CLIENT_ID',
trackScreenViews: true,
trackOutgoingLinks: true,
trackAttributes: true,
filter: () => localStorage.getItem('disable_tracking') === undefined,
});
```
### Using the Web SDK with NPM
<Steps>
#### 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' });
```
</Steps>
### Typescript
Getting ts errors when using the SDK? You can add a custom type definition file to your project.
#### Simple
Just paste this code in any of your `.d.ts` files.
```ts filename="op.d.ts"
declare global {
interface Window {
op: {
q?: string[][];
(...args: [
'init' | 'track' | 'identify' | 'setGlobalProperties' | 'alias' | 'increment' | 'decrement' | 'clear',
...any[]
]): void;
};
}
}
```
#### Strict typing (from sdk)
<Steps>
##### Step 1: Install the SDK
```bash
npm install @openpanel/web
```
##### Step 2: Create a type definition file
Create a `op.d.ts`file and paste the following code:
```ts filename="op.d.ts"
/// <reference types="@openpanel/web" />
```
</Steps>

5
apps/public/content/docs/sdks/vue.mdx Normal file
View File

@@ -0,0 +1,5 @@
---
title: Vue
---
Use [script tag](/docs/sdks/script) or [Web SDK](/docs/sdks/web) for now. We'll add a dedicated react sdk soon.

49
apps/public/content/docs/sdks/web.mdx Normal file
View File

@@ -0,0 +1,49 @@
---
title: Javascript (Web)
description: 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.
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { PersonalDataWarning } from '@/components/personal-data-warning';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';
import WebSdkConfig from '@/components/web-sdk-config.mdx';
## Installation
<Steps>
### Step 1: Install
```bash
npm install @openpanel/web
```
### Step 2: Initialize
```js filename="op.ts"
import { OpenPanel } from '@openpanel/web';
const op = new OpenPanel({
clientId: 'YOUR_CLIENT_ID',
trackScreenViews: true,
trackOutgoingLinks: true,
trackAttributes: true,
});
```
#### Options
<CommonSdkConfig />
<WebSdkConfig />
### Step 3: Usage
```js filename="main.ts"
import { op } from './op.js';
op.track('my_event', { foo: 'bar' });
```
</Steps>
## Usage
Refer to the [Javascript SDK](/docs/sdks/javascript#usage) for usage instructions.