Deployment FAQ

Can I deploy Kapa behind a login?

Yes, you can deploy behind a login.

• The Website widget is most commonly integrated in public documentation sites but it can also be integrated into web pages behind a login.
• The Support Form Deflector can be integrated into both public support forms and those behind a login.
• You can leverage the API to power your own interfaces irrespective of where they are integrated.

How do I fix CORS errors?

CORS (Cross-Origin Resource Sharing) is a security mechanism that controls which domains can access resources from Kapa's servers.

How CORS affects your Kapa integration

When your website (e.g., yourdomain.com) makes requests to Kapa's services (e.g., proxy.kapa.ai), these are considered "cross-origin" requests. Without proper CORS configuration:

• The browser blocks these requests
• Your Kapa Website Widget won't function
• Users see CORS errors in their browser console

What CORS errors look like

Access to fetch at 'https://proxy.kapa.ai/...' from origin 'https://yourdomain.com' has been blocked by CORS policy

How to fix

You don't need to modify your own server's CORS settings. Instead:

1. In the Kapa platform, add your domain to the enabled domains list when configuring your integration
2. This tells Kapa's servers to allow requests from your domain
3. This prevents CORS errors in your integration

How do I fix CSP errors?

CSP (Content Security Policy) is a security feature that you configure on your website to specify which external resources your site is allowed to use.

How CSP affects your Kapa integration

When you add Kapa widgets to your site, your CSP needs to allow:

• Scripts loading from Kapa's domains
• API connections to Kapa's services
• Other Kapa-related resources

Without proper CSP configuration:

• Scripts from Kapa won't load
• API requests to Kapa services are blocked
• Users see CSP violation errors in their browser console

What CSP errors look like

Refused to load the script 'https://widget.kapa.ai/...' because it violates the following Content Security Policy directive: "script-src 'self'"

How to fix

If your website has a Content Security Policy enabled, whitelist these domains:

• https://widget.kapa.ai - For loading the widget script
• https://proxy.kapa.ai - Proxy for widget functionality
• https://kapa-widget-proxy-la7dkmplpq-uc.a.run.app - A fallback for the main proxy
• https://metrics.kapa.ai - For optional analytics and metrics collection
• https://www.google.com/recaptcha/ - For reCAPTCHA functionality
• https://hcaptcha.com and https://*.hcaptcha.com - For hCaptcha functionality

Add these domains to your CSP directives:

<meta
  http-equiv="Content-Security-Policy"
  content="
  script-src 'self' widget.kapa.ai www.google.com https://hcaptcha.com https://*.hcaptcha.com;
  connect-src 'self' proxy.kapa.ai kapa-widget-proxy-la7dkmplpq-uc.a.run.app metrics.kapa.ai https://hcaptcha.com https://*.hcaptcha.com;
  frame-src 'self' www.google.com https://hcaptcha.com https://*.hcaptcha.com;
  style-src 'self' https://hcaptcha.com https://*.hcaptcha.com
"
/>

Or via HTTP headers:

Content-Security-Policy: script-src 'self' widget.kapa.ai www.google.com https://hcaptcha.com https://*.hcaptcha.com; connect-src 'self' proxy.kapa.ai kapa-widget-proxy-la7dkmplpq-uc.a.run.app metrics.kapa.ai https://hcaptcha.com https://*.hcaptcha.com; frame-src 'self' www.google.com https://hcaptcha.com https://*.hcaptcha.com; style-src 'self' https://hcaptcha.com https://*.hcaptcha.com;

Summary: CORS vs CSP

CORS settings (in Kapa) control who can access Kapa's services, while CSP settings (on your website) control what external resources your site can use. Both need to be configured correctly for Kapa widgets to function properly.

For a successful Kapa integration:

1. CORS configuration: Add your domain to the enabled domains list in the Kapa platform
2. CSP configuration: Update your website's Content Security Policy to include the Kapa domains

How do I view user analytics?

All Kapa integrations except the Zendesk Agent App track users anonymously by default and can be configured for non-anonymous tracking with email or custom identifiers.

Integration	Anonymous tracking	Non-anonymous tracking
Website Widget	First-party cookie (kapa_web_id)	Email or custom ID via window.kapaSettings
Support Form Deflector	First-party cookie (kapa_web_id)	Email from form fields or window.kapaSettings
Slack Bot	Slack user ID	Email collection via users:read.email scope
Discord Bot	Discord user ID	Email collection when enabled
Internal Assistant	Kapa account identity	Company email via Google Sign-In
MCP Server	Opaque OAuth user ID	Email or custom ID via _meta field (API key mode)

Once user tracking is in place, team members and administrators can analyze user activity and conversation data on the Kapa platform:

• Users dashboard: Navigate to Users in the left sidebar to view all tracked users, their activity metrics, and conversation history
• User filtering: Search for specific users by ID or email, or filter to show only users with email addresses
• Conversation analysis: Click "View conversations" for any user to see their complete interaction history
• User context in conversations: When reviewing conversations, user IDs are displayed in the details panel, allowing you to see which user submitted a question

You can also use the Export feature, available on both the Users and Conversations screens, to export conversation or user data as CSV for processing in external systems.