@heartbeep/beeper
Version:
Modern JavaScript SDK for Heartbeep event tracking - beep beep!
235 lines (169 loc) • 4.2 kB
Markdown
# @heartbeep/beeper 🔔
Modern JavaScript SDK for Heartbeep event tracking. Simple API, TypeScript support, React/Next.js ready. Beep beep!
## Installation
```bash
npm install @heartbeep/beeper
# or
pnpm add @heartbeep/beeper
# or
yarn add @heartbeep/beeper
```
## Quick Start
### Vanilla JavaScript/TypeScript
```typescript
import { Heartbeep } from "@heartbeep/beeper";
const heartbeep = new Heartbeep({
siteId: "your-site-id",
debug: true, // optional, logs events in development
});
// Track events
heartbeep.track("pageview");
heartbeep.track("click", { name: "Subscribe Button" });
heartbeep.track("purchase", {
name: "Premium Plan",
metadata: { value: 99.99, currency: "USD" },
});
// Convenience methods
heartbeep.pageview("Home Page");
heartbeep.click("Buy Now Button", { section: "hero" });
heartbeep.purchase("Pro Plan", { value: 49.99 });
```
### React
```tsx
import { HeartbeepProvider, useHeartbeep } from "@heartbeep/beeper/react";
// In your root component
function App() {
return (
<HeartbeepProvider siteId="your-site-id">
<YourApp />
</HeartbeepProvider>
);
}
// In any component
function Button() {
const { click } = useHeartbeep();
return (
<button onClick={() => click("CTA Button", { variant: "primary" })}>
Click Me
</button>
);
}
```
### Next.js App Router
For Next.js App Router, create a client component wrapper:
```tsx
// app/providers.tsx
"use client";
import { HeartbeepProvider, AutoPageview } from "@heartbeep/beeper/react";
export function Providers({ children }: { children: React.ReactNode }) {
return (
<HeartbeepProvider siteId="your-site-id">
<AutoPageview />
{children}
</HeartbeepProvider>
);
}
```
Then use it in your root layout:
```tsx
// app/layout.tsx
import { Providers } from "./providers";
export default function RootLayout({ children }) {
return (
<html>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
```
### Auto Page Tracking
```tsx
import { HeartbeepProvider, AutoPageview } from "@heartbeep/beeper/react";
function App() {
return (
<HeartbeepProvider siteId="your-site-id">
<AutoPageview />
<YourApp />
</HeartbeepProvider>
);
}
```
## API Reference
### `Heartbeep` Class
#### Constructor
```typescript
new Heartbeep(config: HeartbeepConfig)
```
**Config Options:**
- `siteId` (required): Your Heartbeep site ID
- `apiUrl` (optional): Custom API URL
- `debug` (optional): Enable debug logging
#### Methods
##### `track(event, payload?)`
Track a custom event.
```typescript
heartbeep.track("custom-event", {
name: "Event Name",
metadata: { key: "value" },
});
```
##### `pageview(name?)`
Track a page view.
```typescript
heartbeep.pageview("Home Page");
```
##### `click(name, metadata?)`
Track a click event.
```typescript
heartbeep.click("Buy Now Button", { section: "hero" });
```
##### `purchase(name, metadata?)`
Track a purchase event.
```typescript
heartbeep.purchase("Pro Plan", {
value: 49.99,
currency: "USD",
});
```
### React Hook
The `useHeartbeep()` hook provides access to all tracking methods:
```typescript
const { track, pageview, click, purchase, heartbeep } = useHeartbeep();
```
## TypeScript Support
Full TypeScript support with type definitions included:
```typescript
import type { HeartbeepConfig, TrackEventPayload } from "@heartbeep/beeper";
```
## Migration from Script Tag
Replace your script tag:
```html
<!-- Old -->
<script src="/beep.js" data-site-id="site_123"></script>
<script>
window.hb("click", "Button");
</script>
```
With the npm package:
```typescript
// New
import { Heartbeep } from "@heartbeep/beeper";
const heartbeep = new Heartbeep({ siteId: "site_123" });
heartbeep.click("Button");
```
## Fun Beep Function
For a bit of fun, we also export a `beep` function:
```typescript
import { beep } from "@heartbeep/beeper";
beep("click", "Fun Button"); // Logs: [Beeper] 🔔 click: Fun Button
```
## Browser Support
- Modern browsers with ES2020 support
- Server-side rendering safe
- Graceful degradation for older browsers
## License
MIT
---
Made with ❤️ by Heartbeep. Beep beep!