@signap/signals-vue

@signap/signals-vue

Vue 3 composable wrapper for @signap/signals-web.

Install

pnpm add @signap/signals-vue
# vue is a peerDependency (>=3 <4)

Usage

Provide the agent once (a <SignalsProvider> near the root, or the plugin), then call useVisitorData() anywhere below it.

Provider + composable

<!-- App.vue -->
<script setup lang="ts">
import { SignalsProvider } from "@signap/signals-vue";
import Page from "./Page.vue";
</script>

<template>
  <SignalsProvider :agent="{ apiKey: 'pk_live_...' }">
    <Page />
  </SignalsProvider>
</template>

<!-- Page.vue -->
<script setup lang="ts">
import { useVisitorData } from "@signap/signals-vue";
const { data, isLoading, error, refetch } = useVisitorData({ tag: "page-view" });
</script>

<template>
  <p v-if="isLoading">Identifying…</p>
  <p v-else-if="error">Failed: {{ error.message }}</p>
  <template v-else>
    <p>visitor: {{ data?.visitorId }}</p>
    <p>confidence: {{ data?.confidence }}</p>
    <button @click="refetch()">Re-identify</button>
  </template>
</template>

Plugin (app-global alternative)

import { createApp } from "vue";
import { SignalsPlugin } from "@signap/signals-vue";
import App from "./App.vue";

createApp(App).use(SignalsPlugin, { apiKey: "pk_live_..." }).mount("#app");

useVisitorData() works the same whether the agent was provided by <SignalsProvider> or the plugin — both feed the same inject key.

Hook shape (v2)

useVisitorData() runs agent.identify() once when the agent is ready and exposes the resolved visitor as reactive refs. ADR §A2 means one round-trip — no separate ack/lookup transition.

SSR-safe: SignalsAgent.load() is gated behind onMounted (provider) or a typeof window guard (plugin), so it never runs during server render.

Holding collection

<SignalsProvider :agent="…" :enabled="false">, or app.use(SignalsPlugin, { ...opts, enabled }) with a ref, keeps the agent from loading. While it is false the SDK registers no event listener, runs no collector and sends no request, and useVisitorData() returns isHeld: true. Setting it to true loads the agent and runs the first identify, exactly as if enabled had never been set. Setting it back to false stops the SDK's interaction listeners for the whole page and discards any identify result still in flight; a request that has already been sent is not recalled. The plugin removes enabled before it calls SignalsAgent.load().

Holding or releasing does not delete anything Signap has already received.

The hold applies to the agent this provider or plugin loads. A copy of the SDK loaded another way, for example the CDN script, is not held.

Endpoint (required)

The agent prop / plugin option is the underlying AgentLoadOptions. endpoint is required — the published SDK ships no baked default host (the region→host map is empty in this alpha), so pass an explicit endpoint (a string or a callback). See the @signap/signals-web README (Endpoint section).

<SignalsProvider :agent="{ apiKey: 'pk_live_...', endpoint: 'https://ingest.signap.example' }">

The provider snapshots agent at mount (later prop changes are ignored — remount to swap apiKey/endpoint).