Previewing unpublished content

In this article, you'll learn about a general approach to running your apps in two environments and using the preview environment to preview content from Kentico Cloud. This will enable your content contributors to preview unpublished content directly from your Kentico Cloud project.

To preview your content from your Kentico Cloud project, you will make use of the Delivery Preview API. The Delivery Preview API returns the latest versions of content items allowing your content producers to view content items before they publish them or preview changes made to already published content items.

Table of contents

Content workflow

When content contributors create new content items (such as articles) in the project, the content items begin their content workflow in the Draft step.

A new content item at the beginning of its workflow in the content list.

Right after being created, the new content items become available via the Delivery Preview API.

Using the Delivery Preview API

Every request to the Delivery Preview API must be authenticated with an API key. There are two concurrent keys, Primary and Secondary, unique for each project in Kentico Cloud.

Note: For continuous use, we recommend using the Primary key to authenticate your API requests and only using the Secondary key when revoking the Primary key to prevent your preview environment from any downtime. Both API keys are generated per project and have no expiration date.

Primary vs. Secondary key

The following instructions work equally for both the Primary key and the Secondary key.

To get the key:

In Kentico Cloud, choose a project.

From the app menu, choose Project settings {@icon-settings@}.

Under Development, choose API keys.

In the Delivery Preview API box, click Copy to clipboard {@icon-copy@} to copy the API key.

You can now use the Primary key to authenticate your requests to the API. The base URL of the Preview Delivery API is {~https://preview-deliver.kenticocloud.com/<YOUR_PROJECT_ID>/~}.

The following example shows how you can get the latest version of the "On Roasts" article, as shown in the image above.

As more people work on content, the content items progress through their workflow and, when all requirements are met, can be scheduled for publishing or published right away. Published items then become available via the Delivery API.

Preview and live environments

To preview unpublished content in your app, we recommend running the app in its own environment separated from the live version of the app.

The main difference is that the app running in the live environment uses the Delivery API, while the app in the preview environment uses the Delivery Preview API. To differentiate between the environments in your app, you can, for instance, use environment variables. The way to check the environment variables will depend on the service you use to deploy your apps.

For example, when using one of our Delivery SDKs, the API to use is often determined by providing or omitting the Preview API key. Note that server-side technology (such as ASP.NET MVC, Node.js with the Express.js framework, or others) is required to keep the Preview API key secret.

In practice, your application can check whether it's run in a preview environment, set a boolean flag based on the check, and determine whether to use the Delivery Preview API.

Content preview in Kentico Cloud

With your application running in two separate environments, you can configure preview URLs for the content types in your project and preview content that is not yet published with one click from Kentico Cloud.

Once you set up the URLs, your content contributors can use a preview button {@icon-eye@} when editing new versions of content items. Note that the button is not shown for already published content items.

Changing your project structure

If you change any of the project models (this includes content types, content type snippets, and taxonomy groups), the changes are immediately reflected in the content items.

This means that changes to the project structure cannot be separately tested in preview environment because they directly affect the live environment.

Continuous development

Deploying changes in the structure of a project to another project in order to, for example, test new content layouts, currently cannot be done.

We're working on bringing the support for continuous development to Kentico Cloud in the near future. See our Roadmap to learn more.

What's next?

In this article, you've learned how to set up a preview environment using the Preview API. Once you've configured previews in your project, your content contributors can preview their new content in a separate preview environment before it's published.