Reverse Proxy| 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:

subdomain.png

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:

reverse-proxy.png

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.

reverse-proxy-urls.png


2. Configure Root Domain

  • The reverse proxy should live on your domain, and forward traffic to the Yext-hosted domain which should look something like [site identifier].[brand].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. In that case, notify Yext and we’ll have to remove HTTPS from your origin.
  • The Pages infrastructure requires that the HTTP “Host” header is set to the Yext Pages content host of [site id].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.
  • 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.brand.com/locations/va/123-bob-ct.html should be forwarded to [site identifier].pagescdn.com/va/123-bob-ct.html
  • 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.brand.com/locations/search/?query=new+york should be redirected to www.brand.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.brand.com/locations should be configured to redirect to www.brand.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.
  • Yext Pages automatically maintains an up-to-date sitemap at [site id].pagescdn.com/sitemap.xml. The public facing address of the sitemap will therefore be www.brand.com/locations/sitemap.xml. To expose the sitemap to search engines, the robots.txt or existing sitemap of www.brand.com should be updated to reference the Yext Pages sitemap.
  • If necessary, refer to our sitemap reference article to customize your sitemap name.
  • For integrating a reverse proxy with the Yext staging site, please note the following:
    • The Yext staging environment does not fully replicate the production serving architecture (specifically the omission of a CDN provider). Yext strongly recommends testing using the production origin, in order to replicate the end consumer request flow as accurately as possible.
Feedback