Tap-Turtle 🐢

Tap-Turtle is a lightweight event-collection platform that tracks DOM snapshots, mouse movements, clicks, and scroll events on a web page. It batches these events and sends them to a backend server for analysis, similar to tools like PostHog. It's super easy to integrate into any React application!

Features

• DOM Snapshot on Load: Capture the initial DOM structure when the page loads.
• Mouse Movements: Track mouse movements on the page.
• Click Events: Record every click event with coordinates and the target element.
• Scroll Tracking: Monitor scroll events and capture the scroll position.
• Event Batching: Events are sent in batches every 5 seconds to reduce network overhead.
• Simple Integration: Just wrap your app with the TapTurtleProvider and provide your project key. No additional hooks needed!

Installation

You can install tap-turtle via npm:

npm install tap-turtle

or via Yarn:

yarn add tap-turtle

Usage

Integrating tap-turtle into your React app is simple! Just wrap your app with the TapTurtleProvider and pass in your projectKey.

Example

import React from "react";
import { TapTurtleProvider } from "tap-turtle";

const App: React.FC = () => {
  return (
    <TapTurtleProvider projectKey="YOUR_PROJECT_KEY">
      <div>Your Application Content</div>
    </TapTurtleProvider>
  );
};

export default App;

This will automatically:

• Capture the initial DOM snapshot on page load.
• Start collecting mouse movements, click events, and scroll events.
• Batch and send the collected events to your backend every 5 seconds.

Configuration

The only required prop is the projectKey, which will be used to identify different projects.

<TapTurtleProvider projectKey="YOUR_PROJECT_KEY">
  {/* Your app content */}
</TapTurtleProvider>

Backend Integration

The events are sent as a POST request to the endpoint http://localhost:5001/events/save. You can modify this endpoint in future releases to suit your backend requirements.

The payload contains the sessionId, a unique identifier for each session, and the list of events:

{
  "sessionId": "unique-session-id",
  "events": [
    {
      "type": "click",
      "x": 150,
      "y": 200,
      "target": "DIV",
      "timestamp": 1628512800000
    },
    {
      "type": "mousemove",
      "x": 300,
      "y": 400,
      "timestamp": 1628512805000
    },
    {
      "type": "scroll",
      "scrollX": 0,
      "scrollY": 500,
      "timestamp": 1628512810000
    }
  ]
}

Customization (Upcoming)

In future versions, the following features will be added:

• Custom event types (e.g., keypress, form submissions)
• Custom backend endpoints
• Configurable batch intervals

Development

If you'd like to contribute to tap-turtle or run the project locally, follow these steps:

1. Clone the repo:

git clone https://github.com/your-username/tap-turtle.git
cd tap-turtle

2. Install dependencies:

npm install

3. Build the package:

npm run build

4. Run the project in development mode:

npm start