Vue | Pieowl

Looking for a step-by-step tutorial? Read the Vue analytics guide.

Good to know

All tracking on this page happens in the browser.

For Vue single-page apps, use @pieowl/web directly. You don't need a separate Vue SDK: create one Pieowl instance and import it where you need it. For Nuxt, see Nuxt.

Installation

Step 1: Install

bash

npm install @pieowl/web

Step 2: Initialize

Create a shared Pieowl instance in your project:

src/pieowl.ts

import { Pieowl } from '@pieowl/web';

export const pieowl = new Pieowl({
  clientId: 'YOUR_CLIENT_ID',
});

clientId is enough. What the SDK collects by itself (page views, outside link clicks, data-track clicks) is set in Settings → Site → What Pieowl counts, not in code.

Options

Common options

apiUrl - The URL of the Pieowl API (default: https://api.pieowl.com). Change it only to send events through your own proxy
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, events are queued and not sent until you call ready() (useful for consent)

Web options

What the script collects by itself is set per site in Settings → Site → What Pieowl counts, not in code. The four options below are only a fallback, used when the script can't load those settings.

trackScreenViews - Fallback for Page views (default: true)
trackOutgoingLinks - Fallback for Clicks on links to other sites (default: true)
trackAttributes - Fallback for Clicks you marked in your code, elements with data-track (default: true)
trackHashChanges - Fallback for Address changes after #, for hash-based routers (default: false)
sessionReplay - Technical options for the screen recorder. Most sites need none. Turning replay on and choosing how many visits to record is done in Settings → Site → What Pieowl counts. Text and form fields are always hidden. See session replay docs.
- blockSelector - CSS selector for elements to replace with a placeholder (default: [data-pieowl-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)

Step 3: Usage

Import the instance in your Vue components:

vue

<script setup>
import { pieowl } from '@/pieowl';

function handleClick() {
  pieowl.track('button_click', { button: 'signup' });
}
</script>

<template>
  <button @click="handleClick">Trigger event</button>
</template>

Usage

Tracking events

Call pieowl.track() directly, or add data-track attributes to your buttons and links. data-track needs Clicks you marked in your code to be on in Settings → Site (it is by default).

vue

<script setup>
import { pieowl } from '@/pieowl';

pieowl.track('my_event', { foo: 'bar' });
</script>

Identifying users

To identify a user, call pieowl.identify() with a unique ID.

This is personal data. Make sure you have the user's consent before you call this.

vue

<script setup>
import { pieowl } from '@/pieowl';

pieowl.identify({
  profileId: '123', // Required
  firstName: 'Joe',
  lastName: 'Doe',
  email: 'joe@doe.com',
  properties: {
    tier: 'premium',
  },
});
</script>

Setting global properties

To set properties that are sent with every event:

vue

<script setup>
import { pieowl } from '@/pieowl';

pieowl.setGlobalProperties({
  app_version: '1.0.2',
  environment: 'production',
});
</script>

Incrementing properties

To increase a numeric property on a user profile.

value is the amount to add. If you leave it out, the property goes up by 1.

vue

<script setup>
import { pieowl } from '@/pieowl';

pieowl.increment({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});
</script>

Decrementing properties

To decrease a numeric property on a user profile.

value is the amount to subtract. If you leave it out, the property goes down by 1.

vue

<script setup>
import { pieowl } from '@/pieowl';

pieowl.decrement({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});
</script>

Clearing user data

To clear the current user's data:

vue

<script setup>
import { pieowl } from '@/pieowl';

pieowl.clear();
</script>

Revenue tracking

Call purchase() with your order number and the amount in normal units, like 49.99. currency is optional and defaults to your site currency. The same order sent twice counts once. Purchases and refunds from the browser only work after you turn on Accept revenue sent from the browser in Settings → Site → Revenue. Each purchase is credited to the current visit. See Revenue attribution.

vue

<script setup>
import { pieowl } from '@/pieowl';

// Track a purchase right away
await pieowl.purchase({ id: 'A-1001', amount: 29.99, currency: 'EUR' });

// Refund it later: the whole order, or pass amount for part of it
await pieowl.refund({ id: 'A-1001' });
</script>

Optional: create a composable

If you prefer a composable, write a small wrapper:

src/composables/usePieowl.ts

import { pieowl } from '@/pieowl';

export function usePieowl() {
  return pieowl;
}

Then use it in your components:

vue

<script setup>
import { usePieowl } from '@/composables/usePieowl';

const pieowl = usePieowl();
pieowl.track('my_event', { foo: 'bar' });
</script>