Content widget object | Documentation

A content widget object (or simply "widget object") describes an actual widget. In particular, its id is the widget ID. There is a basic user interface for creating managing widget objects, but it is also possible to use the API directly.

A content widget object may have the following fields. If a field is not specified when the widget is created, its value will be null. If a field is not specified in an update, this field's value will not be changed. If a field is missing when read back from the server (in the response to a create, read or update), it means that its value is null.

Name	Type	Description
`id`	String	Identifier of the content widget.
`siteGroupId`	String	Site group of this widget.
`description`	String	Short description of the widget.
`enabled`	Boolean	If false, no impressions will be delivered for this widget. New widgets are enabled by default.
`settings`	Object	Detailed settings for this widget, described below.
`lastUpdatedBy`	String	Email address of the last person to update the widget.
`lastUpdatedAt`	String (Date)	Time of the last update to the widget (ISO 8601 timestamp).
`annotations`	Array of Object	Array of key value pair objects. Used for storing custom metadata.
`history`	Array of Object	List of previous revisions.

Annotations

List of key value pairs. Max size of list is 1000.

Name	Type	Description
key	String	Must be unique and less than 256 characters. Must start with a letter and can only contain ascii characters a-z, A-Z, 0-9 or _ (underscore).
value	String	Less than 256 characters

Notes

If lastUpdatedBy and/or lastUpdatedAt is specified when the widget object is created, it has no effect. But if this is specified in an update, it has to match the current values for the update to succeed. This can be seen as a form of optimistic concurrency control. However, we cannot currently make any guarantees when there are several conflicting updates to the same object at the same time.
The history field is only included in the response when individual widget objects are read or updated, and only if changes have been made to this object since December 8, 2013 (when this field was added). It contains up to 50 previous revisions, in reverse chronological order. These revisions are themselves widget objects – except that they do not contain the fields id, siteGroupId and history. The history field is ignored when a widget object is created or updated.
Deleting widgets now requires special privileges, but you can get old widgets "out of the way" by setting enabled to false. In particular, they will no longer be visible in the Content Application. A disabled widget can be (re)enabled by setting enabled to true.

A widget settings object may have the following fields. Observe that at this level, if a field is not specified in an update, it is treated as null. Hence, the field's value may be changed.

Name	Type	Required	Description
`type`	String	Yes	The widget type. Currently always "basic".
`size`	Integer	No (default value)	The number of items (i.e. recommendations) in this widget.
`siteId`	String	Yes	The site where this widget will occur.
`contentId`	String	No	The content configuration for this widget.
`templateId`	String	No	The template object for this widget.
`styleId`	String	No	The style object for this widget.
`timeout`	Integer	No	A value indicating the maximum time limit in milliseconds to process this request, not counting network latency or queue time. Should be used when a quick response, possibly with lower quality, is preferred. Best practice is to not set this configuration, and rather allow automatic handling of optimal timeout. The value must be in the range <0,10000].

Notes

The fields templateId and styleId are used instead of (mapped) render templates if you specify renderTemplateUrl: 'auto' in your call to insertWidget.

Last updated: December 28, 2023