@engagex/react
v0.1.1
Published
React / Next.js wrapper for EngageX tracking. Loads engage.v1.js from your tracking host and gives you a typed <EngageProvider>, sendEngageEvent() and engageIdentify() with automatic SPA page-view tracking.
Maintainers
cdhung87Readme
@engagex/react
React / Next.js wrapper for EngageX tracking. It loads engage.v1.js from
your tracking host and gives you a typed <EngageProvider>, sendEngageEvent()
and engageIdentify() — with automatic page-view tracking across SPA route
changes.
Like
@next/third-parties, this package does not bundle the tracker — it injects the script from your host, so it auto-updates, keeps endpoint auto-detection, and shares the anonymous_cdp_tididentity with your landing pages / embedded forms.
Install
npm add @engagex/react
# or: pnpm add @engagex/reactNext.js (App Router)
// app/layout.tsx
import { EngageProvider } from '@engagex/react'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<EngageProvider publicKey="pk_live_xxx" />
{children}
</body>
</html>
)
}You only pass publicKey — the tracking host is baked in. page.viewed fires
automatically on every route change, no useEffect needed.
Self-hosting or local dev? Override the host:
<EngageProvider publicKey="pk_..." host="http://localhost:8010" />.
Send events / identify (any client component)
'use client'
import { sendEngageEvent, engageIdentify } from '@engagex/react'
// business / behavioural event
sendEngageEvent('order.placed', { order_id: 'DH1', total: 1990000, currency: 'VND' })
// identify — resolving key (phone/email/zalo_id, ≥1) + optional traits + consent
engageIdentify(
{ phone: '0912345678', name: 'Nguyễn Văn An', gender: 'male', birthday: '1990-12-31' },
{ consent: true, purpose: 'marketing' },
)- Traits are applied fill-missing (never overwrite existing profile data).
- Re-calling
identifywith the same phone updates, it does not create a duplicate. Identifying a different person rotates the anonymous id.
Plain React (Vite / CRA)
Same API. <EngageProvider> tracks route changes via the History API, so it
works with React Router too — no extra wiring.
API
| Export | Description |
| --- | --- |
| <EngageProvider publicKey host autoPageview? branchId? /> | Loads the SDK + auto page-view. Mount once at the root. |
| sendEngageEvent(event, properties?) | Forward a track call (SSR-safe). |
| engageIdentify(identity, consent?) | Forward an identify call (SSR-safe). |
<EngageProvider> props
| Prop | Type | Default | |
| --- | --- | --- | --- |
| publicKey | string | — | Source public key (pk_...). |
| host | string | (baked-in) | Tracking host serving engage.v1.js. Override only for self-hosting / local dev. |
| autoPageview | boolean | true | Auto-fire page.viewed on route change. |
| branchId | number \| string | — | Attached to every event. |
License
MIT