Global Settings & Locale Configuration | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to add global settings and set up the locale configuration
• How to add favicon and logo
• How to add GTM to your experience

Global Settings & Locale Configuration

You’ve created your repo. What now?

The first thing you’ll want to do is fill out your global settings and your locale config, which live in the config > global_config.json file and config > locale_config.json file respectively. These files comes with all experiences and are where you specify things that are shared across all pages, like the experienceKey, sdkVersion, favicon or Google Tag Manager (GTM) ID.

The locale_config.json is absolutely required in order to get your experience working, so let’s start there.

locale_config.json File

If you are building a single-language experience (which is most common, at least to start), you only need to specify the default locale and the experienceKey to get started. You can ignore the rest of the file until you’re ready to build Multi-Language experiences, which you can learn about in the Multi-Language track.

The Experience Key is from your Search Configuration. You can find this by navigating to Search > All Search Experiences > Your Experience. This is how the system knows which search configuration to use when running searches. By default, the system will use the configuration version pinned to the STAGING label in the Staging Environment (typically this will be the “Latest” version) and the version pinned to the PRODUCTION label in the Production Environment.

The locale config contains 3 main properties:

• the default locale
• the localeConfig, which includes things like the experienceKey for all locales, even the default
• the urlFormat

Here’s an example of what this file looks like for a single language experience:

{
  "default": "en",
  "localeConfig": {
    "en": {
      // "fallback": [""], // allows you to specify locale fallbacks for this locale
      // "translationFile": "<filepath>.po", // the filepath for the translation file
      // "urlOverride": "", // provide an override for the url path for this locale if you want it to be different than specified in the urlFormat object
      "experienceKey": "answers" //  the unique key of your search configuration for this locale
    }
  },
  "urlFormat": {
    "baseLocale": "{locale}/{pageName}.{pageExt}",
    "default": "{pageName}.{pageExt}"
  }
}

Again, for a single language experience, you only need to specify the default locale and set the localeConfig for your default locale.

default: this is the locale code for your experience. This should align with the language code for your entities in the Knowledge Graph. If you’re not sure what this is, you can look in Account Settings > Personal Settings and find the Default Language for your account. You can also look at the “Languages” module on Entity Edit. If your account is in the US and you have not enabled multi-language profiles, your default locale should be set to “en”. Similarly, if you are in the UK, it should be set to “en_gb”.

localeConfig: the localeConfig object, most importantly, is where you specify the experienceKey so that the frontend knows which backend configuration to connect with. In the case that you have multiple languages, you have the flexibility to use different experienceKeys per language. You can learn more about this and the additional properties that you can set here in the Multi-Language Search module. You need a localeConfig for each language in your experience, including the default.

global_config.json File

The global_config.json file allows you to specify properties that are shared across the pages and that are not specific to a locale, including things like the sdkVersion or favicon. You can optionally choose to specify things like the API Key or Business ID, but if you don’t specify these (which most people don’t) we’ll automatically populate for you based on the account that you’re in.

Here’s an example of what this file looks like:

{
  "sdkVersion": "1.7", 
  // "apiKey": "<REPLACE ME>", 
  // "businessId": "<REPLACE ME>", 
  "logo": "", 
  "favicon": "",
  "googleTagManagerName": "dataLayer", 
  "googleTagManagerId": "", 
  "googleAnalyticsId": "", 
  "conversionTrackingEnabled": true
}

Required Properties:

You must fill this out in order to get your experience working.

SDK Version: This is the version of the SDK library that you want to use. As you learned in the last module, you can choose to pin to a specific version (e.g., 1.3.1), a minor version (e.g., 1.3 which will use the latest patch version of that minor 1.3) or a major version (e.g., 1 which will use the latest version in the major 1 - not recommended). The theme will update with the latest version of the API so when you upgrade your theme make sure to check this.

Optional Properties:

These properties are optional, but recommended:

Logo: Add a url or asset reference to the logo you want to use as the thumbnail image whenever the site is shared on social media platforms, like Twitter or Facebook. If you are using the Yext hosted experience, we strongly recommend that you fill this out. If you are embedding the search results on an existing page in your CMS, this is not necessary.

...
"logo": "https://www.yext.com/wp-content/themes/yext/img/icons/favicon-seal.png"
...

Or

... 
"logo": "static/assets/images/favicon-image.png"
...

Favicon: Add a url or asset reference, just like you did for the logo.

These properties are entirely optional and should only be used as needed:

apiKey: We will automatically pull the Search API key from your account for you. But, if for some reason you want to use another API key, you can enter it here.

Business ID: If you set an API Key from another business, please also provide the business ID for authentication.

Google Tag Manager: We know that a lot of customers use Google Tag Manager (GTM) to manage their analytics events on their websites. Therefore, we have a built-in and easy to use mechanism to add these to your pages. For those familiar with GTM, you need to provide both your Google Tag Manager Name and your Google Tag Manager ID to make this work.

Google Analytics: This allows you to set up GA easily with your site. Here you can enter the tracking Id associated with your Google Analytics account.

Conversion Tracking: Allows you to enable or disable conversion tracking for this site. This defaults to enabled. There are additional steps you may need to take, which are outlined later.

Session Tracking: Allows you to enable or disable session tracking for all pages. This defaults to enabled where the search session is tracked using session storage and cookies.

User Interactions: Allows you to enable or disable all user interactions for analytics. This defaults to enabled and when set to false, this configuration should prevent any analytics user events from being submitted.

initializeManually: For the runtime config to be used, this toggle will need to set to true.

useJWT: If someone is using the runtime config and requiring a JWT, we’ll also recommend this boolean be set to true to clean the build output of the API key. For more information on JWT, visit our step by step guide .

Note

The locale_config.json file was introduced at the Fall ‘20 release. If you are using a repo from before the Fall ‘20 release, you will instead specify the experienceKey and the locale in the global_config.json file. If you are using a repo from before the Fall ‘20 release and you want to convert your site into a multi-language site, you will need to add a locale_config.json file.