Applications

In Optimizely Content Management System (CMS), an application represents any website or frontend that runs on the CMS instance. Examples include a website, a headless frontend, and a campaign microsite. Use Applications to configure and manage one or more applications, including preview settings, hostnames, and routing roots.

Unlike tightly coupled front- and back-end architectures, CMS does not impose routing conventions. Routes are paths that determine how an application responds to a client request for a particular endpoint. Design routes to suit your use case.

Application benefits

Create applications in the following scenarios to ensure that CMS remains organized, scalable, and aligned with your specific business needs:

• Isolated management – Manage each application independently with specific configurations, settings, and content structures.
• Enhanced organization – Keep the CMS organized, especially when dealing with multiple applications or projects.
• User experience – Improve navigation and content management, making it easier for developers and marketers to work on specific applications without interference.
• Flexibility – Use a headless CMS approach, letting you build applications without being tied to a traditional CMS structure.
• Scalability – As your business grows, add applications to scale with your needs.

When to create an application

• Launch a new application – Create a separate application to manage independently from other applications.
• Multi-application management – Manage multiple applications under a single CMS instance by setting up each application as a separate application, providing better organization, dedicated settings, and easier-to-manage content for each application.
• Headless CMS implementation – Create an application to manage different front-end applications that consume content from CMS when you are implementing a headless CMS configuration (where the front end is decoupled from the back end).
• Marketing and campaign applications – Create an application to ensure that applications have their own specific configurations, content, and tracking for temporary or permanent marketing campaign applications.
• Internationalization – Create a separate application to manage localization settings for different regions or languages and content more efficiently.
• Development and preview environments – Create a separate application when you want to configure development or preview environments for new features to maintain a clean separation from the production environment.

Create an application

Create an application to give a website or front end its own start page, settings, and routing within the CMS. Each application keeps content, hostnames, and previews isolated from other sites in the same instance.

1. Go to Settings > Applications.

2. Click Create Application.

   
   • Application Name – Enter the name of the application (analogous to a website). The name must begin with a letter and contain only alphanumeric characters. Click change to modify the automatically generated API ID.
   • Type – Select the type you want to use.
     • Select Headless for this application if you want to manage content in Optimizely but build and host your own custom frontend using APIs.
     • Select In Process for this application if you want Optimizely to manage both your content and directly render your application's frontend.
   • Choose Start Page – Select the start page from the content tree. 
     • From Existing – Select a start page from the page tree that displays.
     • New – Select a start page from a list of Experiences and Page Types.

3. Click Create Application. The application is added to the Applications list.

Configure an application

Configure an application to set its hostnames, start page, asset scope, and live preview behavior. These settings control how visitors reach the site and how editors preview unpublished content.

Configure general settings

General settings define the application's identity. Configure the name, default status, asset scope, API identifier, and start page. The CMS and APIs use these values to reference the application.

1. Click the application name in the Application list (or select More (…) > Edit). The Settings window displays.

   
   • Application name – Enter the application name or the application's start page.
   • Set as default application – The default application is the one users are directed to by default if no specific application is specified.
   • Enable application-specific assets – Select to ensure that this site's assets, such as blocks and media, are not available for use on other sites in the installation. This option affects the folder structure editors see in the assets panel.
   • API ID – Specify a unique identifier for the application that is used in API calls. This ID is typically used to reference the application programmatically within the system, allowing for integration and communication with other services or components. In the screenshot, the API ID is set to "remote," indicating that this is the identifier for the application named "Remote website."
   • Change Start Page – Select the page to which the visitor is sent if only a hostname is specified.
   • Delete Application – Click to delete the application and remove it from the Application list.

Configure hostnames

Hostnames map URLs to the application so visitors reach the right content. Each application supports multiple hostnames for live, preview, media, redirect, and edit scenarios.

1. Open the application's Settings window, then select the Hostnames tab.

2. Click Add Hostname to open the Add Hostname pane.

   

   • Type – Select the type of hostname.

     • For headless applications, you have the following options:
       • Primary – Designate the main hostname for a site when there might be multiple hostnames configured. It can serve as the canonical URL for a site or be used for specific internal routing logic. Select if you want this hostname to be the live, public-facing URL where your final, published content and application are accessible to all end-users.
       • Preview – Configured for content previewing, and used by CMS editors to view unpublished content, drafts, or content in specific contexts before it is published live. It requires special routing and security mechanisms, such as preview tokens. Select if you want this hostname to be a staging or development URL used for reviewing content and application changes before they go live on your primary.
       • Media – Dedicated to serving media files (images, videos, documents). It might have specific configurations for caching, CDN integration, or optimized delivery of digital assets.
     • For traditional (in-process) applications, you have the following options:
       • Default – The primary public-facing hostname for your website. It's the main URL where regular visitors access the live content. In a multi-site configuration, one site is usually designated as the default.
       • Primary – Similar to Default, but often used to designate the main hostname for a site when there might be multiple hostnames configured. It can serve as the canonical URL for a site or be used for specific internal routing logic.
       • Preview – Configured for content previewing, and used by CMS editors to view unpublished content, drafts, or content in specific contexts before it is published live. It requires special routing and security mechanisms, such as preview tokens.
       • Media – Dedicated to serving media files (images, videos, documents). It might have specific configurations for caching, CDN integration, or optimized delivery of digital assets.
       • Edit – Exclusively for accessing the Optimizely CMS editing interface. It's the URL where content editors log in and manage content.
       • RedirectPermanent – Used to configure a permanent HTTP 301 redirect from one URL to another. This is crucial for SEO when a page's URL has permanently changed, ensuring search engines and browsers are directed to the new location.
       • RedirectTemporary – Used to configure a temporary HTTP 302 redirect from one URL to another. This is used when a URL change is temporary, indicating to search engines that the original URL might return in the future.

     📘

     Note

     The Media, Edit, and Preview host types are configured as language-agnostic and are restricted to a single instance per application.

   • Hostname – Enter a unique name of between 2 and 225 characters (letters, numbers, periods, underscores, hyphens, and an optional port number such as hostname:8080) for a new primary host. Do not include http:// or https:// in the name; use the Use a Secure connection (HTTPS) checkbox for that.

     Hostnames are resolved in the following order of precedence:

     1. Media
     2. Primary (language match)
     3. Default (language match)
     4. Primary (no language specified)
     5. Default (no language specified)
     6. Current/Default (fallback)

   • Use a Secure connection – Select for HTTPS. Clear for HTTP.

   • Locale – Select a locale. Displays only if you selected **Type **> Primary.

     • Only one hostname can be primary per locale. If the selected locale already exists for another hostname, you are asked to confirm that you want to change the primary hostname for the selected locale. For example, if Oldtown has a locale of English (en) and you add a Newton hostname with locale English (en), you are asked to confirm changing the primary hostname from Oldtown to Newton.
     • To have URLs indexed without a language segment (transforming example.com/en/my-page to example.com/my-page), map the hostname to the desired language. For example, map example in example.com to the language en. 

3. Click Add. The hostname is added to the list.

   

   📘

   Note

   If you change hostnames, go to Settings > Scheduled Jobs and run the Optimizely Graph Full Synchronization job to update links for all content items.

Configure live preview

Live preview lets editors view unpublished content in the rendered application before publishing. Configure preview tokens and content type rules to control how the preview behaves.

1. Open the application's Settings window, then click Live Preview. The Live Preview panel displays.

   

   • Use Preview Tokens – Automatically append preview tokens to the preview URL you use. Preview tokens are reusable and validated against user permissions rather than specific content references. See the Modify the default token to create a custom preview section below.

     📘

     Note

     Previously, preview tokens were issued for specific content references. Instead of validating the preview token's content reference with the currently routed content reference, you can now validate the preview token principal's permissions to the routed content.

   • Enabled – Any is selected by default, but you must select Enabled to display the preview because you can customize the preview as follows.

   • Add (+) – Click to add a selected Content Type row with a custom URL. Any is the default. If you remove the URL, you can preview only the items you specify.

     

Modify the default token to create a custom preview

When an editor is in the CMS and wants to preview content, the CMS generates a preview token. This token is appended to the URL of your front-end application (for example, yourdomain.com/preview?preview_token=eyJ...). Your front-end application (built with React or Next.js, for example) detects this preview_token in the URL. It then includes this token in the Authorization: Bearer {token} header when making GraphQL requests to Optimizely Graph. Optimizely Graph uses this token to return the appropriate content, including unpublished drafts, based on the editor's access rights. This mechanism allows for secure and context-aware live previews within the CMS.

The following examples show custom preview token configurations:

• Add a custom preview by modifying the default token (adding experience to the token).

• Leave the token field blank to disable preview (for blocks, for example).

• Add a verceltoken parameter to integrate with Vercel’s preview environment.

Delete an application

Delete an application to retire a site and remove its routing, hostnames, and configuration from the CMS. Removing unused applications keeps the Application list focused on active properties.

1. Click the name of an application in the Application list (or select More (…) > Edit) to configure the application. The Settings window displays.
2. Click Delete Application.
3. Confirm the deletion. CMS removes the application from the Application list.