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 and YOUR_PROJECT_NAME with a project you created on SaasHound.

<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:

<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:

<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:

<script>
  window.saasHound.identify({
    userId: 'naomi-nagata',
    properties: {
      name: 'Naomi Nagata',
      email: '[email protected]',
      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:

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:

<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:

<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:

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:

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:

window.saasHound.identify({
  userId: 'naomi-nagata',
  properties: {
    name: 'Naomi Nagata',
    email: '[email protected]',
    role: 'Chief Engineer',
  },
})

Full Example

Here’s everything together in one example:

// 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: '[email protected]',
    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.