A Canonical Name record (abbreviated as CNAME record) is a type of resource record in the Domain Name System (DNS) used to specify that a domain name is an alias for another domain, which is the "canonical" domain.
Our CNAME feature allows you to create hostnames under your own vanity domain (subdomain), used in place of Pendo hostnames for both sending events and downloading guide content. This helps ensure that events are collected and guides are served to end users who even if they're subject to ad-blocking software, firewalls, VPNs, web filters, and so on.
Contact Pendo Support to begin setting up CNAME for your Pendo subscription. If you're in the closed beta for self-serve CNAME configuration, see the Configure organization CNAME (closed beta) article.
Configuration
Provide a subdomain of your corporate domain, such as product.example.com (where example.com is your corporate domain).
Pendo provides a set of required DNS entries, which must be created. The table below provides a list of examples. Pendo provides the actual set of DNS entries for you to create after you submit your request.
| Example domain | Example CNAME | Description |
|---|---|---|
| content.product.example.com | 1234567812345678-content.example.pendo.io | This record is an alias to a custom CDN configuration for your Pendo subscription content host. |
| _123456789abcdef.content.product.example.com | _fedcba987654321.ycvykntjsl.acm-validations.aws | This record shows Proof of Control for the subdomain to Amazon so that SSL certificates can be autogenerated. |
| data.product.example.com | u3fxrmuiqn95e67123t5j11td4q3dkiq-data.customer.pendo.io | This record is an alias to Pendo data host, app.pendo.io. |
| _0123456789ghijklmn.product.example.com | _fedcba987654321.dv.googlehosted.com | This record shows Proof of Control for the subdomain to Google's domain service so that SSL certificates can be autogenerated. |
| _acme-challenge.data.product.example.com | _6522233c-26fd-11ee-a5d5-8c8caac1e6d0.12.authorize.certificatemanager.goog. | This record shows Proof of Control for the subdomain to Google's certificate manager service so that SSL certificates can be autogenerated. |
The subdomain must be dedicated for use with Pendo.
After the DNS entries are configured, Pendo completes the CNAME configuration, which includes autogeneration of SSL certificates for the new hostnames.
After a new CNAME is assigned, Pendo updates the "data host" and "content host" to reflect the values assigned to the application, such as data.product.example.com and content.product.example.com, respectively. Admin users can then see (but not edit) this in Application Settings.
If we detect that your domain uses Certification Authority Authorization (CAA) records, which are used to specify which certificate authorities (CAs) are allowed to issue certificates for your domain, we include the requisite records to allow us to create managed certificates.
| Domain | CAA | Description |
|---|---|---|
| product.example.com | 0 issue "amazontrust.com" | Allow Amazon Certificate manager to be used as the CA (content host). |
| product.example.com | 0 issue "pki.goog" | Allow Google Certificate manager to be used as the CA (data host). |
| product.example.com | 0 issue "letsencrypt.org" | Allow Google Certificate manager to be used as the CA (data host). |
These CAA records are added to the subdomain (vanity domain) in the event they are removed from the parent domain.
You must ensure CAA records are added to the vanity domain as part of the CNAME configuration process. Adding CAA records to your vanity domain after your CNAME is configured can problems with renewing a managed certificated, causing disruption.
Update your Pendo install script ("snippet")
Once the CNAME is assigned to the application, Pendo rewrites the subscription’s Pendo agent using the new settings. From here on, all communication with Pendo happens through the aliases provided by the CNAME.
Next, update your Pendo install script (commonly referred to as "the snippet") anywhere it’s added in your application with your new "content host." The cdn.pendo.io continues to work while you do this, so no data is lost.
Resave your guides and images
You must also re-save each of your published guides, and re-upload any badge icons and other content, so that these are updated with the new aliases. New guides published after the CNAME is assigned automatically begin to use the new content host.
Repeat the following steps for each guide to be published after activating CNAME. Once a guide is resaved, its content is pulled from the alias domain.
- Open the details page of the guide.
- Select Manage In-App.
- Select Save in the Guide Management bar of the Visual Design Studio.
- Select Exit to leave the Visual Design Studio.
CNAME for Pendo Mobile
For information about configuring CNAME for Pendo Mobile, see Configure CNAME for Pendo Mobile.
Frequently asked questions
Does CNAME impact my CSP configuration?
Yes. You must change your CSP directives while you transition to CNAME and after CNAME is in place to maintain uninterrupted service to Pendo. Instructions for changing your CSP directives are in the Content Security Policy article.
Does CNAME guarantee that Pendo will track user analytics?
CNAME doesn't guarantee or ensure that visitor analytics will be captured if there are ad-blockers that might prevent Pendo from tracking usage.
Can I use CNAME with Twilio Segment?
Yes, but only if Pendo is installed using the Pendo Web (Actions) destination in Segment, which allows you to specify your CNAME content host in the destination settings. It's important to add the content host to Segment after you receive a confirmation that the CNAME setup is complete in Pendo, as changing this value in Segment prior to setup completion will break Pendo's data collection.
The legacy method of installing Pendo using the classic Pendo destination in Segment doesn't support CNAME. To learn how to install or migrate to the Pendo Web (Actions) destination, see Install Pendo through Twilio Segment.
Can I provide my own SSL certificates?
Yes. However, as a security best practice, you should allow Pendo to generate the Certificate Signing Request (CSR). This avoids sharing your private key. With Pendo generating the CSR, you must provide us with a text file suitable for generating a CSR. Pendo can generate a SAN template that's specific to your hosts, or you can use the following template to provide information under the [ dn ] section.
[ 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.com
Once we have the SAN file, we generate the CSR and send it to you. You use this to obtain a certificate from your CA. This removes the need to pass the private key between parties since the process of generating the CSR also generates the private key. The certificate and intermediate chain is safe to send through plain-text email.
If you need to send us an encrypted archive containing the certificate chain and private key, the standard method is to send encrypted files through keybase.io to a member of our OPS team. If you prefer your own approved secure file transfer mechanism, we can use that instead. We delete the private key once the certificate has been deployed so you must provide a new key for any future updates.