A CNAME (Canonical Name) is a type of DNS record that routes your Pendo visitors through a subdomain of your own domain. Specifically, Pendo uses a technique known as CNAME masquerading, where Pendo's domain is served through your own subdomain so that requests appear to originate from your domain rather than a third-party one. This article explains what a CNAME is, when to use one, and what to be aware of before you begin setup.
For step-by-step instructions, see Configure organization CNAME. That article walks you through each stage of setup and tells you when each of these considerations applies.
What a CNAME does
When Pendo is installed, user data and guide content are automatically sent to and from Pendo's servers using its default network addresses. If you choose to use a CNAME, that traffic is routed through a subdomain you control. For example, product.example.com instead of pendo.io.
After setup, Pendo assigns two host names to your application:
- A content host for delivering guides and in-app content
- A data host for sending user analytics back to Pendo
When to use a CNAME
You should consider using a CNAME if:
- You want Pendo to operate under your own subdomain rather than the Pendo default domain.
- You need to reach visitors who use ad-blocking software, firewalls, VPNs, or web filters that block Pendo's default endpoints.
How CNAME affects ad blocker behavior
Ad blockers can interfere with Pendo in three ways: blocking guide delivery, blocking event data from being sent to Pendo, and preventing the Pendo Web SDK from loading. A CNAME addresses this by making guide content and event data requests appear to come from your own subdomain, rather than Pendo's domains directly.
| What ad blockers can block | Why it matters | With CNAME |
|---|---|---|
| Loading guides | Visitors don't see guides | Guides appear to come from your content host subdomain, so most ad blockers allow them. |
|
|
Usage data isn't collected | Events appear to come from your subdomain, so most ad blockers allow them. |
| Loading the Pendo Web SDK | Pendo can't run at all. No guides or data are collected | Update the SDK source URL in your install script to your client subdomain, so most ad blockers allow it to load. If your install uses Twilio Segment, updating the SDK will not resolve this problem. |
CNAME reduces the likelihood that ad blockers will interfere with guide delivery and event collection, but it doesn't guarantee that user analytics are captured. Some ad blockers may still prevent data from being collected regardless of your CNAME configuration.
What you need to get started
Configuring a CNAME requires technical expertise. We recommend involving your engineering team before you start.
-
A dedicated host name on your corporate domain. For example,
product.example.com. You'll need to create a DNS CNAME record pointing this host name to Pendo's servers. Work with your engineering team to set this up. - By default, Pendo generates and manages an SSL certificate for your CNAME subdomain. You don't need to do anything. However, in some organizations, your security team may require that you provide your own SSL certificate. If that is the case, contact your Pendo support team to begin the process.
If your security team requires a custom certificate: Create a SAN (Subject Alternative Name) file using the template below and share it with Pendo. Pendo uses it to generate a CSR (Certificate Signing Request) on your behalf and sends it back to you. You then use the CSR to obtain a certificate from your CA (Certificate Authority). The certificate and intermediate chain can be shared over plain-text email. Note that Pendo deletes the private key after deployment, so you'll need to provide a new one for any future certificate updates. Use the following template and fill in the required information under the[ dn ]section.
Template
[ req ]
default_bits = 2048
prompt = no
encrypt_key = no
default_md = sha256
distinguished_name = dn
req_extensions = req_ext
[ dn ]
commonName = Common Name (server FQDN; data.product.example.com)
organizationName = Organization Name (eg, company)
localityName = Locality Name (eg, city)
stateOrProvinceName = State or Province Name (full name)
countryName = Country Name (2 letter code)
organizationalUnitName = Organizational Unit Name (eg, section)
[ req_ext ]
subjectAltName = @alt_names
[ alt_names ]
DNS.1 = data.product.example.com
DNS.2 = content.product.example.comSetup considerations
Things to do before you set up a CNAME
CSP (Content Security Policy) configuration must be updated. If your application uses a CSP, you need to update your CSP directives when transitioning to CNAME and after setup is complete. This needs to be done before you assign a CNAME to any of your apps. For details, see Content Security Policy (CSP).
Things to do during the CNAME process
CAA (Certification Authority Authorization) records must be added before setup is complete. If your domain uses CAA records, you must add the required CAA records to your subdomain as part of the CNAME configuration process. Adding them after your CNAME is configured can cause problems when renewing managed certificates, which may disrupt Pendo functionality.
Things to do after you set up a CNAME
Update your install script. After a CNAME is configured, Pendo updates the sample install script with your new content host. You then need to copy this updated script and replace your existing install script everywhere it appears in your application. Your existing cdn.pendo.io endpoint continues to work while you do this, so no data is lost during the transition.
Published guides need to be resaved. After your CNAME is active, you must resave each published guide so its content is served from your new content host. Guides published after the CNAME is assigned will automatically use the new content host. Only guides that were published before you added the new CNAME will need to be resaved manually.
Twilio Segment users must update the content host after CNAME setup is complete. CNAME is only supported when Pendo is installed using the Pendo Web (Actions) destination in Segment. The legacy classic Pendo destination doesn't support CNAME. If you're using the Actions destination, add your CNAME content host in the destination settings only after you receive confirmation that setup is complete in Pendo. Updating this value before setup is complete will break Pendo's data collection. To install or migrate to the Pendo Web (Actions) destination, for more information, see Install Pendo through Twilio Segment.
If you change your application domain
A domain change requires a new CNAME configuration. If you're already using a CNAME and your application's domain is changing, you need to configure a new CNAME and assign it to your applications in Pendo. Your existing CNAME can't be updated to reflect the new domain.
If both your current and new domains are active at the same time, you can set up the new CNAME in advance and assign it when you're ready to switch. Keep your original DNS records in place until the switch is complete, and make sure your CSP rules account for both domains. After you've switched to your new CNAME and republished all your guides, you can remove the previous domain references from your CSP rules.
For setup instructions, see Configure organization CNAME.
Pendo mobile will need to be configured separately
After CNAME is configured, you'll also need to configure platform-specific settings for Android and iOS. For more information, see Configure organization CNAME.