[Creative Upload] How to setup the features for Xandr

Challenge

You are planning to use the ADvendio Creative Upload features to manage your creatives in ADvendio and upload them directly to your Xandr network. Now you are wondering:

  • Which creative types and features are already supported?

  • Which steps are needed to set up and configure the creative upload feature for Xandr

  • Can ADvendio handle custom templates and custom macros? And how to configure this?


Solution

To set up the Creative Upload in ADvendio, there are so-called Ad Creative Templates required. Those templates control, which fields and settings will be available in the Creative Upload UI and thus which information your Sales Reps will be able to see. Additionally, you can determine which Campaign Items, and which Creative Template are available. This helps you for example to make sure to only use video creatives for your video Campaign Items and similar.

Also, the templates will help to define which information is sent to which fields in Xandr. Each template in ADvendio will refer to a Creative Template in Xandr.

Underneath each Ad Creative Template in ADvendio, there are Template Variables, which can configure which fields are visible in the Creative Upload Screen, but also which settings or custom macros to use in Xandr.

Here is an overview of the data model and what it means:

ADvendio Object

Xandr

ADvendio Object

Xandr

Ad Creative

The actual creative that will be uploaded to an advertiser in Xandr and will later be assigned to a line item

Campaign Item

represents the Line Item in Xandr

Creative Assignments

ADvendio assigns Creatives to Line Items in Xandr based on the Creative Assignment object in ADvendio.

Ad Creative Template

The Xandr Creative Template to use

Ad Creative Template Variable

The fixed settings and fields required for Xandr Creatives, more information can be found in https://advendio.atlassian.net/wiki/spaces/SO/pages/3146416141

Ad Creative Template Variable

Xandr Custom Macros from your template

Configure Your Org for Xandr Creative Upload

 

To start configuring your ADvendio Org for the creative upload to Xandr, you need to follow these steps:

  • Import Creative Template directly from Xandr (Available with Version 2.158)

  • Or manually Create Ad Creative Templates in ADvendio

  • Configure your Ad Creative Template Variables for each template based on your Xandr Settings

  • Connect Ad Creative Templates to Ad Types in ADvendio, to make them available to your Users

 

Features and Creative formats supported for Xandr

 

The following Creative formats are currently supported by ADvendio:

  • Banners

    • Image format (directly uploaded image file & URL to an image)

    • Flash format (Only URL to a flash file)

    • HTML format (Only URL to an HTML file)

    • raw HTML (directly submitted HTML code)

    • iframe HTML (directly submitted HTML code)

    • raw JS (directly submitted JS code)

    • Javascript format (Only URL to a JS file)

  • Interstitials

    • Image format (directly uploaded image file & URL to an image)

    • Flash format (Only URL to a flash file)

    • HTML format (Only URL to an HTML file)

    • Javascript format (Only URL to a JS file)

    • raw HTML (directly submitted HTML code)

    • raw JS (directly submitted JS code)

  • High Impact

    • Image format (directly uploaded image file & URL to an image)

    • Flash format (Only URL to a flash file)

    • HTML format (Only URL to an HTML file)

    • Javascript format (Only URL to a JS file)

    • raw HTML (directly submitted HTML code)

    • iframe HTML (directly submitted HTML code)

    • raw JS (directly submitted JS code)

  • Expendable

    • Image format (directly uploaded image file & URL to an image)

    • Flash format (Only URL to a flash file)

    • HTML format (Only URL to an HTML file)

    • Javascript format (Only URL to a JS file)

    • raw HTML (directly submitted HTML code)

    • iframe HTML (directly submitted HTML code)

    • raw JS (directly submitted JS code)

  • Natives (With version 2.149)

For the first version ADvendio only supports uploading actual image files to Xandr, the support of URLs to externally stored images as well as other formats will be supported soon.

The following features are currently supported:

  • Custom Creative Templates (as long as they are using the supported formats)

  • Custom Macros

 

Import Templates from Xandr Network to ADvendio

With version 2.158, a BETA release of Import Templates from Xandr Network to ADvendio is now available. We will be adding more features in future releases.

You can now import templates from your Xandr network into ADvendio. With this enhancement, you have ready-to-use templates already created at the click of a button!

To access this feature, you will need to go to your Xandr Connection record in ADvendio and select ‘transfer to ADvendio’

Within the window that opens, you will need to select Creative Templates and decide which templates you’d like to import.

  • Creative Standard Templates → This includes the required templates for the default Google Creatives, such as images, image URLs and similar)

 

Once the import is done, you receive ready-to-use templates, which contain all the required technical information for ADvendio. You can then proceed to customize them to your needs further, for example by adding additional help texts to the variables (see mapping section below).

Attention:

All templates imported by ADvendio, receive a Unique Key in the field Unique Key External. If you want to modify a template for your own needs, please empty this Unique Key or set an own one. Otherwise if you start the import process a second time, we might overwrite your changes!

Problems during the import

After the import process from the AdServer finished, you will receive a result email. This will also provide you an overview of problems during the import process. Some of the more common issues can be:

  • Non working / invalid credentials for your connection

  • Missing Permissions on your Third Party Platform User

  • Salesforce Problems, when uploading data, such as no editing permissions on the required fields and objects, storage limitations or custom validations

  • If a Creative Template can not be created by the ADvendio import process, all related variables will also fail, with an error message that ‘ADvendio__UniqueKeyExt__c was not specified’

 

Manual Creation of Ad Creative Templates in ADvendio

 

In ADvendio, you can create ad creative templates manually, this will help you to configure the types of creatives you want to manage from ADvendio.

To use this for Xandr, you need to know the Xandr template IDs, so you can enter this information in ADvendio. To view the templates in Xandr, go to network → tools → Creative Templates

You see a list of all default templates from Xandr and your own custom templates. Relevant for ADvendio is the first column ID.

Let’s say we want to use the Standard Banner image template, which is the default from Xandr. So we take the ID 4. Now we proceed to create an Ad Creative Template record in ADvendio, which could look like this:

  1. Creative Template Name: You can pick any name that you like. This name will be shown to the user when uploading a new creative to ADvendio, so we recommend using something which is relatable to your users

  2. Connection: Please link to the connection record, which represents your Xandr network

  3. Creative Type: You can use this field to further classify

  4. Template ID: Please enter the Creative Template ID from Xandr, which you are planning to use. In our example, it is '4'

  5. External Status: Currently not used

  6. Active: Please set your template to active, otherwise it will not be available during the creative upload process

 

Configuring Ad Creative Template Variables

 

Once the template is there, you will need to define which fields you want or need to use. In our example, there are a few fixed variables we always need for the Xandr banner. Additionally, you can add Custom Macros as Variables to ADvendio, so that they will be used during the Creative Upload.

To manage the variables of a template, you need to switch to the related tab in your Ad Creative Template record and view the related list ‘Ad Creative Template Variables’

Click the button New to create a new Variable. Depending on your creative format there are certain Variables which are always required. See also the section on the mapping below. Also, you will need a Variable record for each Custom Macro of your template. Each Variable record you create will then be your own field in the Creative Upload window your user sees, so they can fill in the required information.

The fields mean the following:

  • Name: A general name for your variable. This will also be shown as Field Name to the user during the creative upload process, so we recommend picking something your users can recognize.

  • Variable Type: Which data type is this variable? The selection will also reflect how your field will be shown to the users. Possible types are:

    • attachment: This type should be used for files.

    • boolean: This type represents a checkbox with true or false.

    • date: This type represents a date with a calendar selection.

    • integer: This type represents a whole number.

    • picklist: This type represents a list of multiple values.

    • string: This type represents a text.

    • textarea: This type represents a longer text.

    • attachmentURL: This type should be used for URLs to externally stored images.

    • ExternalAttachment: This is used for file attachments, which are supposed to be stored in an external storage solution, instead of Salesforce file storage.

  • Required: Check this if the field is required for the user.

  • Possible Values: Only applicable for picklist Variable Types to enter the possible values to be selected separated by a semicolon.

  • Variable ID: The Id to target the value to the external system (case-sensitive). Please check the table below for more information.

  • Default: A possible default value to support the user in the selection.

  • Help Text: A possible help text which will soon be shown in the UI.

Mapping ADvendio Variables to Xandr Ad Creative Template Fields

ADvendio Variable ID

Field to target

Relevant Variable Type

Possible Values

Required

Relevant for Creative Formats

ADvendio Variable ID

Field to target

Relevant Variable Type

Possible Values

Required

Relevant for Creative Formats

File

The actual image file to upload

attachment

OR

ExternalAttachment

 


You either need to provide a file or a MediaURLSecure, in order for the upload to work

Images

MediaURLSecure

The URL to an externally stored file

attachmentURL

 


You either need to provide a file or a MediaURLSecure, in order for the upload to work

All formats

*not required for code based formats

MediaURL

If required, you can set a different, ‘non-secure’ URL to the externally stored file.

attachmentURL

 

All formats

*not required for code based formats

IframeHTMLContent

Stores the HTML code for iframe HTML type creatives

string

 

Iframe HTML formats

RawHTMLContent

 

string

 

HTML Code related formats

RawJSContent

 

string

 

JS related formats

DestinationURL

Click URL where the ad leads

string

 

All formats

*not required for code based formats

Width

the creative width

integer

 

All formats

Height

the creative height

integer

 

All formats

API Name of a Custom Macro

The Custom Macro

 

depending on the macro

Depends on the macro

All formats

AllowAudit

If true, the creative will be submitted for auditing. If false, the creative will not be submitted. Unaudited creatives can only run on a network's managed inventory.

string

  • true

  • false

If nothing is selected is set to “false” by default.

Banner - Image

AuditStatus

The audit status of the creative.

string

  • no_audit

  • pending

  • rejected

  • audited

If nothing is selected is set to “no_audit” by default.

Banner - Image

Status

The status of the creative describing if the creative is ready to serve.

boolean

  • true

  • false

If nothing is selected is set to “false” by default.

Banner - Image

 

Xandr Creative Template Example in ADvendio

 

Using the Xandr Creative Upload is simple. An example template:

AdCreative Template Field

Value

AdCreative Template Field

Value

Name

Standard Banner Image (File Upload)

Creative Type

Banner

Template ID

4

Connection

The connection record of your Xandr network

Active

True

 

Underneath this AdCreative template, the following AdCreative Template Variables are created:

Ad Creative Template Variable Name

Variable Type

Variable ID

Possible Values

Required

Help Text

Default Value

Ad Creative Template Variable Name

Variable Type

Variable ID

Possible Values

Required

Help Text

Default Value

Image File

attachment

OR

ExternalAttachment

File

 

True

Upload the image file you want to use for your ad

 

Goal URL

string

DestinationURL

 

True

Enter which URL a user should reach, once the ad is clicked. Please use ‘http://example.com’

http://www.example.com

Image Width

integer

Width

 

True

Please enter the height of your ad.

 

Image Height

integer

Height

 

True

Please enter the width of your ad.

 

 

Connecting Your Template to Ad Types in ADvendio

Once the template is created with all its Ad Creative variables, you will need to define which Ad Types you would like to assign this template. Without assigning the Templates to Ad Types you won’t be able to create new Creatives in the UI as described in: https://advendio.atlassian.net/wiki/spaces/SO/pages/2829713409

To connect the template to one or multiple Ad Types please go to the related lists of the Ad Creative Template record. For the related list “Assigned Ad Types“ you just need to hit the new button in order to select the relevant Ad Type for which this template and its variables should be usable. After you select the Ad Type you can either hit the save button if you just want to assign one Ad Type. If you would like to assign multiple Ad Types you can also hit the Save & New button.

 

Setting Up Native Formats in ADvendio for Xandr

Natives in Xandr can contain a huge variety of different fields and settings. To prepare those from ADvendio, you will first need to create specific Ad Creative Templates.

The template ID for this one always needs to be ‘39461’ since this is the ID Xandr uses for Natives. In ADvendio you are of course free to create multiple

To set up the Variables in ADvendio, there is a big list of options you could use which represent the different settings of the natives.

Roughly you could separate those into three different types:

  1. The Basic settings like the name and the URL of the landing page

  2. The actual elements of the native, like a title, body text, buttons and similar. They are also referred to as data assets

  3. The image assets will be used within the native, for example as the main image or icon. In the current release, ADvendio does not support video files, only images.

Most of these settings are optional, so you are free to only create those Ad Creative Template Variables in ADvendio, which you are planning to actually use.

 

The Basic Setup

For the basic settings, you will only need a variable, which represents the landing page URL, as the Creative Name is a default field in ADvendio.

ADvendio Variable ID

Field to target

Relevant Variable Type

Possible Values

Required

 

ADvendio Variable ID

Field to target

Relevant Variable Type

Possible Values

Required

 

URLLinkAttribute

The landing page URL for the native

string

 

 

FallbackURLLinkAttribute

 

string

 

 

AllowAudit

If true, the creative will be submitted for auditing. If false, the creative will not be submitted. Unaudited creatives can only run on a network's managed inventory.

string

  • true

  • false

If nothing is selected is set to “false” by default.

Banner - Image

AuditStatus

The audit status of the creative.

string

  • no_audit

  • pending

  • rejected

  • audited

If nothing is selected is set to “no_audit” by default.

Banner - Image

Status

The status of the creative describing if the creative is ready to serve.

boolean

  • true

  • false

If nothing is selected is set to “false” by default.

Banner - Image

 

Composition / Data Assets

To actually define the native, Xandr offers a variety of elements, like the Title, a body text, a Call to action and similar. We summarized those as Data Assets. For each of these Xandr fields that are relevant to you, you can create an ad creative template variable in ADvendio. None of these is required for the submission to Xandr to work.

ADvendio Variable ID

Field to target

Relevant Variable Type

ADvendio Variable ID

Field to target

Relevant Variable Type

DataAssetTitle

The title of the native

string / integer / text field

DataAssetDescription

The main body text of the native

string / integer / text field

DataAssetSponsoredBy

Sponsored By field in Xandr

string / integer / text field

DataAssetCallToAction

Call to Action field in Xandr

string / integer / text field

DataAssetDisplayURL

Display URL field in Xandr

string / integer / text field

DataAssetPrice

Price Field in Xandr

string / integer / text field

DataAssetSalePrice

Sales Price field in Xandr

string / integer / text field

DataAssetRating

Rating field in Xandr

string / integer / text field

DataAssetLikes

Likes field in Xandr

string / integer / text field

DataAssetDownloads

Downloads field n Xandr

string / integer / text field

DataAssetPhone

Phone field in Xandr

string / integer / text field

DataAssetAddress

Address field in Xandr

string / integer / text field

DataAssetAdditionalDescription

Additional Description field in Xandr

string / integer / text field

DataAssetCustomTitle1 … DataAssetCustomTitle5

 

string / integer / text field

DataAssetCustomBody1 ... DataAssetCustomBody5

 

string / integer / text field

DataAssetCustomCallToAction1 … DataAssetCustomCallToAction5

 

string / integer / text field

DataAssetCustomSocialURL1 … DataAssetCustomSocialURL5

 

string / integer / text field

DataAssetCustomDisplayURL1 … DataAssetCustomDisplayURL5

 

string / integer / text field

 

Image Assets & Attachments

You can provide multiple images and icons for your native creatives in Xandr.

 

Image Type

ADvendio Variable ID

Field to target

Possible values

Relevant Variable Type

Required

Image Type

ADvendio Variable ID

Field to target

Possible values

Relevant Variable Type

Required

Main Image

ImageFileMain

The image file to attach as main image for a native

 

attachment

OR

ExternalAttachment

If you want to use an image, either attaching a file or a secure URL to an externally stored image is required

ThirdPartyImageURLMain

A URL to an externally stored image file to use as main icon. It is possible to use URLs with http:// and https://

 

attachmentURL

If you want to use an image, either attaching a file or a secure URL to an externally stored image is required

ThirdPartyImageURLSecureMain

An optional URL to an externally stored image file with secure protocol, setting this is optional and the asset is not necessarily visible in the Xandr UI

 

string

ThirdPartyImageWidthMain

The width of the image, is using an externally stored image

 

integer

you can enter a custom width information for the image, this required by the Xandr API.

If nothing is entered ADvendio will automatically calculate the size of your image.

ThirdPartyImageHeightMain

The height of the image, is using an externally stored image

 

integer

you can enter a custom height information for the image, this required by the Xandr API.

If nothing is entered ADvendio will automatically calculate the size of your image.

ResizeEnabledMain

Optional setting to automatically

true, false

picklist

CropEnabledMain

 

true, false

picklist

AspectRatioUpperBoundMain

 

number between 0 and 50

integer

AspectRatioLowerBoundMain

 

number between 0 and 50

integer

MaxScaleFactorMain

 

number between 1.00 and 9.99

integer

Icon Image

ImageFileIcon

The image file to attach as main icon for a native

 

attachment

OR

ExternalAttachment

If you want to use an image, either attaching a file or a secure URL to an externally stored image is required

ThirdPartyImageURLIcon

A URL to an externally stored image file to use as main icon. It is possible to use URLs with http:// and https://

 

attachmentURL

If you want to use an image, either attaching a file or a secure URL to an externally stored image is required

ThirdPartyImageURLSecureIcon

An optional URL to an externally stored image file with secure protocol, setting this is optional and the asset is not necessarily visible in the Xandr UI

 

attachmentURL

 

ThirdPartyImageWidthIcon

The width of the image, is using an externally stored image

 

integer

you can enter a custom width information for the image, this required by the Xandr API.

If nothing is entered ADvendio will automatically calculate the size of your image.

ThirdPartyImageHeightIcon

The height of the image, is using an externally stored image

 

integer

you can enter a custom height information for the image, this required by the Xandr API.

If nothing is entered ADvendio will automatically calculate the size of your image.

ResizeEnabledIcon

Optional setting to automatically

true, false

picklist

CropEnabledIcon

 

true, false

picklist

AspectRatioUpperBoundIcon

 

number between 0 and 50

integer

AspectRatioLowerBoundIcon

 

number between 0 and 50

integer

MaxScaleFactorIcon

 

number between 1.00 and 9.99

integer

Custom Image 1 - 5

ImageFileCustom1 …

ImageFileCustom5

Similar to the above examples, you can provide the files for the custom images 1-5

 

attachment

OR ExternalAttachment

ThirdPartyImageURLCustom1 …

ThirdPartyImageURLCustom5

Similar to the above examples, you can provide URLS to externally stored files for the custom images 1-5

 

attachmentURL

all other settings above are also support simply replace 'Main' or 'Icon' in the variable ID with Custom1-5

 

Xandr Creative Upload: Support for Third Party Tag and Code Creatives

With the release of version 2.168, we support and include code-based creatives without image files or external URLs. Users can now import Creative Templates with formats like HTML, XML, Flash, and similar code-based formats, making it easier to handle third-party tags received from agencies. The updated feature allows importing and assigning Custom Templates from Xandr, using AdCreative Templates in ADvendio, and using the Creative Upload feature to seamlessly upload and manage creatives in code formats to Xandr for Campaign Items.


Creative Assignment Dates for GAM and Xandr

GAM and Xandr support the feature "Assignment Dates in Creative Uploads" that allows advertisers and campaign managers to select specific dates for uploading their ads. This feature provides greater control over advertising campaigns and ensures that ads are displayed at the right time. For more info, please refer to this article.