Experience Config

8 min

The main configuration for any Purple Experience is done in a file called experience.config.json. It is located in /storefront/assets within the dynamic content. Any data you put here is available to your app via the Global Data object. As it is part of Dynamic Resources, this configuration is generally also available in offline cases. (Note that a version of this file is bundled with the app. Thus, when downloading and app and accessing it in offline mode, upon first start, it might be outdated.)

It is mainly used to configure features of PXP inside the purple element but the configuration you place in this file is generally ubiquitous, and available on any PXP page. So it may also be used to configure custom keys on the top level that are necessary in a project.

All of the configuration keys in the purple object are optional and should only be set if a certain configuration is needed.

Example config file

This code snippet will need to be modified according to the needs of the project.

{
  "language": "en",
  "custom_title": "Hello world",
  "purple": {
    "analytics": {
      "ga4": {
        "configuration": {
          "measurementId": "Provided by Google Analytics 4"
        },
        "consent": {
          "vendorId": "CustomId matching the used CMP",
          "iabVendorId": "iab Id"
        }
      }
    },
    "consentManagement": {
      "cmpProvider": "consentmanager",
      "cmps": {
        "consentmanager": {
          "configuration": {
            "codeId": "Provided by Consent Manager",
            "cmpHost": "Provided by Consent Manager",
            "cmpCdn": "Provided by Consent Manager",
            "cmpBlockIgnoreDomains": []
          }
        }
      }
    }
  }
}

Available Settings

Unless specified otherwise, all the following configuration happens inside the purple object.

Preconnects

see Preconnects.

Website locale

For SEO and accessibility reasons, we recommend that you set the locale for your website explicitly. You can simply do this by adding, i.e. "language": "de" to the top level of experience.config.json. This will then be added to your website's HTML as <html lang="de">.

Please refer to https://www.w3.org/International/articles/language-tags/ for further information on locales in general.

Tracking Systems

Most Third-party tracking Systems must be set up in both experience config in the analytics object and purple manager. For details, see Tracking and Analytics and refer to the detailed steps for the individual trackers. Note that you must set up the tracking config as well, to map events from the purple system to the tracker. This setup allows the changing of trackers with limited adjustments in your tracking logics.

CMP

Most Consent Management Platforms must be set up in both experience.config in the consentManagement and purple manager. For details, see Consent Management App & Web.

Features

Configured inside the features object. Currently available keys:

spa: Controls whether to use Single Page Application (SPA) routing or to load the full page on every navigation. When false, navigation actions (NAVIGATE, OPEN_CONTENT, OPEN_URL) will trigger full page reloads. When true or not set, uses SPA routing (default behavior).

lazyScrollRestoration: Controls whether to disable the lazy scroll restoration retry mechanism. When true, the scroll restoration will not retry if the initial position is not reached. When false or not set, uses the default retry behavior.

Scripts

Using the scripts object, it is possible to add additional script tags to the head or body. Each script configuration provides a key-value pair which then will be rendered as attributes of said script tags. Tags without value (e.g. async) should be configured with an empty string or null. Using booleans as values is not allowed and may result in unwanted behavior since the boolean will just be stringified. Example:

{
  "purple:" {
    "scripts": {
      "head": [
        {
          "id": "123",
          "src": "https://example.com/myHeadScript.js",
          "async": ""
        }
      ],
      "body": [
        {
          "id": "456",
          "src": "https://example.com/myBodyScript.js",
          "data-setting": "abc"
        }
      ]
    }
  }
}

Caches

Inside the caches key, it is possible to globally overwrite the default api cache duration using apiMaxAge in ms (default 60000, meaning one minute). Apart from that, each data source can define its duration itself.

Legacy flags

The legacy object is a place, where we put feature flags of old features which we intented to sunset but still support for a limited time.

Presenter

The presenter config is a place where configuration for the web presenter lies which was previously set up in the Purple Manager. These are configuration fields which are rarely used and should only be set when the default is not suitable.

contentFitStrategy: The fallback content fit strategy when the content does not provide its own. Defaults to fitIside

contentMaxWidth: Max width for the presenter in px.

purchasePreviewUrl: URL to be redirected to in preview issues when navigating outside of the preview area of the issue.

downloadFileName: Format of the downloaded file name. Possible values and their format, defaults to publication_issue:

publication_issue -> <publication> - <issue>[ - <page>].<ext>

issue -> <issue>[ - <page>].<ext>

original -> the attachment's own filename, unchanged