Installation

Google Tag Manager (GTM) - Web or Server-Side

Your Workspace Id

You can find your Workspace Id on your Workspace's settings page. It should start with "ws_".

Installing Spectacle with Google Tag Manager

The Spectacle GTM template provides a complete analytics integration without requiring manual code implementation. You can track page views, identify users, record events, and link users to organizations through Google Tag Manager's interface.

Before you begin

  1. Get your Workspace Id: Find your Workspace Id on your Workspace's settings page
  2. Access to GTM: Ensure you have admin access to your Google Tag Manager container
  3. Plan your tracking: Consider what events you want to track and when they should fire

Step 1: Import the Spectacle GTM Template

  1. Download the Spectace GTM template: Web or Server-side
  2. In Google Tag Manager, go to Templates in the left sidebar
  3. Click New
  4. Click the three dots in the top right corner
  5. Click Import
  6. Select the template.tpl you just downloaded
  7. Click Save

Step 2: Create a Spectacle Tag

  1. Go to Tags and click New
  2. Click Tag Configuration and select Spectacle from the Custom templates section
  3. Configure your tag based on your tracking needs:

Required Configuration

  • Workspace Id: Enter your Workspace Id (starts with "ws_")
  • Spectacle Method: Choose from four tracking methods:
    • Page: Track page views (recommended for most sites)
    • Identify: Identify users with traits
    • Track: Track custom events
    • Group: Associate users with organizations

Method-Specific Configuration

Page Method (Automatic Page Tracking)

  • Enable Lens: When enabled, Spectacle will forego automatic anonymization of the visitor IP address, so the full IP address can be used by Spectacle Lens to identify the company details of anonymous visitors.
Advanced Options
  • Auto Track Forms: Automatically track form submissions as Identify events (when an email is found in form data) and as Track events. This option is enabled by default.

Identify Method (User Identification)

  • User Id (required if no Email): Unique identifier for the user
  • Email (required if no User Id): User's email address
  • First Name: User's first name
  • Last Name: User's last name
  • User Traits: Additional custom properties (key-value pairs)

Track Method (Custom Event Tracking)

  • Event Name (required): Name of the event (e.g., "Trial Started", "Form Submitted")
  • Use GA4 Ecom data (required): Use GA4 ecommerce data for revenue for "purchase" and "refund" events. N.b. it is important that the event name sent to spectacle matches the event names used in GA4 ("purchase" and "refund").
  • Revenue format (required): Major units (e.g., $199.99) or cents (e.g., 19999)
  • Revenue: The revenue associated with this event in major units or cents, depending on the revenue format setting.
  • transactionId A unique transaction id. Used for de-duplication of events with revenue. If no transaction id is provided, Spectacle automatically uses a combination of the visitor id and timestamp as the transactionId. For refunds, make sure to use a different transactionId than the original transaction id being refunded.
  • Currency: The three letter currency code (e.g., "EUR" or "USD")
  • Event Properties: Custom event data (key-value pairs)

Group Method (Organization Association)

  • Group Id (required): Unique identifier for the organization
  • Group Traits: Organization properties (key-value pairs)

Step 3: Configure Triggers

Set up triggers to determine when your Spectacle tags should fire:

For Page Tracking

  • Trigger Type: Page View
  • Trigger Fires On: All Pages (or specific pages as needed)

For User Identification

  • Trigger Type: Custom Event or Page View
  • Trigger Fires On: When user data is available (e.g., after login)

For Event Tracking

  • Trigger Type: Click, Form Submission, Custom Event, etc.
  • Trigger Fires On: When the specific action occurs

For Group Association

  • Trigger Type: Custom Event or Page View
  • Trigger Fires On: When organization data is available

Step 4: Test Your Implementation

  1. Preview Mode: Use GTM's Preview mode to test your tags
  2. Debug Mode: Enable Debug Mode in the Spectacle tag to see console logs
  3. Check Firing: Verify that tags fire on the correct triggers
  4. Validate Data: Ensure the correct data is being sent to Spectacle

Step 5: Publish Your Changes

Once testing is complete:

  1. Click Submit in GTM
  2. Add a descriptive version name and description
  3. Click Publish to make your changes live

Common Use Cases

Basic Website Tracking

Create a tag with Method: Page and Trigger: All Pages

Lead Generation Tracking

Create a tag with Method: Track, Event Name: "Lead Generated", and appropriate form submission triggers

E-commerce Conversion Tracking

Create a tag with Method: Track, Event Name: "Purchase", include revenue and currency properties

User Identification After Login

Create a tag with Method: Identify, include User Id and email, trigger on login success

Revenue Tracking

For revenue events, include revenue and currency properties in your Track events. Spectacle will automatically use this data for ROAS calculations on your dashboard.

Troubleshooting

Tag Not Firing

  • Check trigger configuration
  • Verify trigger conditions are met
  • Use GTM Preview mode to debug

Data Not Appearing

  • Confirm Workspace Id is correct
  • Check browser console for errors (enable Debug Mode)
  • Verify network requests are being made

Next Steps

Once your GTM implementation is live:

  1. Monitor your Spectacle dashboard for incoming data
  2. Set up additional events as needed
  3. Configure attribution models and reporting preferences
Previous
Segment
Next
REST api