# Hogarth DCP Developer Guide

# Getting Started

# About this guide

This section of the documentation will take you through the process of developing Master Templates with Hogarth Intelligent Content DCP.

Hogarth's DCP technology enables you to build your HTML5 templates in whichever way you like. You do not need to implement any ad server specific code, and your versions will work across ad servers and social platforms.

Once you have built your creative, it is time to make the changes required to allow Hogarth DCP to read the editable areas. You will need to make a few small changes to your banner files to ensure they can be read by the platform.

You can then use the Hogarth Intelligent Content interface to rapidly build out thousands of variations in a short time. You can localise or change content from within the interface, manage the approvals process, and deliver campaigns to ad servers in a variety of ways.

To build for Hogarth DCP, you will be using a library and framework called hoxton-cli

# Downloads

Download these files which will be used throughout this documentation

Download Hoxton CLI v0.2.5

Download Hoxton.js v5

Download Boilerplate Templates

# Hoxton CLI

# About the Hoxton CLI

The Hoxton CLI runs on your local machine, and provides the following benefits:

• Hot reloading
• Build multiple sizes at once
• Bring dynamic technology to your desktop
• Easy import into a Hogarth DCP Campaign

You will need to install the CLI to build your master templates.

# Running the Hoxton CLI

In the Terminal, navigate to the parent folder where your banners are and run the command hoxton. If successful, you will see the following result:

💡 Hoxton CLI is ready for changes...
🖥 View at: https://www.hoxton.co/sandbox

Navigate to the Sandbox address, and you will see all the master banners that are on your local machine within the Hogarth DCP interface. You can now easily build up variations, use the timeline scrubber, resize images and content, and all other convenience features that exist within the interface.

# Editing multiple banners at once with Sandbox

Any valid templates existing within the directory you run cli tool will show in the sandbox view. You can make multiple templates for sizes, with bespoke js and css code but best practice is to ensure the json structure remains constant if they are for use in one campaign.

You can also generate new sizes directly from Sandbox by choosing "New Size", click the ... at bottom right of an ad.

All new sizes will respond to the single code base. You can use media queries in css to control layout. This provides a powerful way to avoid duplication of code and build multiple sizes quickly.

An example of a responsive template is included in the boilerplates package:

advanced-responsive

# Accessing images via the Hoxton CLI & Sandbox

Currently, the Sandbox can only access images included locally within folders in the template, or uploaded to the production client Media Library.

# Hoxton.json Manifest

# Example json manifest

{
    "name": "Hogarth starterKit Boilerplate",
    "reportingLabel": "{Message}_{Cta}_{width}x{height}",
    "adType": "HTML5",
    "adSize": {
        "width": "300",
        "height": "250"
    },
    "platform": "generic",
    "backupQuality": "90",
    
    "copy_01": {
        "type": "text",
        "value": "Copy line 01",
        "editableGroups": [
            "Message"
        ]
    },
    "copy_02": {
        "type": "text",
        "value": "Copy line 02",
        "editableGroups": [
            "Message"
        ]
    },
    "img_01": {
        "type": "image",
        "value": "images/background_300x250_x2.jpg",
        "editableGroups": [
            "Message"
        ]
    },
    "cta": {
        "type": "text",
        "value": "Buy Now",
        "editableGroups": [
            "Cta"
        ]
    },
    "css_overrides": {
        "type": "css",
        "value": "",
        "editableGroups": [
            "Message"
        ]
    },
    "exit_url": {
        "type": "text",
        "value": "https://www.hogarth.com",
        "editableGroups": [
            "Cta"
        ]
    }
}

# Metadata

This section of the manifest is required for Hoxton to understand the configuration of your Master Template.

# Content Data

The Content data area of the manifest is where you describe the editable content of your creative. This is what Hoxton reads and displays in the UI. For each item, you must provide a value and a type, and optionally, an editableGroup.

The format is:

"itemName" : {
    "value": "Default Text",
    "type": "text",
    "editableGroups": [
        "My Group"
    ]
} 

The itemName should be an ID that belongs to a DOM element, for example:

<div id="itemName"></div> 
<!-- or -->
<img src id="itemName">

It’s best to leave the content in the DOM element empty, to avoid a flash of unexpected content. Instead, place the default content in the manifest.

# Editable types

The following types are available to use. Items marked with a star are currently unreleased, but please get in contact if you require them.

# Boilerplate templates - Basic

# basic-starterkit

• A basic HTML ad template showing the automatic binding of DOM elements
• Two editableGroups are included, with some copy vars, an image and exit_url

# basic-video

• as above with the addition of a dynamic video
• see setDynamicContent.js for the addition of video preloading functions

# basic-scaleTextToFit

• template includes checkFontsLoaded.js library, ensures specified custom fonts are loaded before ad playback.
• scaleTextToFit function allows automatic font size adjust based on container size.

# Files included in all templates

hoxton-v5.js (do not edit)

• couples IC platform with template
• manages dynamic data
• auto updates DOM

# setDynamicContent.js

• instantiates global variable _dynamicData as the data object
• defines hoxton.timeline
• defines function to call when hoxton is initialised
• defines any updates to non ID targeted content within setDynamicContent() function
• Calls Creative.startAd() defined in creative.js

# updateContent.js

• IC edit mode only
• only called if any IC edits are made
• updates global variable _dynamicData
• define any updates to non ID targeted content
• can delete for runtime outside of IC platform

# creative.js

• define banner timeline animation
• handle exit clickthrough. Use hoxton.exit to handle clickthroughs. The relevant exit functionality for each platform is injected on export.

 hoxton.exit( "Exit" , _exitURL );

• checkIsBackup function - when downloading ads from IC backup images are generated and inserted automatically.
• jumpToEndFrame function - use this function to specify any specific settings you would apply when the backup image is generated.

# Boilerplate templates - Advanced

# advanced-responsive

• a single template with responsive.css file included, with media query breakpoints for various sizes.
• once running in sandbox, use 'new size' to add more sizes to see these.
• this allows multiple sizes to be created with only one codebase.
• when the template is uploaded to the IC platform and used in a campaign, you will need to create each required within that campaign.
• when bespoke JS animations are required in the timeline, this can be acheived through the use of the size class which we add to the main container.
  • in setDynamicContent.js :

  // we set banner containers to display:block so we can take size measurements,
  // (ensure opacity:0 is set, then opacity:1 at start of main TL)
  Creative.displayBanner();
  
  var _adWidth = container.offsetWidth;
  var _adHeight = container.offsetHeight;
  
  container.classList.add("size"+_adWidth+"x"+_adHeight);
  

  then in the timeline, defined in creative.js init function, for example:

  // set all main-copy startPoints to y:10% except on the 728x90 format:
  .to(".main-copy:not(.size728x90 .main-copy)", {x:0, y:"10%"}, "<")
  
  // set the main-copy startPoints on 728x90 only to x:-20%
  .to(".size728x90 .main-copy", {x:"-20%", y:0}, "<")
  

# advanced-reloading_functionality

• to allow more flexibility within a template, config variables can be very useful to control aspects of the animation.
• this boilerplate demonstrates the use of some speed, x, y, and ease vars, added to the json and used within the TL.
• when these values are changed in the editor, the timeline is already initialised so they do not take effect unless saved/refreshed
  • to allow the updates to be seen in editor as they are made, we added functionality to updateContent.js
  • when any specified config variable is changed, the timeline is rebuilt so the new values take effect

Creative.updateContent = function (item) {
    
    _dynamicData = hoxton.getState();

    var _timelineNeedsRebuild = false;

    switch(item.name){
        case "copySpeed":
            _copySpeed = _dynamicData.copySpeed;
            _timelineNeedsRebuild = true;
            break;
        
        case "copyStartX":
            _copyStartX = _dynamicData.copyStartX;
            _timelineNeedsRebuild = true;
            break;

        case "copyEndX": 
            _copyEndX = _dynamicData.copyEndX;
            _timelineNeedsRebuild = true;
            break;

        case "copyEase": 
            _copyEase = _dynamicData.copyEase;
            _timelineNeedsRebuild = true;
            break;
    }

     f(_timelineNeedsRebuild){
        Creative.tl.clear();
        Creative.init();
        Creative.tl.seek("reset");
        Creative.tl.play();
    }
}

# DOM id targeted content

• text, images: DOM id needs to match JSON data id
• css: injects CSS into HTML to override default styles (allows custom banner CSS - eg. font color)

# non DOM id targeted content

• updated in setDynamicContent() within setDynamicContent.js
• updated IC edits in Creative.updateContent(item) within updateContent.js
• to access data - eg.

_dynamicData.exit_url

# DCP Editor features

The DCP Editor (including the Sandbox) contains a number of useful features designed to save time when producing content at scale. If you are unsure how to use anything on the list below, reach out to your Intelligent Content representative.

• Automatic image resizing
• Creating content at scale by combining Groups
• Duplicating group content
• Positioning & text adjustment
• Generating new banner sizes
• Batch importing content by spreadsheet
• Batch importing translations by spreadsheet or WordBee
• Connecting multiple external feeds
• Batch assignment of pre-cropped sizes of a single image
• Locking and unlocking content
• Enabling external teams to update specific content

# Version Library features

The Version Library is where you can see all combinations available, and take your selection through the approval and delivery workflows. If you are unsure how to use anything on the list below, reach out to your Intelligent Content representative.

• Selecting versions
• Marking versions for multi-level approval
• Creating share links
• Converting Ads to Video, Image, DCO Feed or HTML5 Zip
• Sending ads to Social Networks
• Sending ads to Ad Servers
• Communication with team members and clients

# Applying Audience & Macro IDs

There are two ways of assigning external platform IDs in Intelligent Content. Which approach depends on your needs.

# Using Groups & Placeholders

You can design your groups to belong to different data signals, and then create an editable in each group to hold the ID that will be used during the decisioning process. Let's look at the following example:

Change the CTA content based on where the user is in the decisioning process. This is defined by a Floodlight ID.

So, just create a group "Call To Action", and ensure it has two editables - "ctaText" and "floodlightId". Now, whenever a ctaText option is used in a creative, the floodlightId will always be included in the feed for that item.

You can also create groups called 'Audience', 'Placement', and 'Market'. These are reserved group names that will display uniquely in the Library UI in the future. You can add editables to this group that are linked to the ID - things like an exit url, additional fields for reporting dimensions, and of course the relevant macro IDs from external platforms such as DSPs (comma seperated values are also supported here).

# Using Metadata Columns

If you prefer the more traditional method of assigning content to a row on a spreadsheet, or you need a more sophisticated approach where an ID correlates to two or more group options being selected, metadata columns will work well for you.

You can add the required columns in the Library using "Add Column".

Then, select the required combinations for your ID using the checkboxes on the right.

Finally, apply the ID to all selected combinations by using 'Set Values'. You'll find this on the [...] menu in your new column. This only applies to the currently selected page, but by choosing Table Mode you can have 50 items per page. Enable table mode by clicking the List-view icon on the right of your column.

You can access metadata column values within your template. For example, if you needed to specify a unique UTM code to add to the end of the clickthrough url, you could do it this way (assuming the column name is called 'floodlightId'):

  function exit() {
    hoxton.exit('Exit', 'http://promotion.client.com/?utm=' + hoxton.metadata.floodlightId.value)
  }

# Case Studies

The Intelligent Content team has a range of case studies available - reach out to learn more about how our clients have used our creation, delivery, and reporting technology on the following topics:

• Dynamic Video & Audio
• API generated builds
• Realtime data feeds
• Multi-platform campaign delivery
• Content reuse
• DAM integrations
• AI & ML generative content

# Notes on Media Library file names

When uploading files to or creating folders in the media library, the name of the media item will be sanitised to remove any characters which could cause problems when publishing or downloading your ads. The following operations will be performed against the name of any file or folder:

• It will be made lower case e.g. Beach.jpg would be stored as beach.jpg
• Spaces will be removed and replaced with - e.g. nice beach.jpg would become nice-beach.jpg
• Invalid characters (such as, but not limited to, +/[]{}) will be removed e.g. nice-beach$$.jpg would become nice-beach.jpg
• Full stops will be removed e.g. nice.beach.jpg will become nicebeach.jpg

Any file with a name that matches a file that already exists will overwrite the existing file without warning so it is recommended that assets that you upload already have valid names so that converted names do not overwrite existing files unintentionally.

For you convenience you may upload a zip file of assets that you want to add to the system and have it extracted automatically. There are some considerations to be aware of when using this feature.

• File and folder names inside the zip will be sanitised
• Files that exist in the media library will be overwritten by files in the zip if they have the same path
• Folders inside the zip which contain an index.html will stop the sanitation of any paths inside that folder. This is so that when webpage assets are uploaded to be used as folder editable types, the linkages inside the files are not broken. It is still recommended that you make these assets with paths that do not contain special characters or spaces in them.

...