CNAME for Pendo

Last updated:

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.

Once the DNS entries are configured, Pendo completes the CNAME configuration, which includes autogeneration of SSL certificates for the new hostnames.

Once a new CNAME is assigned, Pendo updates the "data host" and "content host" in Subscription Settings to reflect data.product.example.com and content.product.example.com respectively.

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.

  1. Open the details page of the guide.
  2. Select Manage In-App.
  3. Select Save in the Guide Management bar of the Visual Design Studio.
  4. 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.

Can I use CNAME with Segment.io?

No. Configuring CNAME requires access to the Pendo install script to replace the src URL. The Pendo install script can't be modified with a Segment.io installation.

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.

Was this article helpful?
5 out of 8 found this helpful