A powerful JavaScript library for integrating Teacup analytics and data management capabilities into your web applications. Track user interactions, page views, form completions, and seamlessly connect to the Teacup backend.
- 📊 Analytics Tracking: Automatic tracking of button clicks, page views, and form interactions
- 🎯 Smart Form Tracking: Track form completion percentage in real-time
- 📈 Page Scroll Tracking: Monitor how far users scroll on each page
- 🔒 Fingerprinting: Unique visitor identification using canvas fingerprinting
- 🚀 Easy Integration: Simple initialization and automatic data synchronization
- 📦 Lightweight: Minimal dependencies, optimized for performance
npm install teacupwebimport teacup from 'teacupweb';
// Initialize with your credentials
const client = teacup('YOUR_CLIENT_ID', 'YOUR_CLIENT_KEY');
if (client.error) {
console.error(client.message);
} else {
console.log('Teacup initialized successfully!');
}import teacup from 'teacupweb';
const client = teacup('YOUR_CLIENT_ID', 'YOUR_CLIENT_KEY');
// Start tracking analytics
client.analytics.track();That's it! The library will now automatically track:
- Button clicks
- Page navigation and scroll depth
- Form completion percentages
Initializes the Teacup library with your credentials.
Parameters:
clientID(string): Your unique client identifierclientKey(string): Your secret client key
Returns:
- On success: Object with
analyticsanddatacontrollers - On failure: Object with
errorandmessageproperties
Example:
const client = teacup('123', 'secretKey456');Starts automatic tracking of user interactions including:
- Button Clicks: Tracks every button click with the button text and page location
- Page Views: Tracks page navigation and scroll depth percentage
- Form Interactions: Monitors form completion percentage
Example:
client.analytics.track();Data Collection:
- Automatically sends analytics data to the server every 5 seconds
- Uses canvas fingerprinting for unique visitor identification
- Tracks only the highest scroll percentage per page (no duplicates)
- Tracks only the highest form completion percentage per form
Retrieves all blogs associated with your client account.
Returns: Promise resolving to an array of blog objects
Example:
const blogs = await client.data.getBlogs();
console.log(blogs);Retrieves a specific blog by its ID.
Parameters:
blogId(string): The unique identifier of the blog
Returns: Promise resolving to a blog object
Example:
const blog = await client.data.getBlog('blog123');
console.log(blog);Posts data to a specific inbox.
Parameters:
inboxId(string): The unique identifier of the inboxdata(object): The data to be posted
Returns: Promise resolving to the server response
Example:
const response = await client.data.postData('inbox123', {
name: 'John Doe',
email: 'john@example.com',
message: 'Hello!',
});Tracks all button clicks automatically:
// Captured data format:
{
button: "Submit", // Button text
page: "/contact" // Current page path
}Monitors page navigation and scroll depth:
// Captured data format:
{
page: "/about",
percentage: 75 // Highest scroll depth reached (0-100)
}Note: Only the highest scroll percentage is stored for each page visit.
Tracks form completion in real-time:
// Captured data format:
{
form: "Contact Us", // From data-form-name attribute or preceding H1-H3 heading
percent: 66.7 // Percentage of filled fields
}Form Naming:
- Use
data-form-nameattribute on your form element - Or place an
<h1>,<h2>, or<h3>heading before the form - Fallback: "unknown-form"
Example:
<!-- Option 1: Using data-form-name -->
<form data-form-name="Newsletter Signup">
<input type="email" name="email" />
<button type="submit">Subscribe</button>
</form>
<!-- Option 2: Using heading -->
<h2>Contact Us</h2>
<form>
<input type="text" name="name" />
<input type="email" name="email" />
<textarea name="message"></textarea>
<button type="submit">Send</button>
</form>If you want more control over tracking:
import teacup from 'teacupweb';
const client = teacup('YOUR_CLIENT_ID', 'YOUR_CLIENT_KEY');
// Enable only specific tracking
// Note: This requires manual implementation
// The track() method enables all tracking automaticallyThe library works seamlessly with modern frameworks:
// React example
import { useEffect } from 'react';
import teacup from 'teacupweb';
function App() {
useEffect(() => {
const client = teacup(
process.env.REACT_APP_CLIENT_ID,
process.env.REACT_APP_CLIENT_KEY
);
if (!client.error) {
client.analytics.track();
}
}, []);
return <div>Your App</div>;
}Analytics data is automatically sent to the Teacup backend:
- Interval: Every 5 seconds
- Endpoint:
https://backend.teacup.website/api/analytics - Included: Fingerprint, client credentials, and collected analytics data
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
Note: This library uses ES modules and requires a modern browser or build tool.
- Credentials: Store your
clientIDandclientKeysecurely - Environment Variables: Use environment variables for credentials in production
- HTTPS: The library communicates with the backend over HTTPS
Example .env file:
TEACUP_CLIENT_ID=your_client_id
TEACUP_CLIENT_KEY=your_client_keyMake sure you've called client.analytics.track() after initialization:
const client = teacup('CLIENT_ID', 'CLIENT_KEY');
client.analytics.track(); // Don't forget this!Verify your clientID and clientKey are correct:
const client = teacup('CLIENT_ID', 'CLIENT_KEY');
if (client.error) {
console.error('Initialization failed:', client.message);
}- Check browser console for errors
- Verify network requests are being sent to the backend
- Confirm your credentials have the correct permissions
For issues, questions, or feature requests:
- GitHub Issues: https://github.com/teacupweb/teacup-lib/issues
- Repository: https://github.com/teacupweb/teacup-lib
- Website: https://teacup.website
ISC © Tahmid Jihan, Teacup
See CHANGELOG.md for version history and updates.