Custom Domains

Custom domains allow you to serve the Zenovay tracking script and access your dashboard from your own domain. This can improve ad-blocker bypass rates and provide a more branded experience.

Overview

With custom domains, you can:

• Serve tracking script from your domain (e.g., analytics.yourdomain.com)
• Access dashboard from custom URL (e.g., stats.yourdomain.com)
• Improve bypass rates by avoiding common analytics domains
• Maintain brand consistency across all services

Benefits of Custom Domains

1. Better Ad-Blocker Bypass

Ad blockers typically block requests to known analytics domains like api.zenovay.com. Using your own domain can improve tracking accuracy by 10-30%.

2. Faster Loading Times

Serving the script from your domain can reduce DNS lookup time and improve page load speed, especially if you're already using that domain.

3. Brand Consistency

Access your analytics at analytics.yourdomain.com instead of app.zenovay.com for a more cohesive brand experience.

4. First-Party Context

Cookies and storage from your domain are treated as first-party, which is more privacy-friendly and less likely to be blocked.

Types of Custom Domains

Tracking Script Domain

Serve the Zenovay tracking script from your domain.

Example: https://analytics.yourdomain.com/z.js

Use cases:

• Improve ad-blocker bypass rates
• Reduce DNS lookups
• First-party script loading

Dashboard Domain

Access your Zenovay dashboard from your domain.

Example: https://stats.yourdomain.com

Use cases:

• White-label analytics for clients
• Brand consistency
• Custom domain for team access

API Domain (Enterprise only)

Access the Zenovay API from your domain.

Example: https://api-analytics.yourdomain.com

Use cases:

• Complete white-label solution
• Strict CSP policies
• API rate limiting per domain

Setting Up Custom Domains

Step 1: Choose Your Domain

Select a subdomain for Zenovay:

Recommended subdomains:

• analytics.yourdomain.com (tracking script)
• stats.yourdomain.com (dashboard)
• metrics.yourdomain.com
• insights.yourdomain.com

Step 2: Add Domain in Zenovay

1. Go to Settings → Custom Domains
2. Click Add Custom Domain
3. Enter your subdomain (e.g., analytics.yourdomain.com)
4. Select domain type (Tracking Script / Dashboard / API)
5. Click Add Domain

You'll receive DNS configuration details.

Step 3: Configure DNS Records

Add the following DNS records to your domain provider:

For Tracking Script Domain

Add a CNAME record:

Type:  CNAME
Name:  analytics
Value: proxy.zenovay.com
TTL:   3600 (or Auto)

For Dashboard Domain

Add a CNAME record:

Type:  CNAME
Name:  stats
Value: app.zenovay.com
TTL:   3600 (or Auto)

Verification TXT Record

Add a TXT record for domain verification:

Type:  TXT
Name:  _zenovay-verification.analytics
Value: zenovay-verification=abc123xyz...
TTL:   3600 (or Auto)

Step 4: SSL Certificate

Zenovay automatically provisions an SSL certificate for your custom domain using Let's Encrypt.

Process:

1. DNS records verified
2. SSL certificate requested
3. Certificate issued (usually within 5 minutes)
4. Auto-renewal every 90 days

Status:

• Pending: DNS verification in progress
• Issuing: Certificate being generated
• Active: SSL certificate installed and working
• Failed: Configuration error (check DNS)

Step 5: Update Tracking Script

Once the domain is active, update your tracking script:

Before (default domain):

<script src="https://api.zenovay.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"
        async></script>

After (custom domain):

<script src="https://analytics.yourdomain.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"
        async></script>

Step 6: Verify Configuration

Test your custom domain:

1. Visit https://analytics.yourdomain.com/z.js
2. Verify the script loads without errors
3. Check SSL certificate in browser (padlock icon)
4. Test tracking on a page with the updated script

DNS Configuration by Provider

Cloudflare

1. Log in to Cloudflare dashboard
2. Select your domain
3. Go to DNS → Records
4. Click Add record
5. Add CNAME and TXT records as shown above
6. Important: Set Proxy status to "DNS only" (gray cloud)

Google Domains (now Squarespace)

1. Go to My Domains → Select domain
2. Click DNS → Manage custom records
3. Click Create new record
4. Add CNAME:
   • Host name: analytics
   • Type: CNAME
   • Data: proxy.zenovay.com
5. Add TXT record for verification

GoDaddy

1. Log in to GoDaddy account
2. Go to My Products → DNS
3. Click Add in DNS records section
4. Select CNAME from Type dropdown
5. Enter:
   • Host: analytics
   • Points to: proxy.zenovay.com
   • TTL: 1 Hour
6. Add TXT record for verification

Namecheap

1. Log in to Namecheap
2. Domain List → Manage
3. Go to Advanced DNS tab
4. Click Add New Record
5. Select CNAME Record:
   • Host: analytics
   • Target: proxy.zenovay.com
   • TTL: Automatic
6. Add TXT record for verification

Advanced Configuration

Custom Script Path

Change the script path from /z.js to a custom path:

Example: https://analytics.yourdomain.com/pixel.js

Setup:

1. Go to Settings → Custom Domains → Your domain
2. Click Advanced
3. Enter custom script path: /pixel.js
4. Save changes

Update your script tag accordingly.

Multiple Custom Domains

You can add multiple custom domains for different purposes:

API Proxy (Enterprise)

Proxy API requests through your domain:

// Default
fetch('https://api.zenovay.com/e/YOUR_TRACKING_CODE', { ... });

// Custom domain
fetch('https://api.yourdomain.com/e/YOUR_TRACKING_CODE', { ... });

Setup:

1. Add API custom domain in settings
2. Configure CNAME to api.zenovay.com
3. Update API endpoint in your code

Troubleshooting

Domain Verification Failed

Causes:

• DNS records not propagated yet (wait 1-24 hours)
• Incorrect CNAME or TXT record
• Typo in domain name
• DNS caching

Solutions:

1. Verify DNS records with dig or nslookup:

   dig analytics.yourdomain.com CNAME
   dig _zenovay-verification.analytics.yourdomain.com TXT
   

2. Clear DNS cache:

   # macOS
   sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
   
   # Windows
   ipconfig /flushdns
   
   # Linux
   sudo systemd-resolve --flush-caches
   

3. Use online DNS checker: https://dnschecker.org

SSL Certificate Failed

Causes:

• Domain not verified
• Cloudflare proxy enabled (orange cloud)
• CAA DNS record blocking Let's Encrypt
• Rate limit reached (Let's Encrypt)

Solutions:

1. Disable Cloudflare proxy (set to "DNS only")
2. Check CAA record:

   dig yourdomain.com CAA
   

3. If CAA exists, add Let's Encrypt:

   Type:  CAA
   Name:  @
   Value: 0 issue "letsencrypt.org"
   

4. Wait 1 hour and retry certificate issuance

Script Not Loading from Custom Domain

Check:

1. DNS: Verify CNAME points to correct target
2. SSL: Ensure certificate is active (green padlock)
3. Script Path: Confirm /z.js is correct
4. Browser Console: Look for errors
5. CSP: Add custom domain to Content-Security-Policy

CSP header example:

Content-Security-Policy: script-src 'self' https://analytics.yourdomain.com;

Dashboard Not Accessible

Verify:

1. CNAME record points to app.zenovay.com
2. SSL certificate is active
3. Domain status shows "Active" in Zenovay settings
4. No DNS caching issues

Test:

curl -I https://stats.yourdomain.com

Should return 200 OK with valid SSL.

Security Considerations

SSL/TLS

• Zenovay provides free SSL certificates via Let's Encrypt
• Certificates auto-renew every 90 days
• TLS 1.2 and 1.3 supported
• HSTS enabled for all custom domains

DNS Security

Enable DNSSEC on your domain to prevent DNS spoofing:

1. Check if your registrar supports DNSSEC
2. Enable DNSSEC in domain settings
3. Add DS records to parent zone

Access Control

Dashboard custom domains:

• Restrict access by IP (Enterprise)
• Enable mandatory 2FA for team
• Use SSO for authentication (Enterprise)

Performance Optimization

CDN Integration

For global performance, use Cloudflare or similar CDN:

1. Set up Cloudflare for your domain
2. Add custom domain to Zenovay
3. Configure CNAME records
4. Enable "DNS only" mode (gray cloud)
5. Optionally enable Cloudflare proxy AFTER SSL is active

Caching Headers

Zenovay sets appropriate cache headers for the script:

Cache-Control: public, max-age=3600, s-maxage=86400

• Browser cache: 1 hour
• CDN cache: 24 hours

HTTP/2 and HTTP/3

Custom domains support modern protocols:

• HTTP/2 enabled by default
• HTTP/3 (QUIC) available
• Server Push for faster loading

Removing Custom Domains

To remove a custom domain:

1. Update tracking scripts to use default domain
2. Wait 48 hours for cache to clear
3. Go to Settings → Custom Domains
4. Click ⋮ next to domain
5. Select Remove Domain
6. Confirm removal

DNS records can be deleted after removal is complete.

Best Practices

1. Use descriptive subdomains: analytics, stats, metrics
2. Test before deploying: Verify SSL and loading before updating live sites
3. Monitor certificate expiry: Zenovay auto-renews, but monitor for issues
4. Keep DNS records updated: Document DNS changes for your team
5. Use separate domains: Different subdomains for tracking vs dashboard

Getting Help

For custom domain setup assistance:

• Scale Plan: [email protected]
• Enterprise Plan: [email protected] (priority support)
• DNS Issues: Check Troubleshooting Guide