Reverse Proxy | Yext Hitchhikers Platform

You may choose to host your Yext website via subdomain vs. subdirectory.

With the subdomain approach, the only required setup on your end is to register a 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 subdirectory approach, here are the steps you will need to complete in order to set up your reverse proxy:

1. Configure Frontend Code

package.json

You must be on yext/pages version 1.0.0-beta.16 or higher in order to reverse proxy.

serving.json

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 within your site 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>
    </>
  )
}

This includes any images stored locally in your repo that are imported into your templates. Refer to the Favicon example below, which is prefixed with the relativePrefixToRoot:

import Favicon from "../assets/images/yext-favicon.ico";

export const getHeadConfig: GetHeadConfig<TemplateRenderProps> = ({
  relativePrefixToRoot,
  document,
}): HeadConfig => {
  return {
    title: document.name,
    charset: "UTF-8",
    viewport: "width=device-width, initial-scale=1",
    tags: [
      {
        type: "link",
        attributes: {
          rel: "icon",
          type: "image/x-icon",
          href: relativePrefixToRoot + Favicon,
        },
      },
    ],
  };
};

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.

Note

Pages Analytics events will not be recorded for your site if you are using the default production placeholder domain.

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 to locations.yext.com.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.yext.com/locations/search/?query=new+york should be redirected to www.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 to www.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.
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 be www.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.
If necessary, refer to our sitemap reference article to customize your sitemap name.

Back

< Authentication

Multiple Language Support >

Feedback

<% elem.innerText %>