Skip to main content
AdFormatA is a SceneGraph Group component that displays a full-width (or percentage-width) banner image anchored to the top or bottom of the video area. It fades in when the image loads and fades out when destroyed.

​
Interface fields

​
adConfig
assocarray
Configuration object built by AdManager.BuildNodeConfig. Triggers onAdConfigChanged and drives all layout and image-loading behaviour.
KeyTypeDefaultDescription
media_urlstring—URL of the banner image
positionstring"bottom"Normalised position: top, top-left, top-right, bottom, bottom-left, or bottom-right
width_percentfloat100.0Banner width as a percentage of the viewport width
height_percentfloat15.0Banner height as a percentage of the viewport height
fit_modestring"fit""fill" maps to scaleToFill; anything else maps to scaleToFit
viewportassocarraydesign size{x, y, w, h} of the video playback area
​
imageLoaded
boolean
default:"false"
Set to true by AdFormatA once the adPoster Poster node reports a ready load status. AdManager observes this field to start the impression session.
​
imageError
boolean
default:"false"
Set to true if the Poster reports a failed load status. AdManager observes this to destroy the slot and increment the consecutive-failure counter.

​
Visual behaviour and positioning

The banner width and height are calculated as percentages of the viewport dimensions: 
w = Int(sw * wPct / 100.0)   ' default wPct = 100.0
h = Int(sh * hPct / 100.0)   ' default hPct = 15.0
The position value is normalised and resolved to one of six anchor points:
Position valueAnchor
topHorizontally centred at the top edge
top-leftTop-left corner
top-rightTop-right corner
bottom (default)Horizontally centred at the bottom edge
bottom-leftBottom-left corner
bottom-rightBottom-right corner
The component uses a 50 ms repeating Timer (fadeTimer) to drive an opacity animation. Each tick increments opacity by approximately 0.1667 (six steps to fully opaque). FadeOut is called by AdManager before the node is removed.

​
XML component definition

<component name="AdFormatA" extends="Group">
    <interface>
        <field id="adConfig"     type="assocarray" onChange="onAdConfigChanged" />
        <field id="imageLoaded"  type="boolean"    value="false" />
        <field id="imageError"   type="boolean"    value="false" />
    </interface>
    <children>
        <Poster id="adPoster" loadDisplayMode="scaleToFit" visible="false" />
        <Timer  id="fadeTimer" duration="0.05" repeat="true" />
    </children>
</component>

​
How it renders from ad data

1

AdManager sets adConfig

After creating the AdFormatA node and appending it to the scene, AdManager sets node.adConfig = BuildNodeConfig(rec). This triggers onAdConfigChanged.
2

Layout is computed

onAdConfigChanged reads viewport, width_percent, height_percent, position, and fit_mode from adConfig and applies the resulting frame to the adPoster Poster node.
3

Image loads

adPoster.uri is set to cfg.media_url. The Poster is hidden (visible = false) until the load status becomes ready. If the image is already cached and ready, it is shown immediately without waiting for a load event.
4

Fade in

On a successful load, FadeIn starts the fadeTimer. The banner becomes visible and fully opaque after approximately 300 ms (6 ticks × 50 ms).
5

imageLoaded reported

m.top.imageLoaded = true is set, which AdManager observes to record the impression start time.
Format A is the only format that uses the video playback viewport (videoViewport) rather than the base viewport. Its position is always relative to the active video area, not the full screen.

Build docs developers (and LLMs) love

Get started for freeTalk to us