@alexpodify/browser-sdk

@alexpodify/browser-sdk

Privacy-first browser tracker for public interaction events — page/listing views, declarative clicks, Telegram links and forms — that stream to a BotCiu backend (POST /api/public/events). Works in WordPress, React, Vue, Next, Nuxt and plain HTML.

• Zero runtime dependencies, TypeScript, ESM + CJS + types + an auto-init IIFE bundle (~8 KB min).
• No fingerprinting, no cookies, no PII, no form values. Only an allow-list of attribution params leaves the page; the backend sanitizer + producer-trust policy are the final authority.
• The public site token is only ever sent in the Authorization header (never a URL).

Install

npm install @alexpodify/browser-sdk

Or use the auto bundle via a <script> tag (see below).

Quick start (module API)

import { createTracker } from '@alexpodify/browser-sdk';

const tracker = createTracker({
  endpoint: 'https://your-backend/api/public/events',
  siteToken: 'bt_site_...',                 // public token from the BotCiu Integration Registry
  context: { external_type: 'hp_listing', external_id: '1905' },
  settings: { consentMode: 'always' },      // 'always' | 'after_consent' | 'disabled'
});

tracker.startAuto();                        // page.viewed (+ listing.viewed) + auto click/telegram/form
tracker.track('button.clicked', { data: { action: 'contact_owner' } });

Quick start (script tag / auto)

<script>
  window.BotCiuConfig = {
    endpoint: 'https://your-backend/api/public/events',
    siteToken: 'bt_site_...',
    context: { external_type: 'hp_listing', external_id: '1905' }
  };
</script>
<script src="https://unpkg.com/@alexpodify/browser-sdk/dist/botciu-tracker.global.js"></script>
<!-- window.BotCiuTracker.track('button.clicked', { data: { action: 'buy' } }) -->

This is exactly what the BotCiu WordPress plugin ships — the plugin injects window.BotCiuConfig and loads this same bundle.

Public API

The env parameter injects { fetch, storage, now, win, doc, crypto } — used for testing and non-DOM runtimes; it defaults to the browser globals.

Events & payloads

Only these six types are ever emitted; the DOM cannot produce anything else (sale.*, payment.*, lead.qualified, classification, subject_id, project_id are impossible client-side, and rejected server-side too):

page.viewed · listing.viewed · button.clicked · telegram.link_opened · form.started · form.submitted

Declarative click / Telegram tracking needs no JS:

<a href="https://github.com/Gdymora/botciu-browser-sdk/blob/HEAD/contact"
   data-botciu-event="button.clicked"
   data-botciu-action="contact_owner"
   data-botciu-label="Contact owner">Contact owner</a>
<a href="https://t.me/mychannel">Telegram</a>

Forms send metadata only (form_id, form_name, form_type, action_path) — never field values, emails, phones, nonces or FormData. form.submitted is not a trusted lead.created.

Identity, consent, attribution

• visitor_id (btv_…, localStorage) is stable; session_id (bts_…) rotates after 30 min of inactivity. Both opaque, no PII.
• Consent: in after_consent mode nothing is stored or sent until grant() or a botciu:consent-granted DOM event.
• Attribution allow-list: utm_source/medium/campaign/term/content, gclid/gbraid/wbraid/fbclid, fbp/fbc (Meta Pixel cookies — the deduplication key for Conversions API), referrer, landing_url (first landing captured once).

Telegram deep links

A visitor who clicks through to a bot normally arrives anonymous — the session, the article and the ad click id are all lost at the boundary. Attach the token instead:

// one link
el.href = tracker.telegramLink('mybot', '1905');

// or rewrite every t.me link already on the page
tracker.decorateTelegramLinks({ bot: 'mybot' });

Produces https://t.me/mybot?start=v1-<visitor>-p1905. The format is byte-identical to the one the WordPress connector emits, because the same backend parser reads both. Telegram limits start to 64 chars of [A-Za-z0-9_-]; a token that would break either rule is dropped and the plain bot link is returned, so the button always works.

Frameworks

See examples/: vanilla (script tag), react (useBotCiu hook), vue (composable), next (App Router client provider), nuxt (client plugin). For SPA navigation dispatch window.dispatchEvent(new Event('botciu:navigation')) after a route change to fire a fresh page.viewed.

Not in scope

Analytics dashboards, CRM, fingerprinting, cross-device identity, offline conversions.

License

MIT