Set Up a First-Party Tracking Domain

How does Perspection CNAME-based first-party tracking work?

A DNS CNAME record maps a customer-owned subdomain to the Perspection ingestion endpoint. When the browser requests events.yourdomain.com, DNS resolves the CNAME to {id}.perspection.app. Because the Same-Origin Policy evaluates the URL hostname (not the resolved IP), the browser treats the request and cookies as first-party to yourdomain.com.

The CNAME resolution chain

The technical flow from browser to Perspection ingestion operates in 5 steps:

1. The Perspection SDK (installed per Install Tracking on Your Website) fires a tracking event to https://events.yourdomain.com/track.

2. The visitor's browser performs a DNS lookup for events.yourdomain.com.

3. The DNS resolver returns the CNAME record pointing to {id}.perspection.app.

4. The DNS resolver follows the CNAME to the Perspection infrastructure IP address.

5. The browser sends the HTTP request to the resolved IP with Host: events.yourdomain.com, and Perspection's Cloudflare edge routes the request to the ingestion server.

How the SDK snippet changes with a first-party domain

When a workspace has a verified first-party domain, the Perspection dashboard generates an SDK snippet that uses the serverContainerUrl parameter instead of the default endpoint parameter:

<!-- Perspection Analytics SDK (First-Party Domain) -->
<script src="https://events.yourdomain.com/sdk.js"></script>
<script>
  window.perspection && window.perspection.init({
    tenant: "{workspace-tenant-id}",
    serverContainerUrl: "https://events.yourdomain.com",
    apiKey: "{pk_publishable_key}",
    installationSource: "custom"
  });
</script>
<!-- End Perspection Code -->

<!-- Perspection Analytics SDK (First-Party Domain) -->
<script src="https://events.yourdomain.com/sdk.js"></script>
<script>
  window.perspection && window.perspection.init({
    tenant: "{workspace-tenant-id}",
    serverContainerUrl: "https://events.yourdomain.com",
    apiKey: "{pk_publishable_key}",
    installationSource: "custom"
  });
</script>
<!-- End Perspection Code -->

<!-- Perspection Analytics SDK (First-Party Domain) -->
<script src="https://events.yourdomain.com/sdk.js"></script>
<script>
  window.perspection && window.perspection.init({
    tenant: "{workspace-tenant-id}",
    serverContainerUrl: "https://events.yourdomain.com",
    apiKey: "{pk_publishable_key}",
    installationSource: "custom"
  });
</script>
<!-- End Perspection Code -->

Both the SDK script file (sdk.js) and all event payloads (/track, /v1/batch, /v1/identify) load through the first-party subdomain. The ad blocker sees only requests to yourdomain.com, and cookies set by the Perspection SDK inherit first-party storage classification.

Impact on Event Match Quality

A first-party domain directly improves Event Match Quality (EMQ) scores for Meta CAPI, Google Ads, and TikTok Events API by preserving the fbclid, gclid, and ttclid cookies across sessions. When Safari ITP expires the cookies after 7 days under third-party tracking, the click ID is lost, and the conversion event cannot be matched to the original ad click. A first-party domain prevents the click ID from expiring, boosting EMQ scores. For details on EMQ optimization, see Event Match Quality.

How do you set up automatic DNS provisioning in Perspection?

Automatic DNS provisioning creates the CNAME record through the DNS provider's API without requiring a separate login. Perspection detects the provider via nameserver lookup against 19 known providers. For 5 supported providers -- Cloudflare, AWS Route 53, GoDaddy, Namecheap, and Google Cloud DNS -- Perspection accepts API credentials transiently, creates the record, and discards the credentials immediately.

Prerequisites

Before starting, confirm the following:

1. A Perspection workspace exists (see Create Your Workspace if not).

2. The Perspection Web SDK is installed on the website (see Install Tracking on Your Website).

3. DNS API credentials are available for the DNS provider (see provider-specific requirements below).

4. The chosen subdomain is not already in use (common choices: events, track, data, t).

Step-by-step: Automatic DNS provisioning

1. Log in to the Perspection dashboard at dashboard.perspection.app.

2. Navigate to Connectors in the left sidebar, then select the Sources tab.

3. Select the First-Party tab within Sources.

4. Enter the desired subdomain in the domain input field (for example, events.yourdomain.com). Perspection requires a subdomain -- root domains are not supported.

5. Click Continue Setup. Perspection performs a nameserver lookup using Node.js native DNS with a fallback to Cloudflare DNS-over-HTTPS (1.1.1.1) to identify the DNS provider.

6. If Perspection detects a supported provider, a banner displays the provider name with an "Auto-setup available" badge. Select the Auto Setup tab.

7. Enter the DNS provider API credentials in the credential fields. Each provider requires different credentials:

8. Review the CNAME preview showing the Host value and Target value that Perspection will create.

9. Click Create DNS Record Automatically. Perspection validates the credentials against the provider API, creates the CNAME record with a TTL of 300 seconds, and then discards the credentials.

10. A "DNS Record Created" confirmation appears. Perspection begins polling DNS verification every 10 seconds for up to 30 attempts (5 minutes total).

Credential security

Perspection explicitly does not store, log, or persist DNS provider credentials. The credentials are passed to the API endpoint at POST /:workspaceId/dns/auto-provision, used in-memory to authenticate a single API call to the DNS provider, and then released from memory when the request completes. The Perspection UI displays a security notice confirming credentials are used once and immediately discarded.

Provider detection for unsupported providers

Perspection detects 19 DNS providers in total by matching nameserver hostname patterns. For the 14 providers without auto-provisioning support (Wix, Squarespace, Hostinger, Vercel, Netlify, DigitalOcean, OVH, Porkbun, Name.com, DNSimple, Bluehost, IONOS, Hover, and Linode/Akamai), Perspection displays the provider name, a direct link to the provider's DNS settings page, and step-by-step manual configuration instructions.

How do you manually configure a CNAME for Perspection?

Create a CNAME record in your DNS provider's dashboard with the subdomain as Host and the Perspection endpoint as Target. The dashboard displays both values with copy buttons. DNS propagation takes 2-10 minutes, and Perspection verifies the record automatically by polling every 10 seconds.

CNAME record values

The Perspection dashboard generates two values for the CNAME record:

• Host / Name: The subdomain prefix (for example, events for events.yourdomain.com, or track for track.yourdomain.com)

• Target / Points to: The workspace-specific endpoint in the format {shortId}.perspection.app (for example, a1b2c3d4.perspection.app)

Both values are displayed in the Perspection First-Party configuration UI with copy-to-clipboard buttons.

Step-by-step: Cloudflare manual setup

1. Log into the Cloudflare Dashboard at dash.cloudflare.com.

2. Select the domain.

3. Go to DNS > Records.

4. Click Add record.

5. Set Type to CNAME.

6. Set Name to the subdomain prefix (for example, events).

7. Set Target to the Perspection CNAME target value (for example, a1b2c3d4.perspection.app).

8. Set Proxy status to DNS only (grey cloud icon). The orange cloud (Proxied mode) interferes with SSL certificate provisioning and must be disabled.

9. Click Save.

Step-by-step: AWS Route 53 manual setup

1. Log into the AWS Console and navigate to Route 53 > Hosted zones.

2. Select the domain's hosted zone.

3. Click Create record.

4. Set Record name to the subdomain prefix (for example, events).

5. Set Record type to CNAME.

6. Set Value to the Perspection CNAME target value.

7. Set TTL to 300.

8. Click Create records.

Step-by-step: GoDaddy manual setup

1. Log into GoDaddy at dcc.godaddy.com/manage/dns.

2. Navigate to My Products > DNS > Manage Zones and select the domain.

3. Click Add in the DNS Records section.

4. Set Type to CNAME.

5. Set Host to the subdomain prefix.

6. Set Points to the Perspection CNAME target value.

7. Set TTL to 1 hour (or 600 seconds).

8. Click Save.

Step-by-step: Namecheap manual setup

1. Log into Namecheap and go to Domain List > Manage > Advanced DNS.

2. Click Add New Record.

3. Set Type to CNAME Record.

4. Set Host to the subdomain prefix.

5. Set Value to the Perspection CNAME target value.

6. Set TTL to Automatic.

7. Click the green checkmark to save.

DNS propagation and verification

After the CNAME record is saved at the DNS provider, DNS propagation takes 2-10 minutes depending on the provider and the TTL configuration. Perspection automatically polls the DNS record every 10 seconds, displaying a progress counter (for example, "12/30") in the dashboard. The maximum polling window is 30 attempts over 5 minutes. If verification times out, the dashboard displays a link to DNSChecker.org to confirm the CNAME has propagated globally, along with a manual Refresh button to restart verification.

Troubleshooting DNS verification failures

• CNAME not detected after 10 minutes: Verify the CNAME Host and Target values exactly match the values shown in the Perspection dashboard. Check for trailing dots, extra spaces, or incorrect subdomain prefixes.

• Cloudflare users: Confirm the Proxy status is set to "DNS only" (grey cloud). The orange Proxied cloud mode routes traffic through the Cloudflare CDN, which prevents Perspection from verifying ownership of the domain.

• High TTL values: Some providers default to TTL values of 3600 seconds (1 hour) or higher. Lowering the TTL to 300 seconds (5 minutes) accelerates propagation.

• DNSChecker.org verification: Enter the full subdomain (for example, events.yourdomain.com) at dnschecker.org/#CNAME to confirm the CNAME record resolves correctly from multiple global locations.

How does Perspection auto-provision SSL certificates?

After DNS verification, Perspection auto-provisions a domain-validated SSL certificate through Cloudflare for SaaS, issued by Let's Encrypt or Google Trust Services. The certificate progresses through 3 stages -- pending_validation, pending_deployment, and active -- within 2-5 minutes. No manual SSL configuration or certificate installation is required.

SSL provisioning lifecycle

The SSL provisioning process follows 4 automated stages:

1. Custom hostname creation: Perspection registers the customer domain (for example, events.yourdomain.com) as a Cloudflare custom hostname with the Perspection origin server (ingest.perspection.app). The registration triggers automatic certificate issuance.

2. Pending validation (pending_validation): Cloudflare verifies domain ownership through HTTP validation. The Perspection dashboard displays a "Validating" badge with an auto-refresh spinner. Validation typically completes in 1-3 minutes.

3. Pending deployment (pending_deployment): The validated certificate is being deployed to Cloudflare's global edge network (300+ data centers). The dashboard displays a "Deploying" badge. Deployment typically completes in 1-2 minutes.

4. Active (active): The SSL certificate is live. The dashboard displays an "Active" badge with the certificate authority name (Let's Encrypt or Google Trust Services) and the issuance date. All HTTPS requests to the first-party subdomain are now encrypted end-to-end.

SSL status monitoring

The Perspection dashboard automatically refreshes SSL status every 10 seconds while the certificate is in a pending state. The dashboard displays the following information for active certificates:

• Certificate status badge (Active, Validating, Deploying, or Error)

• Certificate authority (Let's Encrypt or Google Trust Services)

• Issuance date

• Expiration monitoring (Perspection flags certificates with fewer than 7 days until expiration)

SSL certificate renewal

Perspection SSL certificates are managed entirely by Cloudflare for SaaS and renew automatically before expiration. No manual intervention is required for certificate renewal. Perspection monitors certificate validity and logs warnings when certificates approach the 7-day expiration threshold.

Troubleshooting SSL provisioning

• SSL stuck in pending_validation: Confirm the DNS record shows "Verified" in the Perspection dashboard first. SSL provisioning cannot begin until DNS verification succeeds.

• Provisioning takes longer than 15 minutes: Check for CAA (Certificate Authority Authorization) DNS records on the domain that may block Let's Encrypt or Google Trust Services from issuing certificates. If a CAA record exists, add letsencrypt.org and pki.goog as permitted CAs.

• SSL error status: Click the Retry button in the dashboard to re-trigger certificate provisioning. If the error persists, contact Perspection support with the workspace ID and domain name.

How does a first-party domain improve Meta CAPI and ad platform conversions?

A first-party domain preserves the fbclid cookie beyond Safari ITP's 7-day limit, letting Perspection attach click IDs to conversions days or weeks later. The same applies to gclid, ttclid, msclkid, and li_fat_id. For Meta CAPI, first-party cookie persistence directly increases Event Match Quality by providing valid fbclid on more server-side conversions.

The click ID expiration problem

When a user clicks a Meta ad, Facebook appends fbclid=abc123 to the landing page URL. The Perspection SDK captures the fbclid value and stores the value in a browser cookie. Under third-party tracking:

• Safari ITP expires the cookie after 7 days.

• If the user converts on day 8, Perspection has no fbclid to attach to the conversion event.

• Meta receives the conversion event without a click ID, reducing the Event Match Quality score.

Under first-party tracking:

• The cookie is stored under events.yourdomain.com, treated as first-party storage.

• Safari does not apply the 7-day ITP cap.

• The fbclid persists for the full cookie duration.

• Perspection attaches the fbclid to the conversion event sent via Meta CAPI, and Meta successfully matches the conversion to the original ad click.

First-party domain and ad platform data flow

The first-party CNAME routes events through the Perspection ingestion endpoint assigned to the workspace. This ensures all event data -- including click IDs for Meta, Google, TikTok, and other ad platforms -- flows through a consistent, first-party origin that preserves cookie integrity and maximizes attribution accuracy.

Methodology

All first-party domain setup steps, DNS provisioning flows, and SSL certificate details in this guide were verified against the Perspection production dashboard as of February 2026.

"The single highest-leverage action any e-commerce brand can take to improve server-side tracking accuracy is configuring a first-party CNAME subdomain. The setup takes 5 minutes, but the impact compounds over every session, every returning visitor, and every conversion event that would otherwise be lost to ad blockers or ITP. Brands running Meta CAPI through Perspection consistently see a 15-25% increase in attributable conversions within the first 30 days of enabling a first-party domain, driven almost entirely by recovering Safari and Firefox users who were previously invisible to third-party tracking."

Sources and References

1. Cloudflare -- Understanding CNAME Records, https://developers.cloudflare.com/dns/manage-dns-records/reference/dns-record-types/

2. WebKit -- Intelligent Tracking Prevention, https://webkit.org/tracking-prevention-policy/

3. Let's Encrypt -- How It Works, https://letsencrypt.org/how-it-works/

4. Perspection Product Guide -- Install Web SDK, /library/install-tracking-website-guide

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