---
title: "Astro | SDKs | Documentation - Vemetric"
description: "Track your data via the Astro SDK for Vemetric."
url: https://vemetric.com/docs/sdks/astro
---

# Astro SDK

Track your data via the Astro SDK for Vemetric.

* * *

The Astro SDK is the preferred way to integrate Vemetric into your Astro application.

Below you can see how to initialize and configure the SDK, as well as all the available functions.

## Installation

### Install the npm package

In your project directory, run:

```bash
npm install @vemetric/astro
```

### Include the Vemetric Component

Import and include the `VemetricScript` component in your Astro application (in a place that is rendered on every page, ideally in the `<head>` tag):

```astro
---
import VemetricScript from '@vemetric/astro';
---

<!doctype html>
<html lang="en">
  <head>
    <slot name="head" />
    <VemetricScript token="YOUR_PROJECT_TOKEN" />
  </head>
  <body>
    <slot />
  </body>
</html>
```

> Replace `YOUR_PROJECT_TOKEN` with the unique token for your project (found in the project settings).

### Verify installation

Once added, Vemetric will automatically start tracking page views on your site (each page load will be recorded). You can verify this by checking your Vemetric dashboard for incoming pageview events a few seconds after loading a page.

> Data from `localhost` won’t be tracked by default. You can enable it [via the config](#configuration).

Keep in mind that one project can be used to track data from multiple websites, which can be useful when you for example want to track users across your landing page and web application. We’ve also created a guide on [how to track data across subdomains](https://vemetric.com/docs/advanced-guides/track-across-subdomains).

### Optional: Track custom events and identify logged-in users

You can track custom events from anywhere in your frontend by importing the `vemetric` object:

```html
<script>
  import { vemetric } from '@vemetric/astro';

  document.getElementById('avatar')?.addEventListener('click', () => {
    vemetric.trackEvent('Avatar Clicked', { eventData: { test: 123 } });
  });
</script>
```

See the [documentation below](#trackevent) for a detailed explanation of the available parameters.

Also learn more about [User Identification](https://vemetric.com/docs/product-analytics/user-identification) to track authenticated users and see their [full journey](https://vemetric.com/docs/product-analytics/user-journeys).

## Configuration

You can pass additional props to the `VemetricScript` component to configure Vemetric.

Look at the different options below for more details.

Example:

```astro
---
import VemetricScript from '@vemetric/astro';
---

<VemetricScript
  token="YOUR_PROJECT_TOKEN"
  scriptUrl="https://hub.yourdomain.com/main.js"
  host="https://hub.yourdomain.com"
  trackPageViews={true}
  trackOutboundLinks={true}
  trackDataAttributes={true}
  maskPaths={['/project/*', '/project/*/users']}
/>;
```

> Replace `YOUR_PROJECT_TOKEN` with the unique token for your project (found in the project settings).

* * *

`scriptUrl`

Description

Here you can specify a different URL for the Vemetric script.

Necessary if you want to [use a proxy for tracking your data](https://vemetric.com/docs/advanced-guides/using-a-proxy) via your own domain.

Type

string

Example

"https://hub.yourdomain.com/main.js"

* * *

`host`

Description

Here you can specify a different host for the Vemetric API.

Necessary if you want to [use a proxy for tracking your data](https://vemetric.com/docs/advanced-guides/using-a-proxy) via your own domain.

Type

string

Example

"https://hub.yourdomain.com"

* * *

`trackPageViews`

Description

Whether to track page views automatically.

Listens to any kind of changes of the URL (hash, pathname, search, etc.) and records a page view event. If disabled, you need to track page views manually.

Type

boolean

Default

"true"

* * *

`trackOutboundLinks`

Description

Whether to track outbound link clicks.

Type

boolean

Default

"true"

* * *

`trackDataAttributes`

Description

Whether to listen to `data-vmtrc` attributes on elements for [sending custom events](https://vemetric.com/docs/product-analytics/tracking-custom-events#data-attributes).

Type

boolean

Default

"true"

* * *

`maskPaths`

Description

An array of paths to mask from the URL. Helpful if you mask sensitive information in the URL (e.g. user IDs) or group page views by a specific path (e.g. `/project/*`).

Type

string\[\]

Example

"\['/project/\*', '/project/\*/users'\]"

* * *

`allowCookies`

Description

Whether to recognize returning visitors with a cookie. Only enable this after your visitors have given their consent where that’s required. Learn more about [using cookies](https://vemetric.com/docs/advanced-guides/using-cookies).

Type

boolean

Default

"false"

* * *

`allowLocalhost`

Description

Whether to track data from `localhost` and `127.0.0.1`. Requests from these hosts are ignored by default, so enable this if you want to track local development, or when tracking inside Capacitor apps.

Type

boolean

Default

"false"

* * *

## Methods

The Astro SDK exports a `vemetric` object that enables you to track custom events or identify users.

You can import it like this and use it anywhere in your application:

```tsx
import { vemetric } from '@vemetric/astro';

<button id="custom-event-button">
  Track Custom Event
</button>

<script>
  import { vemetric } from '@vemetric/astro';

  document.getElementById('custom-event-button')?.addEventListener('click', () => {
    vemetric.trackEvent('custom_event_astro');
  });
</script>
```

Below you can see all the available methods.

### trackEvent

The main method to track any kind of event.

```ts
import { vemetric } from '@vemetric/astro';

await vemetric.trackEvent('MyCustomEvent', {
  eventData: { key: 'value' },
}
```

The first argument is the event name. The second argument is optional and can be an object with the following properties (also both optional):

-   `eventData`: An object containing the meta data of the event so you can later filter by
-   `userData`: An object to update the user data. Only relevant for [identified users](https://vemetric.com/docs/product-analytics/user-identification).
    -   `set`: An object containing the user data to set, overriding existing values.
    -   `setOnce`: An object containing the user data to set once, only if the keys do not exist yet.
    -   `unset`: An array of keys to remove from the user data.

Checkout the [tracking custom events](https://vemetric.com/docs/product-analytics/tracking-custom-events) section to learn more.

### identify

With this function you can identify a user. All following events will be associated with this user. Checkout the docs about [User identification](https://vemetric.com/docs/product-analytics/user-identification) to learn more about how it works.

```ts
import { vemetric } from '@vemetric/astro';

await vemetric.identify({
  identifier: 'your-user-id', // we recommend to use the user's primary id in your database
  displayName: 'John Doe', // optional, will be used to display the users' name in Vemetric
  avatarUrl: 'https://example.com/avatar.jpg', // optional, will be used to display the users' avatar in Vemetric
});
```

The function takes the following parameters:

-   `identifier` **(Required):** The unique identifier for the user. We recommend to use the user's primary id in your database.
-   `displayName` (Optional): will be used to display the users' name in Vemetric
-   `avatarUrl` (Optional): will be used to display the users' avatar in Vemetric
-   `data` (Optional): An object to update the user data.
    -   `set`: An object containing the user data to set, overriding existing values.
    -   `setOnce`: An object containing the user data to set once, only if the keys do not exist yet.
    -   `unset`: An array of keys to remove from the user data.

### getUserIdentifier

Returns the identifier of the currently identified user. Returns `null` if no user is identified.

```ts
import { vemetric } from '@vemetric/astro';

const identifier = await vemetric.getUserIdentifier();
```

### updateUser

Updates the data of the currently identified user.

```ts
import { vemetric } from '@vemetric/astro';

vemetric.updateUser({
  displayName: 'John Doe',
  avatarUrl: 'https://example.com/avatar.jpg',
  set: { key1: 'value1' },
  setOnce: { key2: 'value2' },
  unset: ['key3'],
});
```

The first parameter is an object with the following properties:

-   `displayName` (Optional): will be used to display the users' name in Vemetric
-   `avatarUrl` (Optional): will be used to display the users' avatar in Vemetric
-   `set` (Optional): An object containing the user data to set, overriding existing values.
-   `setOnce` (Optional): An object containing the user data to set once, only if the keys do not exist yet.
-   `unset` (Optional): An array of keys to remove from the user data.

### resetUser

Should be called when the user logs out. From then on, all events will be tracked as anonymous. Checkout the docs about [User identification](https://vemetric.com/docs/product-analytics/user-identification#reset-user) to learn more about how it works.

```ts
import { vemetric } from '@vemetric/astro';

await vemetric.resetUser();
```

### enableTrackPageViews

A function to enable automatic page view tracking after initialization. Only needed if `trackPageViews` was disabled.

```ts
import { vemetric } from '@vemetric/astro';

vemetric.enableTrackPageViews();
```

### enableTrackOutboundLinks

A function to enable outbound link tracking after initialization. Only needed if `trackOutboundLinks` was disabled.

```ts
import { vemetric } from '@vemetric/astro';

vemetric.enableTrackOutboundLinks();
```

### enableTrackDataAttributes

A function to enable data attribute tracking after initialization. Only needed if `trackDataAttributes` was disabled. Learn more about [tracking custom events via data attributes](https://vemetric.com/docs/product-analytics/tracking-custom-events#data-attributes).

```ts
import { vemetric } from '@vemetric/astro';

vemetric.enableTrackDataAttributes();
```

### trackPageView

A function to manually track a page view from the current URL. Only needed if `trackPageViews` was disabled.

```ts
import { vemetric } from '@vemetric/astro';

await vemetric.trackPageView();
```

### trackPageLeave

A function to manually track a page leave. Only needed if `trackPageViews` was disabled.

```ts
import { vemetric } from '@vemetric/astro';

vemetric.trackPageLeave();
```

## Resources

[NPM Package](https://www.npmjs.com/package/@vemetric/astro)

View the NPM package of the Astro SDK.

[Source code](https://github.com/vemetric/vemetric-web/tree/main/packages/astro)

View the source code of the Astro SDK on GitHub.