Install Tracking on Your Website

How do you install Perspection via Google Tag Manager?

The Perspection GTM integration uses a single Custom HTML tag that wraps window.dataLayer.push() to intercept all GTM events, loads the SDK asynchronously, fires an automatic page view, and flushes queued events. Configure with the "Initialization - All Pages" trigger. One Custom HTML tag replaces separate page view, purchase, and contact extraction tags.

Google Tag Manager is the preferred installation method for marketing teams that manage tracking through a tag management interface rather than direct code access.

Step-by-step: GTM installation

1. Open Google Tag Manager and navigate to the website container.

2. Click Tags in the left sidebar.

3. Click the New button to create a new tag.

4. Click Tag Configuration and select Custom HTML.

5. Name the tag Perspection Analytics.

6. Return to the Perspection dashboard, navigate to Connectors > Sources > Google Tag Manager, and click Copy GTM Tag Code.

7. Paste the copied code into the HTML field in the GTM Custom HTML tag configuration.

8. Click the Triggering section and select Initialization - All Pages (recommended for fastest loading, as the Initialization trigger fires before All Pages and other tag triggers).

9. Click Save to save the tag configuration.

10. Click Preview in the top-right corner of GTM to open Tag Assistant.

11. Enter the website URL and click Connect to test the tag in preview mode.

12. Verify that "Perspection Analytics" appears under "Tags Fired" on the Initialization event.

13. Open the browser console (F12) and confirm the message [Perspection] SDK initialized appears.

14. Return to GTM and click Submit in the top-right corner.

15. Add a version name (for example, "Added Perspection Analytics") and click Publish.

How the GTM tag works internally

The Perspection GTM tag executes the following sequence when the Custom HTML tag fires:

1. The tag wraps window.dataLayer.push() with a monitoring function that intercepts every dataLayer.push() call and extracts objects containing an event property.

2. Events pushed to the dataLayer before the SDK loads are queued in an in-memory pendingEvents array.

3. The tag dynamically creates a <script> element, sets the src attribute to the SDK URL (for example, https://ingest.perspection.app/sdk.js), marks the script as async, and appends the script to document.head.

4. On script load, the tag calls window.perspection.init() with the workspace tenant_id, endpoint, apiKey, and installationSource: 'gtm'.

5. The tag fires a page_view event with window.location.pathname, document.title, and document.referrer.

6. The tag iterates through pendingEvents, sending each queued event to Perspection, then clears the queue.

Important: Trigger configuration

Do NOT use a Click trigger (such as "All Clicks" or "Just Links") for the Perspection tag. Click triggers cause Cannot parse target errors in GTM because the Custom HTML tag expects a DOM context that does not exist on click events. Always use a page-based trigger: Initialization - All Pages or All Pages.

Automatic dataLayer monitoring

Because the Perspection GTM tag wraps window.dataLayer.push(), any event pushed to the dataLayer by other tags, plugins, or the website code is automatically captured and forwarded to Perspection. No manual GTM variable mapping or additional trigger configuration is required.

// Events pushed to dataLayer are automatically captured by Perspection
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  'event': 'custom_event',
  'eventCategory': 'User Action',
  'eventAction': 'Button Click',
  'eventLabel': 'Sign Up'
});

// Events pushed to dataLayer are automatically captured by Perspection
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  'event': 'custom_event',
  'eventCategory': 'User Action',
  'eventAction': 'Button Click',
  'eventLabel': 'Sign Up'
});

// Events pushed to dataLayer are automatically captured by Perspection
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  'event': 'custom_event',
  'eventCategory': 'User Action',
  'eventAction': 'Button Click',
  'eventLabel': 'Sign Up'
});

The Perspection SDK intercepts the push, extracts the event name and parameters, sends the event to the ingestion endpoint, and routes the event to configured advertising destinations (Meta CAPI, Google Ads, TikTok Events API).

How does Perspection hash PII on the client side?

Perspection uses the Web Crypto API to SHA-256 hash all PII within the browser before data leaves the client. The SDK normalizes emails to lowercase, phone numbers to E.164 format, and names to lowercase alphabetic characters. The resulting 64-character hex hash replaces raw PII in the event payload, so emails, phone numbers, and names never reach Perspection servers.

PII fields hashed client-side

The Perspection SDK applies SHA-256 hashing to 8 PII fields before transmission:

The SDK includes a pre-hash check using a regex pattern (/^[a-f0-9]{64}$/i) to detect values that are already hashed, preventing double-hashing when upstream systems have pre-hashed the data.

Enhanced Match Quality scoring

After hashing, the Perspection SDK calculates an Enhanced Match Quality (EMQ) score using a weighted formula. The scoring weights are:

• Email: 40 points

• Phone: 30 points

• First name: 5 points

• Last name: 5 points

• Zip code: 5 points

• City: 3 points

• Country: 3 points

• State: 2 points

The maximum possible score is 100. The _match_score and _match_keys_count values are attached to the event payload, enabling downstream ad platforms (Meta CAPI, Google Ads, TikTok) to perform higher-quality identity matching. For a deeper explanation of how match scoring affects ad platform conversion attribution, see Guide 16: Event Match Quality.

Why client-side hashing matters for compliance

Client-side hashing satisfies the GDPR principle of data minimization (Article 5(1)(c)) because raw PII never enters the Perspection data pipeline. The Perspection server receives only SHA-256 hashes, which are classified as pseudonymized data rather than personal data under most interpretations of GDPR Article 4(5). The hashing approach also satisfies the Shopify Protected Customer Data policy (enforced since December 2025), which restricts third-party pixel access to raw checkout fields.

How do you verify the Perspection SDK installation?

The Perspection dashboard provides three verification mechanisms: automated polling that checks for events every 5 seconds, a manual "Send Test Event" button that dispatches a synthetic event through the API, and a Live Event Stream view that displays events in real time via WebSocket. Verification completes when the first event arrives.

Step-by-step: Verify the installation

1. After pasting the SDK snippet (direct HTML) or publishing the GTM container, return to the Perspection dashboard.

2. The Verify Installation card appears automatically below the snippet code, displaying a spinning indicator and the message "Waiting for first event..."

3. Open the website in a new browser tab and navigate to any page. The SDK fires a page_view event automatically.

4. Return to the Perspection dashboard. The verification component polls the events count endpoint every 5 seconds. When the first event arrives, the status changes from "Waiting" to "Connected - Collecting Events" (amber badge) and then to "SDK Successfully Installed!" (green badge with event count).

5. Click View Live Events to open the analytics overview and see the full event stream in real time.

Using the Test Event Sender

The Perspection dashboard also includes a Send Test Event button that generates a synthetic event without requiring a visit to the website:

1. Click the Send Test Event button in the installation wizard.

2. The dashboard sends a POST request to /api/v1/events with the payload { event: 'test_event', properties: { _test: true, source: 'dashboard_test_sender', test_type: 'sdk_verification' } }.

3. A green confirmation message appears with the event ID if the event was accepted.

4. Test events are tagged with _test: true and can be filtered out of production analytics.

Troubleshooting verification failures

If events do not appear after 60 seconds:

1. Open the browser developer tools (F12) on the website and check the Console tab for [Perspection] log messages. If no Perspection messages appear, the SDK script is not loading.

2. Check the Network tab for blocked requests to ingest.perspection.app. Ad blockers and privacy extensions (uBlock Origin, Brave Shields, Safari ITP) can block third-party tracking scripts.

3. If an ad blocker is blocking the SDK, configure a first-party custom domain via CNAME (see Guide 24: First-Party Tracking Domain). A first-party domain routes the SDK script and all event requests through a subdomain of the website (for example, events.yourdomain.com), bypassing ad blocker domain lists and extending cookie persistence beyond Safari ITP 7-day limits.

4. For GTM installations, verify that the Perspection tag uses a page-based trigger (Initialization - All Pages or All Pages). Click-based triggers cause Cannot parse target errors.

5. If duplicate events appear, check for multiple installations of the Perspection snippet or an outdated GTM tag version. The current Perspection GTM tag handles dataLayer monitoring automatically -- manual event forwarding tags from previous versions should be removed.

Methodology

All SDK installation steps and configuration options in this guide were verified against the Perspection production dashboard and live SDK behavior as of February 2026. Code snippets reflect the actual output of the Perspection SDK snippet generator.

"The single most impactful optimization for SDK installation success rate is configuring a first-party tracking domain before deploying the snippet to production. Safari ITP caps third-party cookie lifetime at 7 days, and approximately 40% of global web traffic uses Safari. A CNAME-based first-party domain extends cookie persistence to the full domain lifetime, eliminates ad blocker interference, and increases event delivery rates from roughly 70% to over 95% of actual site visits. The Perspection SDK snippet generator automatically switches to first-party mode when a verified custom domain exists -- no code changes are required on the website after the initial domain configuration."

Sources & References

1. Perspection Help Center -- SDK Installation, https://perspection.app/library

2. Google Tag Manager -- Custom HTML Tag Guide, https://support.google.com/tagmanager/answer/6107167

3. Web Crypto API -- SubtleCrypto.digest(), https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest

4. Perspection Product Guide -- First-Party Tracking Domain, /library/first-party-tracking-domain-guide

5. Perspection Product Guide -- Event Match Quality, /library/event-match-quality-guide