npm package: @openpanel/astro
Description: > 📖 **Full documentation:** [https://openpanel.dev/docs/sdks/astro](https://openpanel.dev/docs/sdks/astro)
Latest version: 1.3.0

# Astro

> 📖 **Full documentation:** [https://openpanel.dev/docs/sdks/astro](https://openpanel.dev/docs/sdks/astro)

---

Looking for a step-by-step tutorial? Check out the [Astro analytics guide](https://openpanel.dev/guides/astro-analytics).

## Installation

### Install dependencies

```bash
pnpm install @openpanel/astro
```

### Initialize

Add `OpenPanelComponent` to your root layout component.

```astro
---
import { OpenPanelComponent } from '@openpanel/astro';
---

<html>
  <head>
    <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'}
    />
  </head>
  <body>
    <slot />
  </body>
</html>
```

#### Options

##### Common options

- `apiUrl` - The url of the openpanel API or your self-hosted instance
- `clientId` - The client id of your application
- `clientSecret` - The client secret of your application (**only required for server-side events**)
- `filter` - A function that will be called before sending an event. If it returns false, the event will not be sent
- `disabled` - If true, the library will not send any events

##### Web options

- `trackScreenViews` - If true, the library will automatically track screen views (default: false)
- `trackOutgoingLinks` - If true, the library will automatically track outgoing links (default: false)
- `trackAttributes` - If true, you can trigger events by using html attributes (`<button type="button" data-track="your_event" />`) (default: false)
- `sessionReplay` - Session replay configuration object (default: disabled). See [session replay docs](https://openpanel.dev/docs/session-replay) for full options.
  - `enabled` - Enable session replay recording (default: false)
  - `maskAllInputs` - Mask all input field values (default: true)
  - `maskTextSelector` - CSS selector for text elements to mask (default: `[data-openpanel-replay-mask]`)
  - `blockSelector` - CSS selector for elements to replace with a placeholder (default: `[data-openpanel-replay-block]`)
  - `blockClass` - Class name that blocks elements from being recorded
  - `ignoreSelector` - CSS selector for elements excluded from interaction tracking
  - `flushIntervalMs` - How often (ms) recorded events are sent to the server (default: 10000)
  - `maxEventsPerChunk` - Maximum events per payload chunk (default: 200)
  - `maxPayloadBytes` - Maximum payload size in bytes (default: 1048576)
  - `scriptUrl` - Custom URL for the replay script (script-tag builds only)

##### Astro options

- `profileId` - If you have a user id, you can pass it here to identify the user
- `cdnUrl` (deprecated) - The url to the OpenPanel SDK (default: `https://openpanel.dev/op1.js`)
- `scriptUrl` - 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.

```astro
<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`_
```ts
import { type TrackHandlerPayload } from '@openpanel/astro';

const opFilter = ((event: TrackHandlerPayload) => {
  return event.type === 'track' && event.payload.name === 'my_event';
}).toString();

<OpenPanelComponent
  clientId="your-client-id"
  filter={opFilter}
/>
```

## Usage

### Client-side Tracking

You can track events with the global op function or you can use data attributes.

```astro
<button onclick="window.op('track', 'clicky')">Click me</button>
<button data-track="clicky" data-prop1="prop1" data-prop2="prop2">Click me</button>
```

### Identifying Users

To identify a user, you can use either the `identify` function or the `IdentifyComponent`.

```astro
---
import { IdentifyComponent } from '@openpanel/astro';
---

<IdentifyComponent
  profileId="123"
  firstName="Joe"
  lastName="Doe"
  email="joe@doe.com"
  properties={{
    tier: 'premium',
  }}
/>
```

### Setting Global Properties

You can set global properties that will be sent with every event using either the `setGlobalProperties` function or the `SetGlobalPropertiesComponent`.

```astro
---
import { SetGlobalPropertiesComponent } from '@openpanel/astro';
---

<SetGlobalPropertiesComponent
  properties={{
    app_version: '1.0.2',
    environment: 'production',
  }}
/>
```