Virtual staging and Dynamic Content

About virtual staging

To work with unpublished or work in progress content, Dynamic Content includes a feature called virtual staging. Virtual staging allows you to retrieve unpublished content by using a virtual staging domain in place of the production content delivery domain, while everything else remains the same. You can use virtual staging to retrieve unpublished content with Content Delivery 2, the filter API and the original Content Delivery API.

A virtual staging environment (VSE) will usually be created for you at the start of your project and is associated with the hub from which content is retrieved. A virtual staging domain is generated and configured in the settings on your hub.

Virtual staging is used for visualizations and content previews, allowing you to retrieve the latest version of content, as well as content that is scheduled to go live on a specified date and time.

The following rules apply to retrieving content using virtual staging domains:

  • If you use a virtual staging domain with no timestamp, the latest version of the content is returned.
  • For a content preview, a time stamp (created from the date and time chosen by the user) is encoded in the virtual staging domain that is passed to your content preview app. This is used to retrieve content that is scheduled to be published at the specified time.

Note that you should use the virtual staging API rather than modifying a virtual staging domain directly.

VSEs are also configured to retrieve unpublished images, according to a set of rules that you define. You can find out a lot more about working with unpublished media in the using virtual staging with Dynamic Media section. On this page we'll focus on using virtual staging with Dynamic Content.

Retrieving unpublished content

One way of finding the virtual staging domain associated with your hub is from the visualization settings window in the Dynamic Content app. A virtual staging domain is also shown in the preview settings window and will usually be the same as the one displayed in visualization settings. However, in some cases you may want to have separate environments with different rules configured for preview and visualization.

In the example shown below, the virtual staging domain is kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io

The virtual staging domain is shown in visualization settings
The virtual staging domain is shown in visualization settings

In the example shown below, we have just created a new content item called "Autumn collection".

The content properties window includes the production content delivery URL used to retrieve published content
The content properties window includes the production content delivery URL used to retrieve published content

In the Content Delivery 2 section of the content properties the following URL is displayed and can be used to retrieve the published version of this content.

https://ampproduct-doc.cdn.content.amplience.net/content/id/977f3a7a-e5fc-461a-92fb-0f671eaae571?depth=all&format=inlined

However, in this example, the content has not yet been published, so if we attempt to use the product content delivery URL shown above, an error will be displayed. If we replace the production content delivery domain with the virtual staging domain shown in the visualization settings, then we can retrieve the latest version of this content- in this case the unpublished version we just created.

kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io/content/id/977f3a7a-e5fc-461a-92fb-0f671eaae571?depth=all&format=inlined

This how visualizations use virtual staging to allow you to preview content before it's published. The virtual staging domain and content id is sent to your visualization app, and you can use these to build up a delivery URL to retrieve the content to be visualized.

Virtual staging and content preview

A content preview will show how your web site or app will look at a specified date and time. The preview URL, added from preview settings, will include a token for the virtual staging environment.

You’ll then use the virtual staging domain instead of the production content delivery URL to retrieve content that you want to preview. The content that will be returned is either published or scheduled to go live on the date chosen by the user.

An example content preview dialog is shown in the image below.

You can view the virtual staging domain sent to the content preview app from the preview content window
You can view the virtual staging domain sent to the content preview app from the preview content window

When the user chooses a date and time to preview, this is converted to a timestamp that is encoded in the virtual staging domain sent to your preview app. You can view the preview URL from the content preview window in the "Content link" section. An example preview URL, including a virtual staging domain with timestamp, is shown below:

https://amp-product.s3-eu-west-1.amazonaws.com/tutorials/dynamiccontenttutorials/contentpreviewcdv2.html?api=kuifkfmrgfsv1qjsmei8dbbnq-gvzrfgnzc-1633561200000.staging.bigcontent.io&timestamp=1633561200000&editionid=null

The virtual staging domain sent to the preview app kuifkfmrgfsv1qjsmei8dbbnq-gvzrfgnzc-1633561200000.staging.bigcontent.io is pinned to the date and time chosen by the user. This can be used to retrieve the content scheduled to go live on this date.

Note that if you want to include a date picker control within your preview app to allow the user to change the date from which the preview is shown, you can modify the virtual staging domain to be pinned to a new date using the virtual staging API.

Virtual staging API

You can generate a time stamp, or snapshot specific virtual staging domain via the Virtual Staging API.

The Virtual Staging API accepts the following parameters:

  • timestamp (epoch milliseconds) or snapshotId (string)
  • Base Virtual Staging Environment (Your base VSE is setup by Amplience when your account is created and provided during the onboarding process)

Generating a VSE using a timestamp

To generate a VSE using a timestamp make a GET request to the Virtual Staging service in the following format:

https://virtual-staging.amplience.net/domain/<base-vse-domain>?timestamp=<epoch-millis>

Example:

GET  https://virtual-staging.amplience.net/domain/1vkz2i2i1hlau19hndnr03duvb.staging.bigcontent.io?timestamp=1543598417

This will return a 200 response and the body will be the newly generated API domain name you should use to request content.

Generating a VSE using a snapshotId

You can also use the Virtual Staging service to generate a Virtual Staging domain pinned to a content snapshot (taken from the payload of the snapshot published webhook event, for example).

To generate a VSE using a snapshotId, send a GET request to the Virtual Staging service in the following format:

https://virtual-staging.amplience.net/domain/<base-vse-domain>?snapshotId=<string>

Example:

GET  https://virtual-staging.amplience.net/domain/1vkz2i2i1hlau19hndnr03duvb.staging.bigcontent.io?snapshotId=0cc865a52faff0001987e70

This will return a 200 response and the body will be the newly generated API domain name that you can use to request content.

Video: virtual staging

In this video we explain the concepts of virtual staging and how you can use it to implement your own previews and visualizations.

Usage notes

VSEs should not be used to serve published, production content. If we notice excessive traffic from your VSE it will automatically be rate limited and may be disabled by our operations team. Therefore please ensure that all your production code uses the production domain of cdn.content.amplience.net (for Content Delivery 2) or cdn.c1.amplience.net (for the oiginal Content Delivery API) to serve content to your live environment, and the appropriate media domains such as cdn.media.amplience.netto serve published media.

Content Delivery 2

Filter API

Visualizations

Content preview apps