Handling Agility URLs

What Are Agility URls?

Agility generates a unique URL to send to your browser whenever a user clicks Preview or View in Live Mode from an item in your instance. It's important to know how these URLs are structured in order to properly handle them.

Preview Mode

In order to initiate preview mode, Agility sends a URL to the user’s browser that has some query strings added to it.

It will look something like this:

https://myside.com/path?ContentID=[ContentID]&lang=[locale]&agilitypreviewkey=[HASHCODE]&agilityts=[timestamp]

  • agilitypreviewkey
    • This is a hashcode generated using the Security Key (which you can find in your API Keys section of settings).
    • The website is responsible for validating this code, which authenticates the browser to initiate preview mode.
  • lang
    • This is the locale code that the user was on in Agility.
    • The website is responsible for displaying the page in the correct locale that the user expects.
  • ContentID
    • This value will not always appear – it’s only used when the user is preview a List Item that has a the Preview URL and Query String parameter set.
    • The website is responsible for redirecting the user to the correct URL for that content item, which can be done using the Sitemap when using Dynamic Pages, or manually if necessary by accessing the item itself and building the URL from scratch.
  • agilityts
    • This is a timestamp value used to bust any caching that might have happened.
    • This value should NOT be necessary, as we recommend that no pages in preview mode should ever be cached.

We recommend storing a session cookie value with a secure token that your site can check in subsequent calls in order to allow the user to navigate through the entire site in preview mode.

We also highly recommend including something visual on your website when it’s in preview mode so that your users will know that they may be seeing staging content that isn’t published yet.

Live Mode

https://myside.com/path?ContentID=[ContentID]&lang=[locale]&AgilityPreview=0

When linking to a page in “Live Mode”, Agility sends a few additional parameters to your site.

  • AgilityPreview
    • This value should have a "0" value.
    • This indicates to your website that, if the user was in preview mode, they should be exited from that mode and back into live mode.
    • The website is responsible for that logic.
  • lang
    • This is the locale code that the user was on in Agility
    • The website is responsible for displaying the page in the correct locale that the user expects
  • ContentID
    • This value operates the same in Live and Preview mode.
    • This value will not always appear – it’s only used when the user is preview a List Item that has a the Preview URL and Query String parameter set.
    • The website is responsible for redirecting the user to the correct URL for that content item, which can be done using the Sitemap when using Dynamic Pages, or manually if necessary by accessing the item itself and building the URL from scratch.

Recommend Articles