Global Settings and Local Configuration | Yext Hitchhikers Platform

The first thing you’ll want to do once you set up your Search site 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 search experiences and are where you specify things that are shared across all pages, like the experienceKey, sdkVersion, favicon or Google Tag Manager (GTM) ID.

locale_config.json File

Updating the locale_config.json is required in order to get your experience working. Specifically, you will need to update the Experience Key property.

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.

You can find this experience key by navigating to Search > Your Experience > Experience Details. 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}"
  }
}

Property Description

default This is the locale code for your experience. This should align with the language code for your entities in Content. 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 experience keys 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.

Property	Description
`default`	This is the locale code for your experience. This should align with the language code for your entities in Content. 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 experience keys 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
}

Property	Description
`sdkVersion` (Required)	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.
`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.
`favicon`	Add a url or asset reference, just like you did for the logo.
`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.
`businessId`	If you set an API Key from another business, please also provide the business ID for authentication.
`googleTagManagerId` and `googleTagManagerName`	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.
`googleAnalyticsId`	This allows you to set up GA easily with your site. Here you can enter the tracking Id associated with your Google Analytics account.
`conversionTrackingEnabled`	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.
`sessionTrackingEnabled`	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.
`userInteractionsEnabled`	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 .

Back

< Theme Repo Structure

Common Console Errors >

Feedback

<% elem.innerText %>