Banner Properties and API fields

This page describes the properties that can be set or retrieved for banners when using the Revive Adserver REST API. The order of this page follows the order of the fields in the Revive Adserver user interface.

Banner ID

Field name: bannerId

Description: The unique ID of a banner. Once a banner has been created and a unique banner ID has been assigned, the ID can not be changed.

Usage:

  • Omit when adding a new banner;
    the ID of the newly created banner will be part of the API response, enabling developers to record it in their own application and use it later for other purposes. Example:

    "bannerId": "1"
  • Include an existing banner ID in the API URL when retrieving a banner, modifying a banner, deleting a banner

Campaign ID

Field name: campaignId

Description: The ID of the campaign the banner is part of.

Usage:

  • Omit when adding a new banner;
    Specify the ID of the campaign that the new banner needs to be part of. Example:

    "campaignId": 2
  • When retrieving a banner’s properties, the campaignId is included in the response

Banner type

Field name: storageType

Description: the type of banner.

Type: string

Allowed values:

  • For an image banner, with the image stored in the file system:
    "storageType": "web"

    (currently not supported)

  • For an image banner, with the image stored in the database:
    "storageType": "sql"

    (currently not supported)

  • For an image banner, referring to an externally hosted image referenced by URL:
    "storageType": "url"
  • For an HTML banner:
    "storageType": "html"
  • For a text ad:
    "storageType": "txt"
  • For an inline video ad:
    "storageType": "video"

Banner name

Field name: bannerName

Description: the name of the banner.

Type: string, maximum 255 characters

Usage example:

"bannerName": "Demo Image Banner 1"

Note: inside the rv_banners table, the column representing this field is called ‘description’

Filename

Field name: filename

Description: the filename of the banner image (applicable only if storageType = “web”)

Type: string, maximum 255 characters

Usage example:

"filename": "79498bab5704ecabf9f3a099a63f57a2.gif"

Note: the file name is randomly generated when a banner image file is uploaded via the web user interface, so that the image can be stored even when another banner is uploaded later that has the same original name.

Image URL

Field name: imageURL

Description: the URL of the banner image (applicable only if storageType = “url”)

Type: string, maximum 255 characters

Usage example:

"imageURL": "https:\/\/www.reviveadserverrestapi.com\/images\/leaderboard.gif"

Note: The content must be properly escaped.

HTML banner code

Field name: htmlTemplate

Description: the HTML code of the banner (applicable only if storageType = “html”)

Type: string, maximum 65K characters

Usage example:

"htmlTemplate": "html code goes here"

Note: The content must be properly escaped.

Destination URL

Field name: url

Description: The URL of the destination when clicking on a banner during ad delivery

Type: string

Usage example:

"url": "https:\/\/www.reviveadserverrestapi.com\/"

Notes

  • Setting a destination URL is optional, if there is no destination URL, the banner can not be clicked (HTML and HTML5 banners are an exception)
  • Special characters should be properly escaped.

Target

Field name: target

Description: (optional) An identfier of the window or tab in which the destination URL must be opened. Leave blank to open the link in a new tab, use _top or _self to open in the same window. It is not necessary to enter _blank, since that’s the default behavior.

Type: string, maximum 16 characters

Usage example:

"target": ""

Alt text

Field name: alt

Description: (optional) The ‘alt’ text that a browser can display when the visitor points their mouse at the banner

Type: string

Usage example:

"alt": "Revive Adserver REST API"

Text below image

Field name: bannerText

Description: (optional) A text that can be display below the banner image during ad delivery (not recommended)

Type: string

Usage example:

"bannerText": "Text below Demo Image Banner 1"

Banner Width

Field name: width

Description: The width of the banner (expressed in pixels)

Type: integer

Usage example:

"width": 728

Banner Height

Field name: height

Description: The height of the banner (expressed in pixels)

Type: integer

Usage example:

"height": 90

Weight

Field name: weight

Description: The weight of a banner, used to control the selection of the banner relative to the sum of the weights of all banners of the same campaign

Type: integer

Usage example:

"weight": 1

Comments

Field name: comment

Description: A comment about the banner

Type: string, maximum length 65,535 characters

Syntax example:

"comments": "A banner comment goes here."

Notes

  • The ‘iframe friendly’ setting introduced in Revive Adserver v3.2.x is currently not supported in this REST API

Examples

Below are a number of examples of banner type and their full response array when retrieved via the Revive Adserver REST API.

Image banner

{
    "bannerId": "1",
    "campaignId": "1",
    "bannerName": "Demo Image Banner 1",
    "storageType": "web",
    "imageURL": "",
    "htmlTemplate": "",
    "width": "728",
    "height": "90",
    "weight": "1",
    "target": "",
    "url": "https:\/\/www.reviveadserverrestapi.com\/",
    "bannerText": "Text below Demo Image Banner 1",
    "status": "0",
    "adserver": "",
    "transparent": "0",
    "capping": "0",
    "sessionCapping": "0",
    "block": "0",
    "aImage": null,
    "aBackupImage": null,
    "comments": "",
    "alt": "Revive Adserver REST API",
    "filename": "79498bab5704ecabf9f3a099a63f57a2.gif",
    "append": "",
    "prepend": ""
}

External Image banner

{
    "bannerId": "2",
    "campaignId": "1",
    "bannerName": "Demo External Image Banner 1",
    "storageType": "url",
    "imageURL": "https:\/\/www.reviveadserverrestapi.com\/images\/leaderboard.gif",
    "htmlTemplate": "",
    "width": "728",
    "height": "90",
    "weight": "1",
    "target": "",
    "url": "https:\/\/www.reviveadserverrestapi.com\/",
    "bannerText": "",
    "status": "0",
    "adserver": "",
    "transparent": "0",
    "capping": "0",
    "sessionCapping": "0",
    "block": "0",
    "aImage": null,
    "aBackupImage": null,
    "comments": "",
    "alt": "Revive Adserver REST API",
    "filename": "",
    "append": "",
    "prepend": ""
}

HTML banner

{
    "bannerId": "3",
    "campaignId": "1",
    "bannerName": "Demo HTML Banner 1",
    "storageType": "html",
    "imageURL": "",
    "htmlTemplate": "html code goes here",
    "width": "728",
    "height": "90",
    "weight": "1",
    "target": "",
    "url": "",
    "bannerText": "",
    "status": "0",
    "adserver": "",
    "transparent": "0",
    "capping": "0",
    "sessionCapping": "0",
    "block": "0",
    "aImage": null,
    "aBackupImage": null,
    "comments": "",
    "alt": "",
    "filename": "",
    "append": "",
    "prepend": ""
}

Inline video ad

Currently not supported in the Revive Adserver REST API

Overlay video ad (image)

{
    "bannerId": "5",
    "campaignId": "1",
    "bannerName": "Demo Overlay Video Ad (image)",
    "storageType": "html",
    "imageURL": "",
    "htmlTemplate": "",
    "width": "-2",
    "height": "-2",
    "weight": "1",
    "target": "",
    "url": "https:\/\/www.reviveadserverrestapi.com\/",
    "bannerText": "",
    "status": "0",
    "adserver": "",
    "transparent": "0",
    "capping": "0",
    "sessionCapping": "0",
    "block": "0",
    "aImage": null,
    "aBackupImage": null,
    "comments": "",
    "alt": "",
    "filename": "79498bab5704ecabf9f3a099a63f57a2.gif",
    "append": "",
    "prepend": ""
}

Overlay video ad (text)

{
    "bannerId": "6",
    "campaignId": "1",
    "bannerName": "Demo Overlay Video Ad (text)",
    "storageType": "html",
    "imageURL": "",
    "htmlTemplate": "",
    "width": "-2",
    "height": "-2",
    "weight": "1",
    "target": "",
    "url": "https:\/\/www.reviveadserverrestapi.com\/",
    "bannerText": "",
    "status": "0",
    "adserver": "",
    "transparent": "0",
    "capping": "0",
    "sessionCapping": "0",
    "block": "0",
    "aImage": null,
    "aBackupImage": null,
    "comments": "",
    "alt": "",
    "filename": "",
    "append": "",
    "prepend": ""
}

Text ad

{
    "bannerId": "7",
    "campaignId": "1",
    "bannerName": "Demo Text Ad",
    "storageType": "txt",
    "imageURL": "",
    "htmlTemplate": "",
    "width": "0",
    "height": "0",
    "weight": "1",
    "target": "",
    "url": "https:\/\/www.reviveadserverrestapi.com\/",
    "bannerText": "Revive Adserver REST API is a RESTful API for Revive Adserver.",
    "status": "0",
    "adserver": "",
    "transparent": "0",
    "capping": "0",
    "sessionCapping": "0",
    "block": "0",
    "aImage": null,
    "aBackupImage": null,
    "comments": "",
    "alt": "",
    "filename": "",
    "append": "",
    "prepend": ""
}

HTML5 banner

Currently not supported in the Revive Adserver REST API.