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 unless you’re ready to build multi-language experiences.

You can find this experience key by navigating to Search > Your Experience > General Settings. 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 three main properties. Check out the Multi-Language Search Frontend unit for more info on setting up these properties.

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.
`urlFormat`	This determines the url format of the pages that are generated.

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.16", // The version of the Answers SDK to use
  // "token": "<REPLACE ME>", // |e
  // "apiKey": "<REPLACE ME>", // The answers api key found on the experiences page. This will be provided automatically by the Yext CI system
  // "experienceVersion": "<REPLACE ME>", // the Answers Experience version to use for API requests. This will be provided automatically by the Yext CI system
  // "environment": "production", // The environment to run on for this Answers Experience. (i.e. 'production' or 'sandbox')
  // "cloudRegion": "us", // The cloud region to use for this Answers Experience. (i.e. 'us' or 'eu')
  // "cloudChoice": "multi", // The cloud provider to use for this Answers Experience. (i.e. 'multi' or 'gcp')
  // "businessId": "<REPLACE ME>", // The business ID of the account. This will be provided automatically by the Yext CI system
  // "initializeManually": true, // If true, the experience must be started by calling AnswersExperience.init() or AnswersExperienceFrame.init() for iframe integrations.
  // "useJWT": true, // Whether or not to enable JWT. If true, the apiKey will be hidden from the build output and the token must be specified through manual initialization.
  "sessionTrackingEnabled": true, // Whether or not session tracking is enabled for all pages
  "analyticsEventsEnabled": true, // Whether or not to submit user interaction analytics events
  "logo": "", // The link to the logo for open graph meta tag - og:image.
  "favicon": "",
  "googleTagManagerName": "dataLayer", // The name of your Google Tag Manager data layer
  "googleTagManagerId": "", // The container id associated with your Google Tag Manager container
  "googleAnalyticsId": "", // The tracking Id associated with your Google Analytics account
  "conversionTrackingEnabled": true // Whether or not conversion tracking is enabled for all pages
}

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.
`token`	The auth token to access Search experience.
`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.
`experienceVersion`	The Search Experience version to use for API requests. This will be provided automatically by the Yext CI system
`environment`	The environment to run on for this Search Experience. (i.e. ‘production’ or ‘sandbox’)
`cloudRegion`	The cloud region to use for this Search Experience. (i.e. ‘us’ or ‘eu’). You must be on Theme v1.31 or above to set the cloud region.
`cloudChoice`	The cloud provider to use for this Search Experience. (i.e. ‘multi’ or ‘gcp’). You must be on Theme v1.34.3 or above to set cloud choice.
`businessId`	If you set an API Key from another business, please also provide the business ID for authentication.
`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 .
`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.
`analyticsEventsEnabled`	Whether or not to submit user interaction analytics events. This defaults to enabled and when set to false, this configuration should prevent any analytics user events from being submitted.
`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.
`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.

Back

< Theme Repo Structure

Common Console and Preview Errors >

<% elem.innerText %>