Detect: Beacon Integration

npm install @kya-os/checkpoint-beacon

yarn add @kya-os/checkpoint-beacon

pnpm add @kya-os/checkpoint-beacon

// hooks/useCheckpointBeacon.ts
import { useEffect, useRef } from 'react';
import { CheckpointBeacon } from '@kya-os/checkpoint-beacon';

export function useCheckpointBeacon() {
  const beaconRef = useRef<CheckpointBeacon | null>(null);

  useEffect(() => {
    const beacon = new CheckpointBeacon({
      projectId: process.env.NEXT_PUBLIC_CHECKPOINT_PROJECT_ID!,
      debug: process.env.NODE_ENV === 'development',
      logLevel: process.env.NODE_ENV === 'development' ? 'debug' : 'error',
    });
    beaconRef.current = beacon;

    // Record the initial page view
    beacon.collect('pageview');

    return () => {
      beacon.destroy(); // flushes pending events
    };
  }, []);

  const track = (name: string, metadata?: Record<string, unknown>) => {
    beaconRef.current?.trackEvent(name, metadata);
  };

  return { track };
}

// components/CheckpointProvider.tsx
'use client';

import { createContext, useContext, ReactNode } from 'react';
import { useCheckpointBeacon } from '@/hooks/useCheckpointBeacon';

const BeaconContext = createContext<ReturnType<typeof useCheckpointBeacon> | null>(null);

export function CheckpointProvider({ children }: { children: ReactNode }) {
  const beacon = useCheckpointBeacon();
  return <BeaconContext.Provider value={beacon}>{children}</BeaconContext.Provider>;
}

export function useBeacon() {
  const context = useContext(BeaconContext);
  if (!context) throw new Error('useBeacon must be used within CheckpointProvider');
  return context;
}

// composables/useCheckpointBeacon.ts
import { onMounted, onUnmounted, ref } from 'vue';
import { CheckpointBeacon } from '@kya-os/checkpoint-beacon';

export function useCheckpointBeacon() {
  const beacon = ref<CheckpointBeacon | null>(null);

  onMounted(() => {
    beacon.value = new CheckpointBeacon({
      projectId: import.meta.env.VITE_CHECKPOINT_PROJECT_ID,
    });
    beacon.value.collect('pageview');
  });

  onUnmounted(() => {
    beacon.value?.destroy();
  });

  const track = (name: string, metadata?: Record<string, unknown>) => {
    beacon.value?.trackEvent(name, metadata);
  };

  return { track };
}

<script setup lang="ts">
import { useCheckpointBeacon } from '@/composables/useCheckpointBeacon';

const { track } = useCheckpointBeacon();

function handleFormSubmit() {
  track('form_submit', { formId: 'contact' });
}
</script>

<template>
  <button @click="handleFormSubmit">Submit</button>
</template>

// detection.ts
import { CheckpointBeacon } from '@kya-os/checkpoint-beacon';

const beacon = new CheckpointBeacon({
  projectId: 'acme-corp',
  debug: true,
  logLevel: 'debug',
});

// Record the initial page view
beacon.collect('pageview');

// Track custom events
document.getElementById('checkout-btn')?.addEventListener('click', () => {
  beacon.trackEvent('checkout_started', {
    cartValue: 99.99,
    itemCount: 3,
  });
});

// Flush reliably on unload
window.addEventListener('pagehide', () => {
  beacon.trackPageUnload();
});

export { beacon };