Spectacle tag
Updated Sep 28, 2026
Spectacle tag by Stape is a custom Google Tag Manager (GTM) server-side template designed to send tracking data directly from a server container to the Spectacle API.
With the Spectacle tag you can:
- Use core Spectacle tracking methods – the tag supports the tracking methods such as page(), identify(), track() and group().
- Manage cookies and identity – automatically manage cookies
sp__anon_id(Spectacle Anonymous ID) andsp__user_id - Extract context – automatically pull context from event data and incoming HTTP request headers: User-Agent, Page URL, Referrer URL, Campaign UTMs, Timezone and Locale.
- Control consent – the tag supports built-in
ad_storageconsent check to respect user consent before firing.
Before you begin
To complete this setup, you will need to create a sGTM container and send data from the web to the sGTM container. You will also need an active Spectacle account and obtain Spectacle Workspace ID. You can find your Workspace ID on your Workspace's settings page, it should start with ws_
How to set up Spectacle tag
1. Go to the Google Tag Manager and open your server container.
2. Go to Templates, and under Tag Templates, click Search Gallery.
3. Search for Spectacle Tag.
4. Click Add to workspace and confirm.
5. Go to Tags and click New.
6. Click Tag Configuration and select Spectacle tag.
7. Enter your Spectacle Workspace ID.
8. Select tracking Method Type. All method types automatically inherit contextual data (User-Agent, Campaign UTMs, Timezone, Locale) and maintain cross-session identity through the sp__anon_id first-party cookie.
- Page – automatically extracts page details from incoming event data, including page URL, path, query string, title and referrer. It also parses
screen_resolutioninto screenwidthandheight. Use this on standard page load and page view events. - Identify – binds an anonymous visitor to an identified user profile and stores user-level traits. This tracking method assigns a unique identifier for the customer. Use this when a user signs up, logs in, or submits contact information.
User Data
Enter the following fields:
- User ID – the unique identifier for the customer. When passed, the tag saves this value in the first-party cookie
sp__user_iduserIduser_iduser_datauser_data.email_addresssp__user_id - Do not save User Email in User ID cookie – email addresses are Personally Identifiable Information (PII). Storing raw emails in browser cookies exposes PII in client-side storage, which can conflict with data protection policies (for example, GDPR, CCPA) or security audits. Check this option to prevent the tag from writing an email address into the
sp__user_idsp__user_id - Email – enter a variable for the email address. The tag first checks the incoming sGTM event data for
user_data.email_addressuser_data.email_addressuser_properties.email - First name – enter a variable for the first name. The tag first checks the incoming sGTM event data for
user_data.first_nameuser_data.first_nameuser_properties.first_name - Last name – enter a variable for the last name. The tag first checks the incoming sGTM event data for
user_data.last_nameuser_data.last_nameuser_properties.last_name - Phone Number – enter a variable for the phone number. The tag first checks the incoming sGTM event data for
user_data.phone_numberuser_data.phone_numberuser_properties.phone_number - Additional User Traits – click Add Trait to pass any custom business data you want associated with that user profile in Spectacle (for example,
plan_namesignup_date
- Track – records actions, milestones, and behaviors performed by the user. Use this on user interactions, e-commerce actions, or conversion triggers.
Event Data
Enter the following fields:
- Event Name – required. The identifier of the user action or conversion event being sent to the Spectacle API. You can type a static event name (for example,
PurchaseForm Submission{{Event Name}}event_name
Warning:
- Revenue (in cents) – enter a variable for monetary value in cents.
- Currency – three-letter ISO code (for example,
USD). - Event Properties – click Add Property to add custom key-value pairs specific to that action (for example,
order_iditemsplan_type
- Group – links an identified user to a specific organization, team, or account (commonly used in B2B / SaaS models). Use this when a user registers a company, switches workspaces, or joins an existing organization.
Group Data
Enter the following fields:
- Group ID – required. The unique identifier for a business account, company, organization, or workspace, where a user is linked to that organization. You can enter a static ID string if the tag fires exclusively for a specific single account context. Or you can insert a variable like
eventData.company_id - Group traits – click Add Trait to pass organizational metadata (for example,
company_nameplan_tierindustry
9. If you set Use Optimistic Scenario to true, the tag will call gtmOnSuccess() without waiting for a response from the API. This will speed up sGTM response time however your tag will always return the status fired successfully even if it isn’t.
10. In Advanced Configuration you can define the following:
- API Base URL – define the endpoint destination where the tag sends tracked event requests. You can route Spectacle tracking data through a custom sub-domain or proxy to avoid ad-blockers and keep network requests strictly first-party. If left blank, the tag sends HTTP POST requests to Spectacle's standard default endpoint. For standard setups, leave this field as is.
- Cookie Domain – define which domains and subdomains have access to read and write to the
sp__anon_idandsp__user_idfirst-party cookies. If your user journey crosses multiple subdomains (for example, browsing onwww.example.com, logging in atapp.example.com, and purchasing oncheckout.example.com), setting the cookie domain to the parent domain (example.com) ensures that identifiers (likesp__anon_idorsp__user_id) persist across the entire journey.
11. In Tag Execution Consent Settings you can control whether a tag fires and sends HTTP request data based on the user's consent status:
- Send data always – the tag fires and sends data to the API on every trigger, regardless of whether consent was granted or denied.
- Send data in case marketing consent given – the tag safely aborts firing if
ad_storageconsent (Google Consent Mode or Stape's Data Tag parameter) isn’t granted.
12. Select a trigger such as Page View.
13. Click Save.
Testing
1. In GTM, open the Preview mode and do some actions on your site to trigger the events. Confirm that the tag is firing.
2. In the Spectacle account, go to Settings → Tracking data and confirm that events are flowing.
Was this article helpful?
Comments