Reverse Proxy | Yext Hitchhikers Platform
For most customers, we recommend hosting your pages via Yext-hosted subdomain. With this approach, the only required setup on your end is to register a single CNAME record from your desired subdomain to a Yext bridge domain. Visually, a request for a page using this setup looks something like this:
Alternatively, you can choose to host your pages from a subdirectory under your root domain, which will require you to configure a reverse proxy service at your origin to forward requests to Yext. Refer to the image below:
If you choose to use the reverse proxy approach, hereβs a guide about how to get setup:
1. Configure Frontend Code
To fulfill reverse proxy requests, you will need to:
Add a serving.json
file to the sites-config/
folder in your repo. This file should include the following lines of JSON, where the displayUrlPrefix
is set to your root domain + subdirectory where your page content will be requested from:
{
"displayUrlPrefix": "www.[brand].com/[subdirectory]",
}
Commit your code changes once you have added this file to your repo. Once your deploy completes successfully, your sitemap content will be registered with the desired absolute URLs from your root domain.
Links
To ensure that relative links to your Yext Pages work correctly during a reverse proxy setup, you must prepend them with the relativePrefixToRoot
object. If not included, relative links will resolve to the Yext-hosted origin instead of to your own origin.
For each page in your site, relativePrefixToRoot
contains the relative path from the generated page to the root of the site, and is accessible via TemplateRenderProps
; refer to the example below:
import { Template, TemplateRenderProps } from "@yext/pages";
import { Link } from "@yext/pages/components";
import "../index.css";
const Location: Template<TemplateRenderProps> = ({
relativePrefixToRoot,
path,
document,
__meta
}) => {
const {
array.name,
array.slug
} = document;
return (
<>
<div className="space-x-8">
{array.map((entity:any) => (
<Link href={relativePrefixToRoot + entity.slug}>
{entity.name}
</Link>))
}
</div>
</>
)
}
2. Connect Domain to Site
In order for Yext to register analytics events for your site, you must create a domain and connect it to your site. To do so, navigate to the Pages > Domains section in the UI, and complete the following steps:
- Click βAdd new domainβ
- For
Use this domain for Search?
, select “No”. - For
Select integration method
, select “Reverse Proxy“ - Enter a domain name of the format
[subdomain].[domain].com
. - Connect this domain to your site from Site Settings.
3. Configure Root Domain
The reverse proxy should live on your domain, and forward traffic to the Yext-hosted domain which which you just created in the previous step - and should look something like
locations.yext.com.pagescdn.com
.The reverse proxy should be configured to communicate with the hosting domain over HTTPS with SNI support. Without SNI support, your reverse proxy will not be able to communicate with Yext Pages hosting using HTTPS.
The Pages infrastructure requires that the HTTP βHostβ header is set to the Yext Pages content host of
locations.yext.com.pagescdn.com
. Any other Host header will prevent the Yext CDN from finding the proper content.The Yext bridge domain connects to a dynamic CDN IP address and is subject to change at any time. Please make sure that any DNS configuration respects cache TTL values from the Yext Pages serving infrastructure. Some reverse proxy servers default to resolving DNS once on startup and then never again. To ensure the reliability of pages, check your reverse proxy for default settings that ignore DNS TTL.
- Your bridge domain can be found in the βDomainsβ section of the UI.
Client IP addresses should be forwarded using the standard HTTP βX-Forwarded-Forβ header. Most web servers with reverse proxy functionality built in will handle this automatically. This is required for server-side geolocation to function properly.
The reverse proxy should be configured to NOT cache any responses from Yext Pages, error or otherwise. That is, every request made for a Yext Pages content by a consumer should be forwarded to the Yext Pages content host. The Yext CDN has extensive caching logic in place; additional proxy-side caching will lead to stale consumer-facing content.
The subfolder portion of the URL should be stripped out before forwarding the request to Yext Pages;
- e.g., A request to
www.yext.com/locations/va/123-bob-ct.html
should be forwarded tolocations.yext.com.pagescdn.com/va/123-bob-ct.html
.
- e.g., A request to
The reverse proxy should be configured to redirect any inbound urls containing trailing slashes β/β to their equivalent url without the trailing slash. For example:
www.yext.com/locations/search/?query=new+york
should be redirected towww.yext.com/locations/search?query=new+york
.- The one exception to this rule is the root domain when using a subfolder, which should be configured to redirect to
www.brand.com/locations/
.- If using a subfolder, such as
/locations
,www.yext.com/locations
should be configured to redirect towww.yext.com/locations/
. - The trailing slash is critical to ensure that relative URLs (assets and links) on the Yext Pages will resolve correctly on the root page.
- If using a subfolder, such as
- The one exception to this rule is the root domain when using a subfolder, which should be configured to redirect to
Yext Pages automatically maintains an up-to-date sitemap at
locations.yext.com.pagescdn.com/sitemap.xml
. The public facing address of the sitemap will therefore bewww.yext.com/locations/sitemap.xml
.- To expose the sitemap to search engines, the robots.txt or existing sitemap of
www.yext.com
should be updated to reference the Yext Pages sitemap.
- To expose the sitemap to search engines, the robots.txt or existing sitemap of
If necessary, refer to our sitemap reference article to customize your sitemap name.