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. The delivery key can be a simple string or a path such as "home-page/feature-banner". You can change the delivery key that is associated with a slot or content item, but the item must be republished before the updated key can be used to retrieve its content.

note

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

Adding a delivery key

There are several ways of adding a delivery key to a content item or slot in the Dynamic Content app. Which method you use will depend on what best suits your workflow.

• Adding or updating the delivery key in a field in the content editing window.
• Choosing "Delivery key" from the "Save" menu in the content editing window.
• Choosing "Delivery key" from the content item's menu in the Content Library.

Delivery keys must be between 1 and 150 characters and follow the delivery key validation rules. The path delimiter "/" can be included in the key, but not as the first or last character. Keys must also be unique within the same hub.

Adding a delivery key to a field in the content editing window

Allowing your users to add or edit a delivery key directly in a field in the content editing window 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 a friendlier name such as url, or blog slug to provide more context for the delivery key field.
• 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

You need to include the deliveryKey property in the content type schema for any content item for which you want to allow the key to be entered as a field in the content editing window. The deliveryKey property should be defined as follows:

 "_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 validation on the deliverykey property, but ensure that it doesn't conflict with the system validation rules. If you do add your own validation, then this will be applied no matter what method is used to add a delivery key.

Adding the key

To add a delivery key from the content editing window, create a new content item by choosing "Create content" in the Content Library or open an existing item for editing. You can then enter the delivery key in its field, as shown in the example below.

If there is already a delivery key assigned to the item then it will be shown in the delivery key field and you can edit it if you need to.

When you click "Save", if the delivery key is valid, the content item is saved and the properties pane will be updated to show the 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/main-page/promo-banner?depth=all&format=inlined

If the delivery key is not valid, for example if it starts with "/" then an error will be displayed and the content item cannot be saved until the key is valid.

Adding a delivery key from the Save menu

To add a delivery key from the Save menu in the content editing window, double-click the item in the Content Library and choose "Delivery key".

In this example we're adding a delivery key to a slot, but you can add a delivery key to a content item in the same way.

Enter your chosen key in the Delivery key window. The key must follow the validation rules and a content item with an invalid delivery key cannot be saved

In this example we are setting the delivery key to "home-page/main-feature-slot".

Click "Save" to assign the delivery key to the slot.

When the delivery key is saved, the properties pane is updated to include delivery URLs to get the slot by id and by delivery key. You will need to publish the slot before you can use the production delivery URLs.

With the slot published, the following URL can be used to get the slot using its delivery key:

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

Adding a delivery key from the Content Library

In this example we'll add a delivery key to the winter banner content item from the item's menu in the Content Library, as shown in the image below.

For this example the delivery key is set to: "home-page/feature-promo-banner".

When the delivery key has been added, the URL to retrieve the item, using either its id or the delivery key, is shown in the properties pane. The content item must be published before it can be retrieved using the production delivery key URL.

The following URL will retrieve the banner content using its delivery key.

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

Updating a delivery key

You can update a delivery key once it's set using any of the ways in which you can add a delivery key to a content item or slot.

In the example below we're changing the key to "promo-page/main-feature-slot" to change the location in which the slot is displayed. To delete a delivery key, just enter an empty string.

A content item or slot can only be retrieved using an updated delivery key, once it's been re-published.

Valid delivery keys

When you enter the delivery key for a slot or content item, that key must pass some validation rules.

• Delivery keys must be between 1 and 150 characters in length

• Delivery keys must not:

  • contain invalid characters.
  • start or end with "/".
  • contain spaces.

Delivery keys can contain the following alphanumeric characters: a to z, A to Z and 0 to 9. You can also include "-" and "_" and "/" as long as it is not included at the start or end of the key.

If the delivery key contains invalid characters, then a warning message will be displayed.