@fnel/vue

Vue.js SDK for fnel funnel tracking. This package provides a Vue plugin and composables for easy integration of fnel tracking into your Vue 3 applications.

Features

• 🚀 Easy Integration: Simple plugin pattern with Vue 3 composables
• 🔄 Auto-initialization: Automatically loads and initializes the fnel SDK
• 📱 Vue 3 Ready: Built for Vue 3 with Composition API support
• 🎯 Funnel Tracking: Dedicated composables for funnel step tracking
• 💾 State Management: Automatic state synchronization with the SDK
• 🛡️ TypeScript: Full TypeScript support with comprehensive types
• 🔧 Debug Support: Access to debug information and SDK state
• 🎨 Template Support: Access fnel functionality directly in templates

Installation

npm install @fnel/vue
# or
yarn add @fnel/vue
# or
pnpm add @fnel/vue

Quick Start

1. Install the plugin in your app

import { createApp } from 'vue';
import { FnelPlugin } from '@fnel/vue';
import App from './App.vue';

const app = createApp(App);

app.use(FnelPlugin, {
  apiToken: 'your-api-token-here'
});

app.mount('#app');

2. Use the composable in your components

<template>
  <div>
    <p v-if="isInitialized">Fnel initialized!</p>
    <p>User ID: {{ userId }}</p>
    <button @click="trackLandingPage">Track Landing Page</button>
  </div>
</template>

<script setup lang="ts">
import { useFnel } from '@fnel/vue';

const { track, isInitialized, userId } = useFnel();

const trackLandingPage = async () => {
  await track({
    name: 'landing_page',
    step: 1,
    funnel: 'abc123def'
  });
};
</script>

3. Or use the specialized funnel tracking composable

<template>
  <div>
    <button @click="trackStep1">Complete Step 1</button>
    <button @click="trackStep2">Complete Step 2</button>
  </div>
</template>

<script setup lang="ts">
import { useFunnelTracking } from '@fnel/vue';

const { trackFunnelStep, isInitialized } = useFunnelTracking();

const trackStep1 = async () => {
  await trackFunnelStep('onboarding', 1, 'welcome_page', {
    source: 'direct_traffic'
  });
};

const trackStep2 = async () => {
  await trackFunnelStep('onboarding', 2, 'signup_form', {
    form_type: 'email'
  });
};
</script>

API Reference

FnelPlugin

The main plugin that initializes the fnel SDK globally.

app.use(FnelPlugin, {
  apiToken: 'your-api-token',
  autoInit: true, // optional, default: true
  onInit: (result) => console.log('Initialized:', result), // optional
  onError: (error) => console.error('Error:', error) // optional
});

Options

• apiToken (required): Your fnel API token
• autoInit (optional): Whether to automatically initialize on mount (default: true)
• onInit (optional): Callback when initialization succeeds
• onError (optional): Callback when errors occur

useFnel

The main composable that provides access to all fnel functionality.

const {
  isInitialized,
  userId,
  track,
  version,
  getUserId,
  getQueueLength,
  clearQueue,
  clearStorage,
  reset
} = useFnel();

Returns

• isInitialized: Reactive boolean indicating if fnel is initialized
• userId: Reactive string containing the current user ID
• track: Function to track events
• version: Reactive string containing the SDK version
• getUserId: Function to get the current user ID
• getQueueLength: Function to get the current queue length
• clearQueue: Function to clear the event queue
• clearStorage: Function to clear stored data
• reset: Function to reset the SDK state

useFunnelTracking

A specialized composable for funnel tracking with a simplified API.

const { trackFunnelStep, isInitialized } = useFunnelTracking();

await trackFunnelStep(
  'funnel_id',    // The funnel identifier
  1,              // Step number
  'step_name',    // Step name/description
  {               // Additional data (optional)
    source: 'direct_traffic',
    campaign: 'summer_2024'
  }
);

Template Usage

When using the plugin, you can also access fnel functionality directly in templates:

<template>
  <div>
    <button @click="$fnel.track({ name: 'button_click', step: 1, funnel: 'demo' })">
      Track Click
    </button>
    <p>Initialized: {{ $fnel.isInitialized }}</p>
    <p>User ID: {{ $fnel.userId }}</p>
  </div>
</template>

Advanced Usage

Manual SDK Control

For advanced use cases, you can access the SDK directly:

import { fnelSDK } from '@fnel/vue';

// Manual initialization
await fnelSDK.init('your-api-token');

// Direct tracking
await fnelSDK.track({
  name: 'custom_event',
  step: 1,
  funnel: 'custom_funnel'
});

Custom Event Data

You can include additional data with your events:

await track({
  name: 'purchase_completed',
  step: 3,
  funnel: 'checkout',
  amount: 99.99,
  currency: 'USD',
  product_id: 'prod_123',
  category: 'electronics'
});

TypeScript Support

The package includes comprehensive TypeScript types:

import type { FnelEvent, FnelInitResult, FnelTrackResult } from '@fnel/vue';

const event: FnelEvent = {
  name: 'page_view',
  step: 1,
  funnel: 'marketing_funnel'
};

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.