Configure organization CNAME

A CNAME lets you route Pendo's guide delivery and analytics through your own vanity URL. For example, product.example.com, so that requests appear to originate from your domain rather than Pendo's. This helps ensure guides and analytics reach visitors even when ad blockers or web filters are in place. Use this article to configure a CNAME record at the organization level.

Prerequisites

We strongly recommend that you first read Overview of a CNAME before continuing with this article. You will need:

• Organization admin permissions. Subscription admins don't have access to update CNAME settings. You must be an organization admin. For more information, see Organization users.
• CNAME turned on for your organization. Contact your Pendo Support Team to turn this on before you start.
• Engineering resources. Some steps, such as adding your DNS records, require technical expertise.

Add a CNAME configuration

To add a new CNAME you must contact Pendo with a request to turn on the ability to use a CNAME. After this is done, follow these steps in order.

1. Create a new CNAME configuration
2. Update your DNS entries
3. Update CSP rules (if applicable)
4. Assign a CNAME to your apps
5. Resave existing guides
6. Update your Pendo install script

Step 1. Create a new CNAME configuration

Use a dedicated subdomain of your corporate domain, such as product.example.com (where example.com is your corporate domain). This reduces the risk of path conflicts and rendering issues caused by backend route handling.

1. From the top-right corner of the page in Pendo, go to Settings > Organization settings.
   
2. Select the CNAME tab. This page includes a list of the subscriptions for your organization. If you don't see CNAME as an option, you don't have it turned on for your organization. Contact your Pendo Support Team to turn it on. 
   
3. Hover over the subscription that you’d like to add the CNAME to, and select View CNAME Configuration.
4. In the top-right corner, select Manage CNAME configurations. If you don’t have a CNAME set up yet, select Set up CNAME instead.
   
5. Select New CNAME configuration in the top-right corner of the page.
6. Enter the Name, Domain, Content Prefix, and Data Prefix for your CNAME configuration.
   
7. Select Save.

Step 2. Update your DNS entries

After completing Step 1, Pendo sends you an email with your DNS records. The records will look similar to the examples below. Follow the detailed instructions in the email to add your DNS records.

Example DNS records

Example CAA records

If your domain uses CAA (Certification Authority Authorization) records, you must also add the following records to your subdomain before continuing. CAA records control which certificate authorities (CAs) are allowed to issue certificates for your domain. Adding these records after your CNAME is configured can cause problems renewing managed certificates and may disrupt Pendo functionality.

These records are added to your subdomain in case they are removed from the parent domain.

Confirm your DNS setup

After adding your records, allow up to an hour for Pendo to detect them. To confirm the setup is complete:

1. Go to Settings > Organization settings
2. Select the CNAME tab.
3. Hover over the subscription that you added the DNS records for.
4. Select View CNAME Configuration.
5. From the top-right corner, select Manage CNAME configurations.
6. In the list you'll see the CNAME with a status of Done.
   

Once the status shows Done, Pendo sends you a confirmation email. You’re then ready to continue to Step 3. 

For help resolving DNS validation issues during CNAME setup, see Troubleshooting DNS records

Step 3. Update CSP rules

If your application uses a Content Security Policy (CSP), update it to allow your new CNAME before switching over. Without the correct CSP directives, Pendo may be blocked from loading scripts, styles, images, or network requests.

Pendo generates the required CSP directives based on your app and subscription settings, including your assigned CNAME configuration.

1. Go to Settings > Subscription settings
2. Select the Applications tab.
3. Select the app you added the CNAME for.
4. Select the Install Settings tab.
5. Scroll to the CSP Configuration section.
6. Select Copy to copy the generated CSP directives.
   
7. Add the copied directives to your application’s CSP settings. If you already have Pendo-related CSP rules, replace the old Pendo host names (for example, cdn.pendo.io and *.pendo.io) with the new CNAME host names from your configuration.
8. Remove any outdated Pendo CSP rules that reference the previous host names.
9. Deploy your CSP changes to all environments where Pendo is installed (production, staging, and so on).
10. Confirm guides, analytics, and other features load without CSP errors in the browser console.

Step 4. Assign a CNAME to your apps

After your CNAME configuration shows a status of Done, assign it to each app that should use it. While a CNAME is set up at the organization level, it only takes effect for an app once you assign it on the Subscription CNAME Settings page.

1. Go to Settings > Organization settings.
2. Select the CNAME tab.
3. Hover over the subscription that you set up the CNAME for and select View CNAME Configuration.
4. On the Subscription CNAME Settings page, find the app you want to update.

5. In the CNAME Configuration column, open the dropdown and select your CNAME configuration.

   Note: If the app already has a CNAME assigned, select the edit icon in that row before choosing a different configuration from the dropdown.

6. Review the steps in the confirmation message, then select Confirm.

The CNAME Configuration column updates to show the assigned configuration name for that app. After the CNAME is assigned, Pendo rewrites the subscription's Pendo web SDK with the new settings, autogenerates SSL certificates for your new host names, and updates the data host and content host to reflect your new values. All newly published guides and content will use the new content host, and all new events will be sent through the data host. Subscription admins can see the data host and content host values in application settings but cannot edit them.

Step 5. Resave existing guides

Guides published before you assigned a CNAME were built using the default Pendo host name. After switching to a CNAME, these guides don't update automatically and may still load content from the old URL, which can cause them to display incorrectly. You must resave each published guide after switching to ensure the content loads from your new host.

1. Go to Guides > Guides.
2. Find and open the guide you want to update.
3. Select Edit in my app in the top-right of the Content section.
4. Select Save from your Visual Design toolbar.

Tip: You can find all your published guides by filtering by guide status on the top of the guides page: All statuses > Public.

Step 6. Update your Pendo install script

Important: Don’t update the Pendo install script until you receive email confirmation from Pendo that the CNAME setup is complete. The email subject line will have this format: "[subscription name]'s CNAME configuration [subdomain] is complete". 

Update your install script anywhere it's added in your application with your new content host. cdn.pendo.io continues to work while you do this to ensure that no data is lost, and visitors continue to see guides without interruption.

If you're installing Pendo with Twilio Segment, you can add the content host in your Segment destination settings using the CNAME content host field. For more information, see Install Pendo through Twilio Segment.

CNAME for Pendo Mobile

If you use Pendo Mobile, you must also configure platform-specific settings for Android and iOS after completing Steps 1–6. Without these updates, mobile apps will continue using Pendo's default endpoints.

Android

Add the following entry to your app's AndroidManifest.xml, inside the <application> tag replacing <data.product.example.com> with the CNAME you've set up:

<meta-data android:name="pnd_device_url" android:value="https://<data.product.example.com>" />

iOS

Add the following mapping to your Info.plist file replacing <https://dataproduct.example.com> with the CNAME you've set up.

<key>PNDCNames</key>
<dict>
  <key>PNDDeviceURL</key>
  <string>https://data.product.example.com</string>
</dict>