Skip to main content

Delivery keys

Delivery keys are strings of up to 150 characters that can be used instead of the content id to retrieve content items and slots. A delivery key can be a simple string or a path such as "home-page/feature-banner". For end users, such as content authors, delivery keys provide an easy to understand unique identifier for the delivery URL.

info

A hub must be enabled for Content Delivery 2 in order for the delivery key feature to be available.

Delivery keys are enabled on a hub. Users can set a key on a content item or slot from the menus in the content library or from the Save menu in the content form. In addition, you can enable users to enter delivery key values in content forms, thus supporting their content creation workflow. To do this you include delivery key fields in content forms.

This example shows a content form where a delivery key field has been included (2), and highlights how a user also has the choice of adding a delivery key from the Save menu (1).

Example of where to add a delivery key in a content form

When a content item or slot is saved, if the delivery key is valid, the properties pane will show the Delivery key and the Delivery key URL to retrieve content using this key.

When the delivery key has been saved the delivery key URL is updated in the properties section

In this example, the content item can be retrieved using the following URL when the content item is published:

https://ampproduct-doc.cdn.content.amplience.net/content/key/home-page/sale-banner?depth=all&format=inlined

Where delivery keys are referenced in your own systems, those delivery key references must be kept in sync with the delivery keys users enter. When a key is updated or removed after an item has been published, the old key still exists and can be used to retrieve the older version of the content. To avoid references in your systems retrieving old content, you should ensure that old keys are replaced or removed.

For information about how to add and update delivery key values with Dynamic Content, see Adding a delivery key.

Planning for delivery keys
Link copied!

Where multiple content authors and producers are each adding delivery keys, it's good practice to have a key naming convention. This helps to maintain consistent, easily identifiable key names. For example, if you have multiple brands, you could outline a simple structure, such as [brand-name]/[slug-name].

You can set up validation for your key naming convention and any other key rules by including the deliveryKey property in your content type schemas. Once validation has been set up for a delivery key field, it is applied whichever way that delivery key value is entered by the user.

Delivery keys are case sensitive and must follow the delivery key validation rules.

Adding a delivery key field to a content form
Link copied!

Allowing users to add or edit a delivery key directly in a content form field has several advantages:

  • It allows users to add a delivery key directly into content as part of their normal authoring flow.
  • You can give the delivery key field a friendlier name such as url, or blog slug to provide more context for the user.
  • You can apply custom validation on the delivery key to ensure that it's valid for your particular use case. Note that the validation must not conflict with the system validation rules.

Including the deliveryKey property in a content type schema
Link copied!

To allow delivery keys to be entered with the content form for content items and slots, you must include the deliveryKey property in the relevant content type schema. Here's an example of a deliveryKey property in a content type schema:

 "_meta":{
"type":"object",
"properties":{
"deliveryKey":{
"type":"string",
"title":"Delivery key",
"description": "Enter the delivery key for this item"
}
}
}

The delivery key must be included in the _meta property, and the property name must be deliveryKey in order for its field to be shown. You can include your own title and description if you want to give it a more friendly name.

You can include the _meta property at any point in the properties list and use the propertyOrder keyword to ensure your fields are displayed in the order you choose.

You can include additional validation on the deliverykey property, but ensure that it doesn't conflict with the system validation rules.

Required delivery keys and copying

If you make a delivery key a required field in a content type schema, any content items or slots created by users from that content type cannot be copied. Instead a schema validation notification is displayed informing the user that the item cannot be copied.

See Adding properties with the schema editor.

Valid delivery keys
Link copied!

Delivery keys must pass system validation rules defined by Amplience. You can add additional validation too, for example to enforce naming conventions. The validation rules apply for keys whichever way they are entered. If a delivery key is invalid, an error message is shown and you can't save the content item or delivery key until the key is valid.

System validation rules
Link copied!

  • Each delivery key must be unique within a hub
  • Keys must be between 1 and 150 characters long
  • Delivery keys must contain valid alphanumeric characters only:
    • a to z, A to Z and 0 to 9
    • _ and -, and / (but not at the start or end of a delivery key)
  • Spaces are not permitted

Note that delivery keys are case sensitive.

Additional validation
Link copied!

If a regular expression provides extra delivery key validation, for example to ensure keys follow a naming convention, the keys must match the pattern.

For example, if a pattern of home-page/.* is set in a content type schema:

 "_meta":{
"type":"object",
"properties":{
"deliveryKey":{
"title": "Delivery key",
"description": "Enter a key starting with home-page/",
"type": "string",
"pattern": "home-page/.*"
}
}
}

Attempting to enter a delivery key that doesn't match the pattern, for this example, "home/sale-banner" instead of "home-page/sale-banner", will cause an error:

Additional validation for a delivery key

Unpublishing and delivery keys
Link copied!

If you want to change or remove a delivery key after publishing a content item, you will need to unpublish the item first- unless you are reusing the key on another item.

Unpublishing a content item makes it easy to manage the availability of delivery key URLs, but the order in which you unpublish a content item and remove the delivery key is important.

To remove or update a delivery key when an item is published:

  • Unpublish the content item. The item can no longer be retrieved using its published Content Delivery URL.
  • Remove the delivery key by setting it to an empty string, or change it to a new value.
  • Publish the content item. It can now be retrieved using its new delivery key URL.

Note: If you remove the delivery key before unpublishing the content item, it will remain available via its original published delivery key URL. To remove such an "orphaned" delivery key, add it to another content item, publish the item to which you added the key and finally unpublish it.

Reusing a delivery key
Link copied!

Reusing a delivery key on a different content item, requires slightly different steps as you may want the original content to remain available at the delivery key URL until the new item is published.

  • Remove the delivery key from the original content item by setting it to an empty string.
  • Add the delivery key to the new content item.
  • Publish the new content item. It can now be retrieved using the deliveryKey URL, replacing the original item.

Note: You can republish the original item if you still need to consume it via its delivery ID.

Delivery key concepts

Delivery key schema example

Adding properties with the schema editor

Tokens supported by visualizations

Adding a delivery key