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).

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.

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

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

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

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

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

• 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

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:

Related pages

Delivery key concepts

Delivery key schema example

Adding properties with the schema editor

Tokens supported by visualizations

Adding a delivery key