# SaasHound Web SDK Guide

## What is SaasHound?

SaasHound is a tool that helps you track what users do on your website. You can track things like:

- Page views (when someone visits a page).
- Button clicks (when someone clicks a button).
- Form submissions (when someone fills out a form).
- Custom events (like when someone completes a mission or updates a metric).

## How to Install SaasHound

To use SaasHound, add this code to your HTML file. Replace `YOUR_TOKEN` with an api key from [SaasHound Token](https://app.saashound.co/settings/api-keys) and `YOUR_PROJECT_NAME` with a project you created on SaasHound.

```html
<script src="https://cdn.jsdelivr.net/npm/saashound-web/dist/saashound.js"></script>
<script>
  window.onload = function () {
    window.initSaasHound({
      token: 'YOUR_TOKEN',
      project: 'YOUR_PROJECT_NAME',
      trackPageViews: true,
    })
    console.log('SaasHound is ready!')
  }
</script>
```

> **Tip:** Make sure your token is set to "Public" and only works for the project you’re tracking.

---

## Setting the User ID

Before SaasHound can track events, you need to tell it who the user is. Use this code to set a user ID:

```html
<script>
  window.saasHound.setUserId('naomi-nagata')
</script>
```

You can use anything to identify the user, like their email or username.

---

## Tracking Events

You can track events by adding a `data-event` attribute to any HTML element. For example, here’s how to track when a user completes a mission:

```html
<div
  data-event="Alien Encounter"
  data-user-id="naomi-nagata"
  data-channel="exploration"
  data-icon="👽"
  data-description="First contact with aliens!"
  data-tag-species="Unknown"
  data-tag-location="Sol gate"
  data-tag-communication="Successful"
>
  👽 Alien Encounter Logged
</div>
```

### Extra Details for Events

You can add more information to your events using these attributes:

- **data-user-id**: (Optional) The user’s ID. Skip this if you’ve already set it.
- **data-channel**: (Optional) The part of your app this event belongs to. Default is `"events"`.
- **data-icon**: (Optional) An emoji or icon to show with the event.
- **data-tags**: Add extra details like `data-tag-mission`, `data-tag-location`, etc.

---

## Adding User Details

You can tell SaasHound more about your users. This helps with tracking. Here’s an example:

```html
<script>
  window.saasHound.identify({
    userId: 'naomi-nagata',
    properties: {
      name: 'Naomi Nagata',
      email: 'naomi@roci.com',
      role: 'Chief Engineer',
    },
  })
</script>
```

---

## Tracking Page Views

SaasHound automatically tracks when users visit different pages on your website. To enable this, set `trackPageViews` to `true` when creating the SaasHound instance.

Example:

```javascript
window.onload = function () {
  window.initSaasHound({
    token: 'YOUR_TOKEN',
    project: 'YOUR_PROJECT_NAME',
    trackPageViews: true,
  })
  console.log('SaasHound is ready and tracking page views!')
}
```

---

## Tracking Button Clicks

You can track when users click buttons or other elements. Add a `data-event` attribute to the element you want to track:

```html
<button data-event="Mission Complete" data-channel="operations" data-icon="🚀">
  Complete Mission
</button>
```

### What Do These Attributes Mean?

- **data-event**: The name of the event (e.g., "Mission Complete").
- **data-channel**: The category of the event (e.g., "operations").
- **data-icon**: An emoji or icon to show for the event.

---

## Tracking Form Submissions

You can track when users submit forms. Add a `data-event` attribute to the form:

```html
<form data-event="Contact Form Submitted" data-channel="support" data-icon="📨">
  <input type="text" name="name" placeholder="Your Name" />
  <input type="email" name="email" placeholder="Your Email" />
  <button type="submit">Submit</button>
</form>
```

### What Do These Attributes Mean?

- **data-event**: The name of the event (e.g., "Contact Form Submitted").
- **data-channel**: The category of the event (e.g., "support").
- **data-icon**: An emoji or icon to show for the event.

---

## Tracking Custom Events

You can track custom events using the `logEvent` method. For example, to track when a user completes a mission:

```javascript
window.saasHound.logEvent({
  channel: 'operations',
  title: 'Mission Complete',
  message: 'The user completed the mission successfully.',
  icon: '🚀',
  tags: {
    mission: 'Exploration',
    location: 'Asteroid Belt',
  },
})
```

---

## Tracking Metrics

You can track numbers, like percentages or scores, using the `sendMetric` method. For example, to track oxygen levels:

```javascript
window.saasHound.sendMetric({
  title: 'Crew Count',
  value: 17,
  icon: '🌬️',
  increment: false, // Set to true if the value should increase
})
```

---

## Identifying Users

You can give SaasHound more details about your users. This helps with tracking. Use the `identify` method:

```javascript
window.saasHound.identify({
  userId: 'naomi-nagata',
  properties: {
    name: 'Naomi Nagata',
    email: 'naomi@roci.com',
    role: 'Chief Engineer',
  },
})
```

---

## Full Example

Here’s everything together in one example:

```javascript
// Initialize SaasHound
const saasHound = new SaasHound({
  token: 'YOUR_TOKEN',
  project: 'YOUR_PROJECT_NAME',
  trackPageViews: true,
})

// Set the user ID
saasHound.setUserId('naomi-nagata')

// Identify the user
saasHound.identify({
  userId: 'naomi-nagata',
  properties: {
    name: 'Naomi Nagata',
    email: 'naomi@roci.com',
    role: 'Chief Engineer',
  },
})

// Track a custom event
saasHound.logEvent({
  channel: 'operations',
  title: 'Mission Complete',
  message: 'The user completed the mission successfully.',
  icon: '🚀',
  tags: {
    mission: 'Exploration',
    location: 'Asteroid Belt',
  },
})

// Track a metric
saasHound.sendMetric({
  title: 'Crew Count',
  value: 17,
  icon: '🌬️',
  increment: false,
})
```

---

## How It Works

### Sessions

- SaasHound creates a **session** when a user visits your website.
- The session ends if the user is inactive for 30 minutes or closes the tab.
- You can manually end a session using the `endSession` method.

### Heartbeats

- SaasHound sends a **heartbeat** every 5 minutes to keep the session alive.
- If the user is inactive for too long, the session ends automatically.

### Offline Tracking

- If the user goes offline, SaasHound saves the tracking data locally.
- When the user comes back online, the data is sent to the server.

---

## Methods

### `setUserId(userId: string)`

- Sets the user ID for tracking.

### `clearUserId()`

- Removes the user ID.

### `logEvent(eventData: CaptureParams)`

- Logs a custom event.

### `sendMetric(metricData: MetricParams)`

- Sends a metric (like a number or percentage).

### `identify(identifyData: IdentifyParams)`

- Adds more details about the user.

### `endSession()`

- Ends the current session.

---