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.

You can also add multiple delivery keys to a content item.

info

A hub must be enabled for Content Delivery v2 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":{
    "title": "Delivery key",
    "type":"object",
    "properties":{
      "deliveryKey":{
        "title": "Key for URL",
        "description": "Enter the key to be used in the delivery URL",
        "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:

Unpublishing and delivery keys

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.

Currently you can only remove a delivery key from the dialog shown when you choose "Delivery key" from the menu in the authoring experience, or from a content item's ellipsis menu in the Content Library.

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

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.

Multiple delivery keys

One use for delivery keys is to represent a URL in a content managed website. Adding support for multiple delivery keys makes it easier to manage URLs for localized versions of website pages. These URLs can be included in web page metadata to inform search engines about language and region specific variants of a page.

To support multiple delivery keys you need to include a deliveryKeys property to your content type schemas to represent an array of delivery keys. An example is shown below, with the minimum length of the array set to 4.

"_meta":{
      "type":"object",
      "properties":{
         "deliveryKeys":{
            "type":"object",
            "properties":{
               "values":{
                  "type":"array",
                  "items":{
                     "type":"object",
                     "minlength":4,
                     "properties":{
                        "value":{
                           "type":"string"
                        }
                     }
                  }
               }
            }
         }
      }
   }

Note that deliveryKeys is not a localized array, so each delivery key is not linked to a locale. You will need to use a naming convention to map each delivery key to the a locale.

Multiple delivery keys- example

An example of a content form created from a content type schema that supports multiple delivery keys is shown below. It's for the shoes section of a website with localized delivery keys for several languages. URLs representing each locale are shown in the meta section of the content form.

The content item also includes a localized string so that you can enter a title for each locale. This would then need to be mapped to the corresponding delivery key.

You can find the full example on the multiple delivery keys- schema example page.

Retrieving content using a delivery key

You can retrieve a content item using any one of its delivery keys using the Content Delivery API. In the following example we're retrieving a content item using the delivery key fr/hommes/chaussures.

https://sfccamplienceproduct.cdn.content.amplience.net/content/key/fr/hommes/chaussures?depth=all&format=inlined

The JSON response is shown below. All of the delivery keys are returned in the meta section. These delivery keys could be used to populate hreflang element in the shoes website page to improve the website SEO for different languages and regions.

{
  "content": {
    "_meta": {
      "schema": "https://localised-field-with-deliverykeys.schema-example.com",
      "name": "Localised field with deliverykeys - shoes",
      "deliveryKeys": {
        "values": [
          {
            "value": "en/men/shoes"
          },
          {
            "value": "fr/hommes/chaussures"
          },
          {
            "value": "it/uomo/scarpe"
          },
          {
            "value": "de/herren/schuhe"
          }
        ]
      },
      "deliveryId": "c997b7ff-173f-46c3-be54-3b85e0d79a83"
    },
    "Title": {
      "values": [
        {
          "locale": "en-GB",
          "value": "Mens Shoes"
        },
        {
          "locale": "fr-FR",
          "value": "Chaussures pour Hommes"
        },
        {
          "locale": "it-IT",
          "value": "Scarpe da uomo"
        },
        {
          "locale": "de-DE",
          "value": "Herrenschuhe"
        }
      ],
      "_meta": {
        "schema": "http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
      }
    }
  }
}

Usage notes

• As with single delivery keys, each delivery key among multiple delivery keys must be unique across a hub. Adding a duplicate delivery key will result in an error.

Related pages

Delivery key concepts

Delivery key schema example

Multiple delivery keys schema example

hreflang property

Adding properties with the schema editor

Tokens supported by visualizations

Adding a delivery key