Installation

JavaScript

Your personal tracking pixel

You can find your personal tracking pixel on your Workspace's settings page.

Learn the basics of installing Spectacle with JavaScript

To properly install Spectacle, you need to add Spectacle's code to your website, app, or server. This code will help track user interactions and generate insights based on the specific triggers you define.

For a basic setup, you can use a JavaScript snippet that you insert into the HTML of your website to monitor page views. Spectacle also supports installation through various platforms such as Segment, HubSpot, Shopify, Google Tag Manager, or WordPress, offering integrations for different needs.

The best way to understand how Spectacle works is by seeing it in action. This guide will walk you through a basic client-side installation of Spectacle.

Before you begin

First, consider your user journey or conversion funnel. A typical funnel might start with a click on an ad, leading to a landing page, and finally a conversion event. For example:

  • Visitor clicks an ad and is redirected to www.example.com?utm_source=adplatform
  • Visitor lands on www.example.com?utm_source=adplatform and submits a form with their information.

Once the snippet is placed, Spectacle will use the referring and destination domains to assign credit to specific channels and filters on the dashboard. Below, you'll learn more about the spectacle.js script and the components necessary for tracking with Spectacle.

Install the snippet and call page() to start tracking visits

  1. Copy your Spectacle snippet from your Workspace's settings page.
  2. Paste the snippet into the <head> tag of every page on your site. Ensure that all pages are on the same domain.

Assuming all pages are on the same domain, the snippet will load spectacle.js asynchronously, ensuring it does not impact your page load speed. Once the snippet is live, visits will start being recorded.

Note:
spectacle.js records the referring and destination domains of each visit. For example, the referring domain might be www.google.com, and the destination domain could be www.your-site.com?utm_source=adplatform. Spectacle will use these values to filter visits on the dashboard and attribute credit to your ad campaigns.

Call identify() to recognize your users

The identify() method allows you to tell Spectacle who the current user is, including a unique User id and any optional traits you know about them. While calling identify() is not required, it is highly recommended. It lets you easily assign User Iss, names, and emails to your visitors.

You don't need to call identify() for anonymous visitors; Spectacle will automatically assign them an anonymousId. Just calling page() and track() is sufficient if you don't capture personal information. However, using identify() is highly recommended when you do have such data, as it enables tracking across different devices.

Note:
Identifying visitors with an email trait is necessary for some of our integrations like Stripe and soon others.

Here’s an example of a basic identify() call:

spectacle.identify('uniqueUserId', {
  name: 'John Doe',
  email: 'john.doe@example.com'
});

This identifies John Doe by his unique User ID (uniqueUserId) and adds name and email traits.

If you don't have a unique User ID, you can use the email as a tracking ID:

spectacle.identify({
  name: 'John Doe',
  email: 'john.doe@example.com'
});

Replace the hard-coded trait values with variables representing the current user's details.

We recommend injecting an identify() call via a backend template after the Spectacle snippet (for example, in the footer) on every page where the user is logged in. This ensures the user is always identified regardless of the page they first land on.

Depending on your templating language, the identify() call might look like this:

spectacle.identify('{{user.id}}', {
  name: '{{user.fullname}}',
  email: '{{user.email}}'
});

With this call in your page footer, every user visiting your site will be successfully identified.

Remember, you don’t need to call identify() if you don't have user information (e.g., User Idand/or email are not available).

Call track() to record events and build your model

The track() method allows you to log conversion events that Spectacle can use to measure the effectiveness of your campaigns. You can track specific conversion events like "Trial Started" or "Demo Requested" to evaluate ad performance at different stages of your funnel. Revenue conversion events like "Order Paid" or "Subscription Payment" are also trackable, allowing revenue to be included in your model.

Here’s an example of a track() call for when a user starts a trial:

spectacle.track('Trial Started', {
  plan: 'Pro'
});

This tells Spectacle that a visitor has triggered the "Trial Started" event and selected the "Pro" plan.

In Spectacle, you can filter conversion events by properties like these. For instance, you can view the return on ad spend (ROAS) for Facebook ads on users who started a trial specifically for the Pro plan.

Revenue events are treated uniquely. Any time a track() event includes a revenue property, it will be used in Spectacle's calculations and models.

For example, if a revenue of 22 is passed in a track() event, Spectacle will use it to calculate ROAS on your dashboard:

spectacle.track('Customer Charged', {
  revenue: '22',
  plan: 'Pro'
});

To account for refunds or returns, you can also pass a negative revenue value:

spectacle.track('Refund Processed', {
  revenue: '-22',
  plan: 'Pro'
});

To start, we recommend tracking just a few critical events—you can always add more later!

Once you've implemented page(), identify(), and track(), you've completed Spectacle's tracking installation. The next steps involve connecting ad platforms and filtering visits.

If you have any questions, please reach out to support at support@spectaclehq.com.

Previous
Core concepts
Next
Segment