CNAME for Pendo Insights and Guidance

Overview

The CNAME feature allows you to create hostnames under your own application’s domain which will be 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 are subject to ad-blocking software, firewalls, web filters, etc.

 

What does CNAME stand for?

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.

 

Note: Reach out to Pendo Support to begin setting up CNAME for your Pendo subscription.

 

Configuration

Provide a subdomain of your corporate domain, such as product.example.com (where ‘example’ is your corporate domain).

Pendo provides a set of required DNS entries which must be created. They look something like:

Domain CNAME Description
product.example.com 1234567812345678-txt.example.pendo.io This record is used to validate to Google that Pendo can serve data.product.example.com via Google App Engine.
data.product.example.com 1234567812345678-data.example.pendo.io This record is an alias to app.pendo.io.
content.product. example.com 1234567812345678-content.example.pendo.io This record is an alias to a custom CDN configuration for your Pendo subscription.
_0123456789abcdef. content.product. example.com _fedcab987654321.acm-validations.aws This record is used to validate subdomain ownership to Amazon so that SSL certificates can be autogenerated.


The above examples are placeholders, Pendo will provide the actual set of DNS entries to be created.

 

Note: You need a unique content domain for each Pendo subscription key.

 

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

Pendo updates the "data host" and "content host" in Subscription Settings to point to data.product.example.com and content.product.example.com respectively.

 

Update your Pendo Snippet

The Pendo application triggers a rewrite of the Subscription’s Pendo Agent using the new settings. From this point on, all communication with Pendo happens via the aliases provided.

Next, you will need to update your Pendo snippet anywhere it’s installed with your new "content host."

 

Resave Your Guides

You will need to re-save each of your existing Guides so their content will be pulled from the new aliases.

Repeat these steps for every active Guide.

  1. In Guide Details, click Manage In-App.
  2. In the Visual Design Studio, Click Save in the Guide Management bar.
  3. Click Exit to leave the Visual Design Studio.
  4. Repeat for each Guide that will be published after activating CNAME.
  5. Once a Guide is resaved, its content is pulled from the alias domain.

 

CNAME for Pendo Mobile

Requirements: Mobile CNAME requires Android and iOS SDK version 2.5.1 or higher

 

Note: The Hash values required below are provided by Pendo after the certificates are installed.

 

Enabling CNAME in Android

Add the following entries to the app’s Manifest.xml, inside the <application> tag:

example:
<meta-data android:name="pnd_device_url" android:value="https://device_url.acme.com/" />
<meta-data android:name="pnd_app_url" android:value="https://app_url.acme.com/" />
<meta-data android:name="pnd_data_url" android:value="https://data_url.acme.com/" />
<meta-data android:name="pnd_device_hash" android:value="sha256/035gh43/1Df3aP/dh3j7iHFk23gs7Upuf8R4gd=" />
<meta-data android:name="pnd_data_hash" android:value="sha256/03gp63/3Da143/k64vr5df526d7=" />

 

Enabling CNAME in iOS

Add the following mapping to your info.plist

<key>PNDCNames</key> 
<dict>
<key>PNDDeviceURL</key>
<string>https://device_url.acme.com</string>

<key>PNDAppURL</key>
<string>https://app_url.acme.com</string>

<key>PNDDataURL</key>
<string>https://data_url.acme.com</string>

<key>PNDDeviceHash</key>
<string>6fSJ7nrsv8A/65FAOBoGr34q3Ar63gjFy88FA7C84Av=</string>

<key>PNDDataHash</key>
<string>Ga+fa/Rsv/Sfh4AFsEkhA895hsdg4654FHSfd5SgO+df4=</string>
</dict>

 

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 snippet to replace the src URL. The Pendo snippet cannot be modified with a Segment.io installation.

 

Can I provide my own SSL certificates?

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 generates a key and CSR. We send you the CSR, which you use to obtain a certificate from your CA. This eliminates the need to pass a private key between parties. The certificate chain is safe to send via plain-text email.

CSR input file example

[ 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

 

If you must provide Pendo with the SSL certificates, you can provide a single SSL certificate suitable for both the data and content hostnames, or provide two separate certificates.

Generate a key and CSR, obtain a certificate from your CA, and send us an encrypted archive containing the certificate chain and private key. Our standard method is to send PGP-encrypted files via keybase.io to a member of our OPS team. If you prefer your own approved secure file transfer mechanism, we can use that instead.