Documentation
¶
Index ¶
- Constants
- Variables
- func DecodeBindingParams[P any](bindings []Binding, target string) (P, bool)
- func ParseAspectRatio(s string) (w, h float64, err error)
- type Accessor
- type AltTextRequirement
- type AssetRequirement
- func (a AssetRequirement) Animated() AssetRequirement
- func (a AssetRequirement) AspectRatioValue() (w, h float64, ok bool)
- func (a AssetRequirement) Bind(b Binding) AssetRequirement
- func (a AssetRequirement) Bitrate(min, max int) AssetRequirement
- func (a AssetRequirement) Codecs(codecs ...string) AssetRequirement
- func (a AssetRequirement) Count(min, max int) AssetRequirement
- func (a AssetRequirement) Duration(min, max float64) AssetRequirement
- func (a AssetRequirement) ExactSize(width, height int) AssetRequirement
- func (a AssetRequirement) Focal(x, y float64) AssetRequirement
- func (a AssetRequirement) Framerates(fps ...float64) AssetRequirement
- func (a AssetRequirement) GetMaxCount() int
- func (a AssetRequirement) GetMinCount() int
- func (a AssetRequirement) GetName() string
- func (a AssetRequirement) IsFixedSize() bool
- func (a AssetRequirement) IsHTML5Support() bool
- func (a AssetRequirement) IsImageSupport() bool
- func (a AssetRequirement) IsMain() bool
- func (a AssetRequirement) IsMimeTypeSupport(mimePrefix string) bool
- func (a AssetRequirement) IsMultiple() bool
- func (a AssetRequirement) IsRequired() bool
- func (a AssetRequirement) IsSoundSupport() bool
- func (a AssetRequirement) IsVideoSupport() bool
- func (a AssetRequirement) MatchesAspectRatio(width, height int) bool
- func (a AssetRequirement) MaxSize(bytes int64) AssetRequirement
- func (a AssetRequirement) MinMaxHeight() (mn, mx int)
- func (a AssetRequirement) MinMaxWidth() (mn, mx int)
- func (a AssetRequirement) RangeCount() (min, max int)
- func (a AssetRequirement) Require() AssetRequirement
- func (a AssetRequirement) RequireAltText(maxLength int) AssetRequirement
- func (a AssetRequirement) Size(minW, maxW, minH, maxH int) AssetRequirement
- func (a AssetRequirement) SoftEqual(asset AssetRequirement) bool
- func (a AssetRequirement) Sound() AssetRequirement
- func (a AssetRequirement) SupportsCodec(codec string) bool
- func (a AssetRequirement) SupportsFramerate(fps float64) bool
- func (a AssetRequirement) Types(types ...string) AssetRequirement
- func (a AssetRequirement) When(c Condition) AssetRequirement
- func (a AssetRequirement) WithAspectRatio(ratio string) AssetRequirement
- func (a AssetRequirement) WithNavigateTo(screen string) AssetRequirement
- func (a AssetRequirement) WithSafeZone(top, right, bottom, left float64) AssetRequirement
- type Binding
- type Condition
- type Config
- func (c Config) ActiveAssets(values map[string]any) []AssetRequirement
- func (c Config) ActiveFields(values map[string]any) []Field
- func (c Config) ActiveGroups(values map[string]any) []Config
- func (c Config) ActiveParams(values map[string]any) []Param
- func (c Config) AsEntry() Config
- func (c Config) AssetByName(name string) *AssetRequirement
- func (c Config) Assets() []AssetRequirement
- func (c Config) ContainsAsset(asset AssetRequirement, revers ...bool) bool
- func (c Config) Count(min, max int) Config
- func (c Config) EntryGroup() (Config, bool)
- func (c Config) Fields() []Field
- func (c Config) GetField(name string) *Field
- func (c Config) GetMaxCount() int
- func (c Config) GetMinCount() int
- func (c Config) GetParam(name string) (Param, bool)
- func (c Config) Groups() []Config
- func (c Config) Intersec(other Config) bool
- func (c Config) IsEmpty() bool
- func (c Config) IsMultiple() bool
- func (c Config) MainAsset() *AssetRequirement
- func (c Config) Params() []Param
- func (c Config) RangeCount() (min, max int)
- func (c Config) RequiredField(fields ...string) *Field
- func (c Config) RequiredFieldExcept(fields ...string) *Field
- func (c Config) SimilarField(field Field, revers ...bool) *Field
- func (c Config) SimpleAsset() *AssetRequirement
- func (c Config) Validate() error
- func (c Config) Walk(fn func(path string, n Node) error) error
- func (c Config) When(cond Condition) Config
- func (c Config) WithAssets(assets ...AssetRequirement) Config
- func (c Config) WithFields(fields ...Field) Config
- func (c Config) WithGroups(groups ...Config) Config
- func (c Config) WithParams(params ...Param) Config
- func (c Config) WithTitle(t string) Config
- type Field
- func BoolField(name string) Field
- func EmailField(name string) Field
- func FloatField(name string) Field
- func GeoField(name string) Field
- func IntField(name string) Field
- func PhoneField(name string) Field
- func ScreenRefField(name string) Field
- func StringField(name string) Field
- func URLField(name string) Field
- func (f Field) Bind(b Binding) Field
- func (f Field) Count(min, max int) Field
- func (f Field) GetMaxCount() int
- func (f Field) GetMinCount() int
- func (f Field) GetName() string
- func (f Field) GetType() FieldType
- func (f Field) HasOptions() bool
- func (f Field) IsEditable() bool
- func (f Field) IsMultilang() bool
- func (f Field) IsMultiple() bool
- func (f Field) IsRequired() bool
- func (f Field) IsValidOption(v any) bool
- func (f Field) Len(min, max int) Field
- func (f Field) MaxLength() int
- func (f Field) MultilineRows() int
- func (f Field) Prepare(value any) (result any, err error)
- func (f Field) Range(min, max float64) Field
- func (f Field) RangeCount() (min, max int)
- func (f Field) ReadOnly() Field
- func (f Field) Require() Field
- func (f Field) SoftEqual(field Field) bool
- func (f Field) When(c Condition) Field
- func (f Field) WithDescription(s string) Field
- func (f Field) WithMask(mask string) Field
- func (f Field) WithMultilang() Field
- func (f Field) WithMultiline(rows int) Field
- func (f Field) WithNavigateTo(screen string) Field
- func (f Field) WithOptions(opts ...Option) Field
- func (f Field) WithRegExp(pattern string) Field
- func (f Field) WithTitle(t string) Field
- type FieldType
- type FocalPoint
- type Format
- func (f Format) DefaultSize() (SizeOption, bool)
- func (f *Format) GetConfig() *Config
- func (f Format) HasTag(tag string) bool
- func (f Format) IsAudio() bool
- func (f Format) IsBanner() bool
- func (f Format) IsDirect() bool
- func (f Format) IsFixedSize() bool
- func (f Format) IsNative() bool
- func (f Format) IsPush() bool
- func (f Format) IsVideo() bool
- func (f Format) String() string
- func (f Format) Suits(width, height int) bool
- func (f Format) SupportsOrientation(o Orientation) bool
- func (f Format) Validate() error
- type GeoValue
- type Kind
- type Node
- type NodeKind
- type Option
- type Orientation
- type Param
- type SafeZone
- type SimpleAccessor
- func (fa *SimpleAccessor) DirectFormatSet() *searchtypes.NumberBitset[uint]
- func (fa *SimpleAccessor) FormatByCode(code string) *Format
- func (fa *SimpleAccessor) FormatByID(id uint64) *Format
- func (fa *SimpleAccessor) Formats() []*Format
- func (fa *SimpleAccessor) FormatsBySize(width, height int) []*Format
- func (fa *SimpleAccessor) Prepare()
- type SizeOption
- type Thumb
Constants ¶
const ( AssetNameBanner = "banner" AssetNameMain = "main" AssetNameIcon = "icon" AssetNameLogo = "logo" )
Well-known asset names, kept for parity with the old model (admodels/types.FormatAsset* constants).
const ( )
Reserved NavigateTo commands (§3.2.11) — not screen names.
const ( FieldNameTitle = "title" FieldNameDescription = "description" FieldNameBrandname = "brandname" FieldNamePhone = "phone" FieldNameURL = "url" FieldNameContent = "content" FieldNameRating = "rating" FieldNameLikes = "likes" FieldNameAddress = "address" FieldNameSponsored = "sponsored" )
Well-known field names, kept for parity with the old model (admodels/types.FormatField* constants).
const Unlimited = -1
Unlimited is the sentinel MaxCount/GetMaxCount value meaning "no upper bound on the number of instances".
Variables ¶
var ( ErrFieldIsRequired = errors.New("adformat: field is required") ErrFieldInvalidType = errors.New("adformat: field value has invalid type") )
Errors returned by Field.Prepare.
Functions ¶
func DecodeBindingParams ¶
DecodeBindingParams finds the first binding in bindings matching target and decodes its Params into a value of type P via an encoding/json round-trip. It is the shared implementation behind every adapter package's own typed Get*/GetImage/GetData/... helpers (see adformat/openrtbnative, adformat/openrtbvideo, adformat/tracking, adformat/vasttracking), so none of them need to touch map[string]any by hand. Returns false when no binding for target is present or decoding fails.
func ParseAspectRatio ¶
ParseAspectRatio parses a "W:H" proportion string (e.g. "1.91:1", "16:9") into its numeric components. Both parts must be positive numbers.
Types ¶
type Accessor ¶
type Accessor interface {
// Formats list collection.
Formats() []*Format
// FormatsBySize returns the list of formats whose Sizes accept
// width/height (§3.2.13); direct formats are always included, same
// convention as the old model.
FormatsBySize(width, height int) []*Format
// FormatByID of the model.
FormatByID(id uint64) *Format
// FormatByCode of the model.
FormatByCode(code string) *Format
// DirectFormatSet to search.
DirectFormatSet() *searchtypes.NumberBitset[uint]
}
Accessor object interface (was admodels/types.FormatsAccessor).
type AltTextRequirement ¶
type AltTextRequirement struct {
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
MaxLength int `json:"max_length,omitempty" yaml:"max_length,omitempty"`
}
AltTextRequirement declares whether this asset role must be accompanied by an accessibility description supplied together with the file, and how long that description may be (§3.2.1 gap #3, increasingly required by exchanges). Just like FocalPoint's default anchor, this only describes the *requirement*; the actual text for one uploaded file is data of that creative instance, not part of the format schema.
type AssetRequirement ¶
type AssetRequirement struct {
// Required marks the asset as mandatory when it is active (see
// Condition below).
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
// Name of the asset (optional for the first/only asset, defaults to
// "main").
Name string `json:"name,omitempty" yaml:"name,omitempty"`
// Resizable: the platform may scale this file to fit the target size
// (was "adjust_size" — renamed for clarity, §3.2.1).
Resizable bool `json:"resizable,omitempty" yaml:"resizable,omitempty"`
// Width/Height: a "preferred" exact size for preview/fit purposes —
// does not participate in range validation, that is always the
// explicit Min/Max* pair below (§3.2.1). Left unset when only a
// range is meaningful.
Width int `json:"width,omitempty" yaml:"width,omitempty"`
Height int `json:"height,omitempty" yaml:"height,omitempty"`
// MinWidth/MaxWidth, MinHeight/MaxHeight: explicit allowed size
// range in pixels for image/video content (renamed from the
// old ambiguous width/min_width pair, §3.2.1).
MinWidth int `json:"min_width,omitempty" yaml:"min_width,omitempty"`
MaxWidth int `json:"max_width,omitempty" yaml:"max_width,omitempty"`
MinHeight int `json:"min_height,omitempty" yaml:"min_height,omitempty"`
MaxHeight int `json:"max_height,omitempty" yaml:"max_height,omitempty"`
// AspectRatio is a direct "W:H" proportion (e.g. "1.91:1", "16:9")
// offered as a more readable alternative/addition to a Min/MaxWidth
// + Min/MaxHeight range, matching how many real-world exchange specs
// (Facebook/Google-style) describe size constraints (§3.2.1 gap #1).
// When set together with a width/height range, both must be
// satisfied. See AspectRatioValue/MatchesAspectRatio.
AspectRatio string `json:"aspect_ratio,omitempty" yaml:"aspect_ratio,omitempty"`
// AllowAnimated/AllowSound: permissions for the asset content (was
// "animated"/"sound" — renamed since these describe a requirement,
// not a fact about a specific uploaded file, §3.2.1).
AllowAnimated bool `json:"allow_animated,omitempty" yaml:"allow_animated,omitempty"`
AllowSound bool `json:"allow_sound,omitempty" yaml:"allow_sound,omitempty"`
// DurationMin/DurationMax: allowed video/audio duration range in
// seconds. Zero means "no constraint" on that bound.
DurationMin float64 `json:"duration_min,omitempty" yaml:"duration_min,omitempty"`
DurationMax float64 `json:"duration_max,omitempty" yaml:"duration_max,omitempty"`
// BitrateMin/BitrateMax: allowed video/audio bitrate range in kbps
// (0 = no constraint on that bound). Closes the §3.2.1 gap #4 found
// in stricter TV/VAST specs, which the old duration-only model could
// not express.
BitrateMin int `json:"bitrate_min,omitempty" yaml:"bitrate_min,omitempty"`
BitrateMax int `json:"bitrate_max,omitempty" yaml:"bitrate_max,omitempty"`
// AllowedCodecs restricts video/audio encoding (e.g. "h264", "vp9",
// "av1", "aac") — empty means "any codec is allowed" (§3.2.1 gap #4).
AllowedCodecs []string `json:"allowed_codecs,omitempty" yaml:"allowed_codecs,omitempty"`
// AllowedFramerates restricts video frame rate to one of the given
// values in fps — empty means "any frame rate is allowed" (§3.2.1
// gap #4; several TV/VAST specs only accept exact rates like
// 25/29.97/30 rather than a free-form range).
AllowedFramerates []float64 `json:"allowed_framerates,omitempty" yaml:"allowed_framerates,omitempty"`
// MaxFileSize: maximum allowed file weight in bytes (0 = no limit) —
// closes a real gap found while researching playable/rich-media
// specs (§3.2.2), which almost universally cap file size.
MaxFileSize int64 `json:"max_file_size,omitempty" yaml:"max_file_size,omitempty"`
// FocalPoint: optional focus-point metadata (§3.2.1).
FocalPoint *FocalPoint `json:"focal_point,omitempty" yaml:"focal_point,omitempty"`
// SafeZone: optional edge-inset metadata, symmetric to FocalPoint
// (§3.2.1 gap #2).
SafeZone *SafeZone `json:"safe_zone,omitempty" yaml:"safe_zone,omitempty"`
// AltText: optional accessibility-text requirement (§3.2.1 gap #3).
AltText *AltTextRequirement `json:"alt_text,omitempty" yaml:"alt_text,omitempty"`
// Thumbs: structured autogenerated thumbnail sizes (§3.2.1).
Thumbs []Thumb `json:"thumbs,omitempty" yaml:"thumbs,omitempty"`
// AllowedTypes of files for this particular asset — either a short
// category (image/video/html5/sound) or an exact MIME type
// (image/jpeg) — both forms are intentionally supported.
AllowedTypes []string `json:"allowed_types,omitempty" yaml:"allowed_types,omitempty"`
// MinCount/MaxCount: how many instances of this asset one ad
// creative carries (§3.2, п.2). See
// GetMinCount/GetMaxCount/IsMultiple/RangeCount. MaxCount == -1
// means unlimited. Only legitimate when every instance is
// guaranteed to be part of one advertiser's single submission —
// see §3.0.
MinCount int `json:"min_count,omitempty" yaml:"min_count,omitempty"`
MaxCount int `json:"max_count,omitempty" yaml:"max_count,omitempty"`
// Condition controls when this asset is active (§3.2.5).
Condition *Condition `json:"condition,omitempty" yaml:"condition,omitempty"`
// image) switches the creative to when activated (§3.2.11).
// "$back"/"$close" are reserved commands, not screen names.
NavigateTo string `json:"navigate_to,omitempty" yaml:"navigate_to,omitempty"`
// Bindings associate this asset with external protocol
// representations (OpenRTB Native image/video asset, ...) —
// §3.2.12. Replaces the old, always-empty FormatFileRequirement.ID.
Bindings []Binding `json:"bindings,omitempty" yaml:"bindings,omitempty"`
}
AssetRequirement describes a requirement for one media file within an ad creative (was admodels/types.FormatFileRequirement).
func Asset ¶
func Asset(name string) AssetRequirement
Asset starts a new AssetRequirement builder chain with the given name.
func (AssetRequirement) Animated ¶
func (a AssetRequirement) Animated() AssetRequirement
Animated allows animated content for this asset.
func (AssetRequirement) AspectRatioValue ¶
func (a AssetRequirement) AspectRatioValue() (w, h float64, ok bool)
AspectRatioValue parses AssetRequirement.AspectRatio, reporting ok=false when it is empty or malformed.
func (AssetRequirement) Bind ¶
func (a AssetRequirement) Bind(b Binding) AssetRequirement
Bind attaches an external-protocol association to this asset (§3.2.12).
func (AssetRequirement) Bitrate ¶
func (a AssetRequirement) Bitrate(min, max int) AssetRequirement
Bitrate sets the allowed video/audio bitrate range in kbps (§3.2.1 gap #4).
func (AssetRequirement) Codecs ¶
func (a AssetRequirement) Codecs(codecs ...string) AssetRequirement
Codecs restricts the allowed video/audio codecs (§3.2.1 gap #4).
func (AssetRequirement) Count ¶
func (a AssetRequirement) Count(min, max int) AssetRequirement
Count sets the MinCount/MaxCount instance-count bounds (§3.2, п.2).
func (AssetRequirement) Duration ¶
func (a AssetRequirement) Duration(min, max float64) AssetRequirement
Duration sets the allowed video/audio duration range in seconds.
func (AssetRequirement) ExactSize ¶
func (a AssetRequirement) ExactSize(width, height int) AssetRequirement
ExactSize sets a single preferred exact size (Width/Height only, no range) — the common case for a classic fixed-size asset.
func (AssetRequirement) Focal ¶
func (a AssetRequirement) Focal(x, y float64) AssetRequirement
Focal enables a focal point on this asset with the given default anchor (§3.2.1).
func (AssetRequirement) Framerates ¶
func (a AssetRequirement) Framerates(fps ...float64) AssetRequirement
Framerates restricts the allowed video frame rates in fps (§3.2.1 gap #4).
func (AssetRequirement) GetMaxCount ¶
func (a AssetRequirement) GetMaxCount() int
GetMaxCount effective maximal number of instances (-1 = unlimited).
func (AssetRequirement) GetMinCount ¶
func (a AssetRequirement) GetMinCount() int
GetMinCount effective minimal number of instances of this asset within one ad creative (§3.2, п.2).
func (AssetRequirement) GetName ¶
func (a AssetRequirement) GetName() string
GetName of the asset, defaulting to "main".
func (AssetRequirement) IsFixedSize ¶
func (a AssetRequirement) IsFixedSize() bool
IsFixedSize reports whether this asset requires an exact size (no range).
func (AssetRequirement) IsHTML5Support ¶
func (a AssetRequirement) IsHTML5Support() bool
IsHTML5Support of the file.
func (AssetRequirement) IsImageSupport ¶
func (a AssetRequirement) IsImageSupport() bool
IsImageSupport of the file.
func (AssetRequirement) IsMain ¶
func (a AssetRequirement) IsMain() bool
IsMain asset (the default asset of a Config when no explicit name is given elsewhere).
func (AssetRequirement) IsMimeTypeSupport ¶
func (a AssetRequirement) IsMimeTypeSupport(mimePrefix string) bool
IsMimeTypeSupport of the file — allowed_types is either a short category ("image") or an exact MIME type ("image/jpeg"); an empty list means "any type is allowed" (§3.2.1).
func (AssetRequirement) IsMultiple ¶
func (a AssetRequirement) IsMultiple() bool
IsMultiple reports whether this asset may have more than one instance.
func (AssetRequirement) IsRequired ¶
func (a AssetRequirement) IsRequired() bool
IsRequired asset — unlike the old model, this is a pure getter derived from Required || MinCount>0 (no more mutating IsMain() side effect on first call, see the bug noted in §2).
func (AssetRequirement) IsSoundSupport ¶
func (a AssetRequirement) IsSoundSupport() bool
IsSoundSupport of the file.
func (AssetRequirement) IsVideoSupport ¶
func (a AssetRequirement) IsVideoSupport() bool
IsVideoSupport of the file.
func (AssetRequirement) MatchesAspectRatio ¶
func (a AssetRequirement) MatchesAspectRatio(width, height int) bool
MatchesAspectRatio reports whether the given pixel dimensions satisfy AspectRatio within a small relative tolerance (to tolerate integer rounding of real image dimensions). Always true when AspectRatio is not set.
func (AssetRequirement) MaxSize ¶
func (a AssetRequirement) MaxSize(bytes int64) AssetRequirement
MaxSize sets the maximum allowed file weight in bytes (§3.2.2).
func (AssetRequirement) MinMaxHeight ¶
func (a AssetRequirement) MinMaxHeight() (mn, mx int)
MinMaxHeight sizes, symmetric to MinMaxWidth.
func (AssetRequirement) MinMaxWidth ¶
func (a AssetRequirement) MinMaxWidth() (mn, mx int)
MinMaxWidth sizes, mirroring the semantics of the old model's method of the same name (a bare Width with no MinWidth means an exact size).
func (AssetRequirement) RangeCount ¶
func (a AssetRequirement) RangeCount() (min, max int)
RangeCount returns the effective (min, max) instance-count range.
func (AssetRequirement) Require ¶
func (a AssetRequirement) Require() AssetRequirement
Require marks the asset as mandatory.
func (AssetRequirement) RequireAltText ¶
func (a AssetRequirement) RequireAltText(maxLength int) AssetRequirement
RequireAltText marks this asset as needing an accessibility text description of at most maxLength characters (0 = unbounded), §3.2.1 gap #3.
func (AssetRequirement) Size ¶
func (a AssetRequirement) Size(minW, maxW, minH, maxH int) AssetRequirement
Size sets the allowed width/height range of the asset file.
func (AssetRequirement) SoftEqual ¶
func (a AssetRequirement) SoftEqual(asset AssetRequirement) bool
SoftEqual compares two asset requirements for compatibility purposes (used by Config.Intersec), same relaxed matching rules as the old model plus a symmetric comparison of the effective instance-count ranges via compareAspect.
func (AssetRequirement) Sound ¶
func (a AssetRequirement) Sound() AssetRequirement
Sound allows sound for this asset.
func (AssetRequirement) SupportsCodec ¶
func (a AssetRequirement) SupportsCodec(codec string) bool
SupportsCodec reports whether codec is allowed by AllowedCodecs (empty list means any codec is allowed).
func (AssetRequirement) SupportsFramerate ¶
func (a AssetRequirement) SupportsFramerate(fps float64) bool
SupportsFramerate reports whether fps is allowed by AllowedFramerates (empty list means any frame rate is allowed).
func (AssetRequirement) Types ¶
func (a AssetRequirement) Types(types ...string) AssetRequirement
Types sets the allowed asset content types (short category or exact MIME type, §3.2.1).
func (AssetRequirement) When ¶
func (a AssetRequirement) When(c Condition) AssetRequirement
When attaches a Condition controlling this asset's activity (§3.2.5).
func (AssetRequirement) WithAspectRatio ¶
func (a AssetRequirement) WithAspectRatio(ratio string) AssetRequirement
WithAspectRatio sets a direct "W:H" proportion constraint, e.g. "1.91:1" (§3.2.1 gap #1). Named WithAspectRatio, not AspectRatio, because the latter would collide with the struct field of the same name (see the package-level deviation note above).
func (AssetRequirement) WithNavigateTo ¶
func (a AssetRequirement) WithNavigateTo(screen string) AssetRequirement
WithNavigateTo marks activating this asset (e.g. a tappable hotspot image) as a fixed transition to the named sibling screen — or to the reserved "$back"/"$close" commands (§3.2.11). Named WithNavigateTo, not NavigateTo, because the latter would collide with the struct field of the same name (see the package-level deviation note above).
func (AssetRequirement) WithSafeZone ¶
func (a AssetRequirement) WithSafeZone(top, right, bottom, left float64) AssetRequirement
WithSafeZone sets the edge-inset metadata, symmetric to Focal (§3.2.1 gap #2). Insets are fractions (0..1) of the asset's own width/height.
type Binding ¶
type Binding struct {
Target string `json:"target" yaml:"target"` // "openrtb_native", "vast", "mraid", or a partner-specific name
Params map[string]any `json:"params,omitempty" yaml:"params,omitempty"` // shape defined by the adapter package for Target
}
Binding associates a Node (asset/field) or a whole Format with a concrete element of some external target representation — a bidding protocol's markup (OpenRTB Native asset, OpenRTB Video/VAST object, MRAID feature, a specific partner's proprietary JSON), by an opaque target-defined key. adformat itself has zero knowledge of what "openrtb_native" or "vast" mean — that semantics lives entirely in a small adapter package per target (see adformat/openrtbnative, adformat/openrtbvideo, adformat/tracking, adformat/vasttracking). One asset/field can carry several Bindings for several targets at once — e.g. the same "main" image asset is simultaneously the OpenRTB Native "main image" AND, for a partner that doesn't speak OpenRTB, a specific field path in their proprietary JSON.
func FindBinding ¶
FindBinding returns the first binding in bindings matching target.
func NewBinding ¶
NewBinding builds a Binding for target from an arbitrary params value by round-tripping it through encoding/json into map[string]any — used by adapter packages' constructors (ImageAsset, TitleField, Video, Tracker, ...).
type Condition ¶
type Condition struct {
// Leaf predicate: name of the controlling field/asset + one of
// In/NotIn/Present. Ignored when All/Any/Not below are non-empty.
Field string `json:"field,omitempty" yaml:"field,omitempty"`
In []any `json:"in,omitempty" yaml:"in,omitempty"`
NotIn []any `json:"not_in,omitempty" yaml:"not_in,omitempty"`
Present *bool `json:"present,omitempty" yaml:"present,omitempty"`
// Composition: combine leaf/nested conditions with boolean logic. The
// plain leaf form above still works unchanged for the common
// single-field case.
All []Condition `json:"all,omitempty" yaml:"all,omitempty"`
Any []Condition `json:"any,omitempty" yaml:"any,omitempty"`
Not *Condition `json:"not,omitempty" yaml:"not,omitempty"`
}
Condition describes when a Field, AssetRequirement or nested Config (group/param) is active (shown + eligible to be required), based on the current value of another field/asset in the same Config. Absent Condition = always active. Zero value is a valid empty leaf (matches nothing in particular — always true) so Condition can be composed by value, not just by pointer.
It replaces the old, never-implemented FormatField.Exclude: instead of declaring "if I am filled — hide them" from the controlling field's side, the dependent field declares "I am active when it equals X" from its own side — easier to read top-to-bottom when generating a form (the field's own description already tells you when it appears).
func FieldAbsent ¶
FieldAbsent builds a Condition that is true when the named field has no value (or an empty one).
func FieldIn ¶
FieldIn builds a Condition that is true when the named field's value is (or, for a repeatable field, includes) one of values.
func FieldNotIn ¶
FieldNotIn builds a Condition that is true when the named field's value is not (or, for a repeatable field, does not include) any of values.
func FieldPresent ¶
FieldPresent builds a Condition that is true when the named field has a non-empty value.
func (Condition) Eval ¶
Eval evaluates the condition tree against the current set of field/asset values (keyed by name, same map shape as used for Config.ActiveFields/ActiveAssets). It is a pure function without side effects — the schema (Condition) and the engine (Eval) stay separate, same principle as Field.Prepare.
If the referenced value is a slice (i.e. the field it points to is a repeatable/multi-select Field or AssetRequirement, see MinCount/MaxCount and IsMultiple), In/NotIn match element-wise ("at least one of the selected elements intersects with the given set", like an element-wise SQL IN rather than a whole-slice comparison) and Present means "the slice is non-empty".
type Config ¶
type Config struct {
// Name of this group (empty for the root Config).
Name string `json:"name,omitempty" yaml:"name,omitempty"`
// Title of this group for the UI.
Title string `json:"title,omitempty" yaml:"title,omitempty"`
// MinCount/MaxCount: how many instances of this group one ad
// creative carries (§3.4/§3.5) — same effective semantics as
// AssetRequirement/Field (see GetMinCount/GetMaxCount/RangeCount).
// Only legitimate when every instance is guaranteed to be part of
// one advertiser's single submission — see §3.0.
MinCount int `json:"min_count,omitempty" yaml:"min_count,omitempty"`
MaxCount int `json:"max_count,omitempty" yaml:"max_count,omitempty"`
// Entry marks this group as the starting screen of a multi-screen
// creative (§3.2.11). If no nested group is marked Entry, the first
// one in Children is assumed to be the start screen.
Entry bool `json:"entry,omitempty" yaml:"entry,omitempty"`
// Condition controls when this group is active (§3.2.5) — e.g. a
// nested "panel" that only applies for a certain layout choice.
Condition *Condition `json:"condition,omitempty" yaml:"condition,omitempty"`
// Children holds assets, fields, groups and params together, in
// authoring order.
Children []Node `json:"children,omitempty" yaml:"children,omitempty"`
}
Config is the recursive structure describing an ad format's creative (was admodels/types.FormatConfig). It is built on top of a single Children []Node list (assets + fields + groups + params, in the order the author declared them) instead of three parallel typed slices — see node.go and §3.2.7 for the rationale. There is no separate "Group" type: a nested group is simply another Config referenced by a Node of Kind NodeGroup.
Name/MinCount/MaxCount/Condition/Entry are meaningless on the root Config hanging off Format.Config — they only matter for a Config used as a nested group/screen (a Node's Group field).
func (Config) ActiveAssets ¶
func (c Config) ActiveAssets(values map[string]any) []AssetRequirement
ActiveAssets returns the top-level assets whose Condition (if any) evaluates to true against values (§3.2.5).
func (Config) ActiveFields ¶
ActiveFields returns the top-level fields whose Condition (if any) evaluates to true against values (§3.2.5).
func (Config) ActiveGroups ¶
ActiveGroups returns the top-level nested groups whose Condition (if any) evaluates to true against values.
func (Config) ActiveParams ¶
ActiveParams returns the top-level params whose Condition (if any) evaluates to true against values.
func (Config) AsEntry ¶
AsEntry marks this group as the starting screen of a multi-screen creative (§3.2.11).
func (Config) AssetByName ¶
func (c Config) AssetByName(name string) *AssetRequirement
AssetByName from config; an empty name matches the main asset.
func (Config) Assets ¶
func (c Config) Assets() []AssetRequirement
Assets returns the top-level asset requirements of this Config (does not recurse into nested groups).
func (Config) ContainsAsset ¶
func (c Config) ContainsAsset(asset AssetRequirement, revers ...bool) bool
ContainsAsset in the list of top-level assets.
func (Config) Count ¶
Count sets the MinCount/MaxCount instance-count bounds of this group (§3.4/§3.5).
func (Config) EntryGroup ¶
EntryGroup returns the nested group explicitly marked Entry, or, failing that, the first nested group in Children — the default "convention over configuration" start-screen rule from §3.2.11. The second return value is false only when there are no nested groups at all.
func (Config) Fields ¶
Fields returns the top-level fields of this Config (does not recurse into nested groups).
func (Config) GetMaxCount ¶
GetMaxCount effective maximal number of instances (-1 = unlimited).
func (Config) GetMinCount ¶
GetMinCount effective minimal number of instances of this group.
func (Config) Intersec ¶
Intersec reports whether c and other are compatible: every required top-level asset/field of one config is satisfiable by the other. Only considers top-level assets/fields, same as the old flat model — nested groups are a new structural feature and are not part of this comparison.
func (Config) IsMultiple ¶
IsMultiple reports whether this group may have more than one instance.
func (Config) MainAsset ¶
func (c Config) MainAsset() *AssetRequirement
MainAsset returns the main asset if it exists.
func (Config) RangeCount ¶
RangeCount returns the effective (min, max) instance-count range.
func (Config) RequiredField ¶
RequiredField returns a required field, optionally restricted to one of the given names — same lookup semantics as the old model.
func (Config) RequiredFieldExcept ¶
RequiredFieldExcept returns any required field not present in the given exception list.
func (Config) SimilarField ¶
SimilarField in the list of top-level fields.
func (Config) SimpleAsset ¶
func (c Config) SimpleAsset() *AssetRequirement
SimpleAsset returns the main asset in case it is the only required asset in the config.
func (Config) Validate ¶
Validate walks the whole Config tree once and checks everything that could otherwise fail silently at first use (§3.2.6):
- Every Field.RegExp compiles.
- Every Condition.Field (on a Field/AssetRequirement/nested Config/ Param) references an existing sibling name at the same tree level.
- No cycles in Condition dependencies at a given level.
- Every NavigateTo (other than the reserved "$back"/"$close") and every screen_ref Field.Options value references an existing screen (named nested group) — the set of screen names is the nearest enclosing level of group siblings: a field/asset nested directly inside one named screen (e.g. "intro") targets the screen's own siblings ("offer", ...), not something inside "intro" itself — see the worked example in multiscreen.yaml (§3.2.11).
- Every AssetRequirement.AspectRatio parses as "W:H", and BitrateMin does not exceed BitrateMax when both are set (§3.2.1 gaps #1/#4).
Call this once when a Format/Config is loaded (codec.go does this automatically for LoadYAML/LoadJSON), not on every use.
func (Config) Walk ¶
Walk calls fn for every Node in the tree rooted at c, passing a stable dotted path (e.g. "panel.headline", "offer.hotspot.target_screen") usable for error messages and for addressing a specific node from a UI editor. Recurses into nested groups depth-first, in Children order.
func (Config) WithAssets ¶
func (c Config) WithAssets(assets ...AssetRequirement) Config
WithAssets appends the given asset requirements to Children, wrapping each into a Node — the NodeKind discriminator never surfaces to the caller.
func (Config) WithFields ¶
WithFields appends the given fields to Children, wrapping each into a Node.
func (Config) WithGroups ¶
WithGroups appends the given nested Config groups to Children, wrapping each into a Node.
func (Config) WithParams ¶
WithParams appends the given params to Children, wrapping each into a Node (§3.2.14).
type Field ¶
type Field struct {
// Required marks the field as mandatory when it is active (see
// Condition below) — a Condition never overrides Required, it only
// controls whether the field participates at all.
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
// Title of the field for the UI.
Title string `json:"title,omitempty" yaml:"title,omitempty"`
// Description is helper text shown under the title in the edit UI.
Description string `json:"description,omitempty" yaml:"description,omitempty"`
// Name of the field (required, used for addressing/Condition/Binding).
Name string `json:"name" yaml:"name"`
// Type of the field data.
Type FieldType `json:"type,omitempty" yaml:"type,omitempty"`
// Options is the list of selectable values, used both for a
// single-select field and, combined with MaxCount > 1, for a
// multi-select field (§3.2.3/§3.2.15). Empty = free-form input.
Options []Option `json:"options,omitempty" yaml:"options,omitempty"`
// Min/Max: length bounds for string-like types, value bounds for
// int/float types.
Min float64 `json:"min,omitempty" yaml:"min,omitempty"`
Max float64 `json:"max,omitempty" yaml:"max,omitempty"`
// MinCount/MaxCount: how many instances of this field one ad creative
// carries — repeatable text variants (e.g. Google Responsive Ads
// style headlines) or a multi-select out of Options (§3.2.15). See
// GetMinCount/GetMaxCount/IsMultiple/RangeCount for the effective
// semantics. MaxCount == -1 means unlimited.
MinCount int `json:"min_count,omitempty" yaml:"min_count,omitempty"`
MaxCount int `json:"max_count,omitempty" yaml:"max_count,omitempty"`
// Mask is a pure UI hint for rendering a masked input (e.g.
// "+1 (999) 999-9999") — it is never used for server-side validation,
// unlike RegExp below.
Mask string `json:"mask,omitempty" yaml:"mask,omitempty"`
// RegExp is an additional/overriding validation pattern (e.g. a
// stricter phone format for a specific exchange). Unlike the old
// model, this is actually applied by Prepare (§3.2.4).
RegExp string `json:"regexp,omitempty" yaml:"regexp,omitempty"`
// Condition controls when this field is active (shown + eligible to
// be required) — replaces the dead FormatField.Exclude (§3.2.5).
Condition *Condition `json:"condition,omitempty" yaml:"condition,omitempty"`
// switches the creative to when activated (e.g. a button) — for
// structural multi-screen creatives (§3.2.11). "$back"/"$close" are
// reserved commands, not screen names.
NavigateTo string `json:"navigate_to,omitempty" yaml:"navigate_to,omitempty"`
// Bindings associate this field with external protocol
// representations (OpenRTB Native data/title asset, tracking pixel
// event, ...) — §3.2.12.
Bindings []Binding `json:"bindings,omitempty" yaml:"bindings,omitempty"`
// Multiline is the minimum textarea row count; 0 means a single-line input.
Multiline int `json:"multiline,omitempty" yaml:"multiline,omitempty"`
// Editable controls whether the field is shown in the general edit UI.
// Omitted (Valid=false) or true = shown; false = hidden.
Editable null.Bool `json:"editable,omitzero" yaml:"editable,omitempty"`
// Multilang marks the field as supporting multiple languages when editing.
Multilang bool `json:"multilang,omitempty" yaml:"multilang,omitempty"`
}
Field describes a requirement for a text/numeric/boolean value that is part of one ad creative (was admodels/types.FormatField).
func EmailField ¶
EmailField starts an email Field builder chain.
func ScreenRefField ¶
ScreenRefField starts a screen_ref Field builder chain — the advertiser picks the target screen from Options (§3.2.11).
func StringField ¶
StringField starts a string Field builder chain.
func (Field) Count ¶
Count sets the MinCount/MaxCount instance-count bounds — repeatable text variants or a multi-select out of Options (§3.2.15).
func (Field) GetMaxCount ¶
GetMaxCount effective maximal number of instances (-1 = unlimited).
func (Field) GetMinCount ¶
GetMinCount effective minimal number of instances of this field within one ad creative (§3.2.15).
func (Field) HasOptions ¶
HasOptions reports whether the field restricts values to a fixed list.
func (Field) IsEditable ¶
IsEditable reports whether the field is shown in the general edit UI. Omitted JSON (Valid=false) defaults to true.
func (Field) IsMultilang ¶
IsMultilang reports whether the field supports multiple languages when editing.
func (Field) IsMultiple ¶
IsMultiple reports whether this field may have more than one instance (repeatable field or multi-select out of Options).
func (Field) IsRequired ¶
IsRequired field value. Bool fields are never "required" in the validation sense (false is a perfectly valid value), same as the old model.
func (Field) IsValidOption ¶
IsValidOption reports whether v equals one of Options[i].Value. Always true when the field has no Options (free-form input).
func (Field) MultilineRows ¶
MultilineRows is the minimum textarea row count; 0 means a single-line input.
func (Field) Prepare ¶
Prepare validates and normalizes a single input value according to the field's Type/Min/Max/RegExp/Options. Unlike the old FormatField.Prepare, the float upper bound is actually checked, boolean and phone values are no longer silently dropped, and "url" is a real type. For a repeatable/multi-select field (IsMultiple), call Prepare once per element and use RangeCount to validate the element count separately (Prepare itself only validates one value at a time).
func (Field) RangeCount ¶
RangeCount returns the effective (min, max) instance-count range.
func (Field) SoftEqual ¶
SoftEqual compares two fields for compatibility purposes (used by Config.Intersec), same relaxed semantics as the old model: same name and either both are string-typed or both share the exact same type.
func (Field) WithDescription ¶
WithDescription sets helper text shown under the title in the edit UI.
func (Field) WithMultilang ¶
WithMultilang marks the field as supporting multiple languages when editing.
func (Field) WithMultiline ¶
WithMultiline sets the minimum textarea row count (0 = single-line input).
func (Field) WithNavigateTo ¶
WithNavigateTo marks activating this field (e.g. a button) as a fixed transition to the named sibling screen — or to the reserved "$back"/"$close" commands (§3.2.11). Named WithNavigateTo, not NavigateTo, because the latter would collide with the struct field of the same name (see the package-level deviation note above).
func (Field) WithOptions ¶
WithOptions sets the list of selectable values (§3.2.3).
func (Field) WithRegExp ¶
WithRegExp sets an additional/overriding validation pattern (§3.2.4).
type FieldType ¶
type FieldType string
FieldType is the data type of a Field value. It is a plain string, open for extension the same way Kind is.
const ( FieldStringType FieldType = "string" FieldIntType FieldType = "int" FieldFloatType FieldType = "float" FieldBoolType FieldType = "bool" FieldPhoneType FieldType = "phone" FieldEmailType FieldType = "email" FieldURLType FieldType = "url" FieldGeoType FieldType = "geo" FieldScreenRefType FieldType = "screen_ref" // §3.2.11 — advertiser picks a target screen from Options FieldDefaultType = FieldStringType )
Field type values.
type FocalPoint ¶
type FocalPoint struct {
// Enabled: whether the advertiser/editor may pin a focal point for
// this asset.
Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
// Default anchor used when the advertiser did not specify one.
// [0,0] = top-left, [0.5,0.5] = center, [1,1] = bottom-right.
Default [2]float64 `json:"default,omitempty" yaml:"default,omitempty"`
}
FocalPoint declares whether this asset role supports attaching an anchor point on the image/video content, and what to assume if the advertiser did not provide one. This is purely positioning metadata — the file itself is never modified or cropped by adformat or the ad server; the display client (widget/app) uses the anchor (typically via a CSS object-position-like mechanism) to keep the important area in frame when rendering the same file at a different aspect ratio (MGID-style native "focus point", §3.2.1). The actual anchor chosen for one particular uploaded file is data of that creative, not part of the format schema.
type Format ¶
type Format struct {
ID uint64 `json:"id,omitempty" yaml:"id,omitempty"`
Codename string `json:"codename,omitempty" yaml:"codename,omitempty"`
Title string `json:"title,omitempty" yaml:"title,omitempty"`
// Kind is the primary media/content type; Tags is the open-ended
// list of secondary classifiers (§3.2, п.1).
Kind Kind `json:"kind,omitempty" yaml:"kind,omitempty"`
Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
// Orientations supported by this creative as a whole — empty means
// "any" (§3.2.2).
Orientations []Orientation `json:"orientations,omitempty" yaml:"orientations,omitempty"`
// Version of the schema this Format was authored against — empty is
// treated as "1" (§3.2.9). Purely informational: it does not affect
// current validation, but gives future incompatible changes a place
// to branch on instead of guessing from field presence.
Version string `json:"version,omitempty" yaml:"version,omitempty"`
// Bindings associate the whole format (not any single asset/field)
// with an external protocol representation — e.g. OpenRTB Video
// Protocols/APIs/Linearity/PlaybackMethod, which have no
// protocol-agnostic equivalent on any single AssetRequirement
// (§3.2.12).
Bindings []Binding `json:"bindings,omitempty" yaml:"bindings,omitempty"`
// Sizes is the multiselect of overall display-area sizes, replacing
// the old single Width/Height/MinWidth/MinHeight pair (§3.2.13).
Sizes []SizeOption `json:"sizes,omitempty" yaml:"sizes,omitempty"`
// Config is the recursive structure of assets/fields/groups/params
// that make up this creative.
Config *Config `json:"config,omitempty" yaml:"config,omitempty"`
}
Format describes the creative that one advertiser prepares and uploads for one ad (was admodels/types.Format) — see §3.0 for the exact scope boundary (one creative of one advertiser, never a placement-level composition of several ads).
func DecodeAny ¶
DecodeAny decodes a Format from data, choosing the JSON or YAML decoder based on the file extension of name (".json" vs anything else, treated as YAML — a superset of JSON). Useful together with embed.FS, where the file name/extension is already known.
func LoadYAML ¶
LoadYAML decodes a single Format from YAML data and validates it (§3.2.6). Since Node/Config use plain yaml tags with no custom (Un)Marshal code, the YAML shape is a direct mirror of the Go structures — see node.go.
func (Format) DefaultSize ¶
func (f Format) DefaultSize() (SizeOption, bool)
DefaultSize returns the SizeOption explicitly marked Default; if none is marked and there is exactly one option, that one is the default; otherwise the first option is returned. ok is false only when Sizes is empty.
func (Format) IsFixedSize ¶
IsFixedSize reports whether every SizeOption is a plain exact size (none Flexible) — helps a UI decide whether a size picker is needed at all.
func (Format) String ¶
String representation of the format, preferring its default size when one is set.
func (Format) Suits ¶
Suits reports whether width/height matches at least one of f.Sizes. A Format with no Sizes at all (e.g. direct/popunder, native "strip" with no fixed container) suits any size — it has no display-area constraint to check.
func (Format) SupportsOrientation ¶
func (f Format) SupportsOrientation(o Orientation) bool
SupportsOrientation reports whether o is supported — an empty Orientations list means "supports any orientation" (§3.2.2).
type Kind ¶
type Kind string
Kind is the primary media/content type of an ad format (banner, video, native, ...). It is a plain, open-ended string instead of a bitmask (the old admodels/types.FormatTypeBitset was capped at 32 flags and mixed two independent axes — media type and display surface/behavior) so new values can be added without any change to this package. The secondary, open-ended axis (display surface/behavior: interstitial, dooh, tv, ingame, vr, preroll, push-notification, product-card, mraid, playable, interactive-end-card, expandable, rewarded, ...) lives in Format.Tags.
type Node ¶
type Node struct {
Kind NodeKind `json:"kind" yaml:"kind"`
Asset *AssetRequirement `json:"asset,omitempty" yaml:"asset,omitempty"`
Field *Field `json:"field,omitempty" yaml:"field,omitempty"`
Group *Config `json:"group,omitempty" yaml:"group,omitempty"` // recursion
Param *Param `json:"param,omitempty" yaml:"param,omitempty"`
}
Node is the single recursive element of the format-structure tree. Exactly one of Asset/Field/Group/Param is set, matching Kind. It replaces three parallel typed slices (Assets/Fields/Groups) that used to live directly on Config — see §3.2.7 for the rationale. Node/Config use plain json/yaml tags (no custom (Un)Marshal): the wire format is a direct mirror of this Go structure — a "children" list where every element carries an explicit "kind" plus a nested "asset"/"field"/ "group"/"param" object.
Application code is not expected to build Node values by hand — see builder.go, which exposes Asset()/StringField()/Group()/Param() constructors plus Config.WithAssets/WithFields/WithGroups/WithParams that wrap values into Node internally.
func AssetNode ¶
func AssetNode(a AssetRequirement) Node
AssetNode wraps an AssetRequirement into a Node — a small helper for the rare bare Go literal that does not go through builder.go.
func (Node) Condition ¶
Condition is a read-only proxy returning the Condition of whichever spec is set, or nil if none/not applicable.
func (Node) IsActive ¶
IsActive reports whether the node is active given the current set of field/asset values — true when the node carries no Condition, or its Condition evaluates to true against values.
func (Node) Name ¶
Name is a read-only proxy that returns the name of whichever spec (Asset/Field/Group/Param) is set — a single point of access for generic engine code (Validate, Walk, ActiveNodes) that does not need to know Kind to read this common attribute. Returns "" for a zero Node.
func (Node) NavigateTo ¶
NavigateTo is a read-only proxy returning the fixed screen-navigation target of whichever spec is set (only meaningful for asset/field, §3.2.11) — empty string means "no navigation".
type Option ¶
type Option struct {
Value any `json:"value" yaml:"value"`
Title string `json:"title,omitempty" yaml:"title,omitempty"` // if empty, a UI shows Value as-is
}
Option is a single selectable choice for a Field, rendered as a dropdown/checkbox/select control by a UI builder. Works for both string and numeric field types — Value's concrete type should match Field.Type (e.g. a string for FieldStringType, a number for FieldIntType/FieldFloatType). Replaces the old, inconsistently-shaped FormatField.Select []any (§3.2.3).
type Orientation ¶
type Orientation string
Orientation is a supported screen orientation for a creative (§3.2.2).
const ( OrientationPortrait Orientation = "portrait" OrientationLandscape Orientation = "landscape" )
Orientation values.
type Param ¶
type Param struct {
Name string `json:"name" yaml:"name"`
Value any `json:"value" yaml:"value"`
Condition *Condition `json:"condition,omitempty" yaml:"condition,omitempty"`
}
Param is a fixed, author-supplied value embedded directly in the Config tree — unlike Field, never shown to or editable by whoever fills in the ad creative. Used to carry hidden/internal context alongside the visible structure: a fixed template/layout id, a partner-specific tag, a hardcoded default consumed by the rendering engine, or any other constant that needs to travel WITH a specific group/screen (so nested Param values inside different named groups/screens can differ) rather than living as a single Format-level constant (§3.2.14).
type SafeZone ¶
type SafeZone struct {
Top float64 `json:"top,omitempty" yaml:"top,omitempty"`
Right float64 `json:"right,omitempty" yaml:"right,omitempty"`
Bottom float64 `json:"bottom,omitempty" yaml:"bottom,omitempty"`
Left float64 `json:"left,omitempty" yaml:"left,omitempty"`
}
SafeZone declares edge insets (as fractions of the asset's own width/height, 0..1) that the display client must keep free of overlaid interface chrome (logo, countdown timer, skip/close/CTA button, §3.2.1 gap #2). Exactly like FocalPoint, this is pure positioning metadata: the asset file itself is never cropped or modified by adformat or the ad server, the display client is responsible for keeping this area in mind when compositing its own controls over the creative.
type SimpleAccessor ¶
type SimpleAccessor struct {
// contains filtered or unexported fields
}
SimpleAccessor implements a basic in-memory Accessor (was admodels/types.SimpleFormatAccessor). It accepts either a static Go slice/var-table of Format values (§3.2.10) or the result of loading codec.go-produced YAML/JSON — both paths produce the same Format type, so the accessor (and any downstream validation engine) never needs to know how a Format was built.
func NewSimpleAccessor ¶
func NewSimpleAccessor(formats ...*Format) *SimpleAccessor
NewSimpleAccessor from a fixed list of formats. Accepts value or pointer formats for convenience with both Go var-table literals and codec.go decode results.
func (*SimpleAccessor) DirectFormatSet ¶
func (fa *SimpleAccessor) DirectFormatSet() *searchtypes.NumberBitset[uint]
DirectFormatSet to search.
func (*SimpleAccessor) FormatByCode ¶
func (fa *SimpleAccessor) FormatByCode(code string) *Format
FormatByCode of the model.
func (*SimpleAccessor) FormatByID ¶
func (fa *SimpleAccessor) FormatByID(id uint64) *Format
FormatByID of the model — requires Prepare (called by NewSimpleAccessor) to have run first, otherwise the binary search may silently return the wrong result.
func (*SimpleAccessor) Formats ¶
func (fa *SimpleAccessor) Formats() []*Format
Formats list collection.
func (*SimpleAccessor) FormatsBySize ¶
func (fa *SimpleAccessor) FormatsBySize(width, height int) []*Format
FormatsBySize returns the list of formats whose Sizes accept width/height; direct formats are always included, since they carry no display area at all.
func (*SimpleAccessor) Prepare ¶
func (fa *SimpleAccessor) Prepare()
Prepare sorts the format list by ID — required for FormatByID's binary search to work; called automatically by NewSimpleAccessor, but exposed for callers that mutate Formats() directly afterwards.
type SizeOption ¶
type SizeOption struct {
Title string `json:"title,omitempty" yaml:"title,omitempty"` // optional, for a UI label ("Medium Rectangle")
// Exact size, when Flexible == false (the common case — a classic
// fixed-size banner, a standard IAB size, a fixed native strip).
Width int `json:"width,omitempty" yaml:"width,omitempty"`
Height int `json:"height,omitempty" yaml:"height,omitempty"`
// Flexible: the concrete size is picked not by the format's author
// but by whoever creates a particular creative from this format
// (same principle as FocalPoint — the concrete value is data of a
// particular creative, not part of the format schema). The Min/Max*
// fields below are optional bounds on that free choice (needed for
// an iframe banner, which still must match a reasonable range of
// third-party slots rather than being fully unbounded); unset = no
// bound.
Flexible bool `json:"flexible,omitempty" yaml:"flexible,omitempty"`
MinWidth int `json:"min_width,omitempty" yaml:"min_width,omitempty"`
MaxWidth int `json:"max_width,omitempty" yaml:"max_width,omitempty"`
MinHeight int `json:"min_height,omitempty" yaml:"min_height,omitempty"`
MaxHeight int `json:"max_height,omitempty" yaml:"max_height,omitempty"`
// Default marks this option as pre-selected when there is more than
// one. Not needed when Sizes has exactly one element — the only
// option is unambiguously the default without an explicit flag.
Default bool `json:"default,omitempty" yaml:"default,omitempty"`
}
SizeOption is one selectable overall display-area size for a Format (the ad unit's outer container) — not any individual asset's file dimensions, which stay on AssetRequirement (see MinWidth/MaxWidth there). Generalizes: a single classic fixed-size banner (one exact-size SizeOption), an IAB "multi-size" ad unit (several exact-size options), and a stretchable iframe/native container (a Flexible option with its own optional bounds) — under one mechanism, for any Kind, not only banner (§3.2.13).
func FixedSize ¶
func FixedSize(title string, width, height int) SizeOption
FixedSize builds a single exact-size SizeOption (§3.2.13).
func FlexibleSize ¶
func FlexibleSize(title string, minW, maxW, minH, maxH int) SizeOption
FlexibleSize builds a flexible SizeOption with optional bounds — pass 0 for an unbounded side (§3.2.13).
func (SizeOption) AsDefault ¶
func (s SizeOption) AsDefault() SizeOption
AsDefault marks this SizeOption as pre-selected when a Format has more than one.
func (SizeOption) IsFixed ¶
func (s SizeOption) IsFixed() bool
IsFixed reports whether this option describes a single exact size (not Flexible, with both Width/Height set).
func (SizeOption) Suits ¶
func (s SizeOption) Suits(width, height int) bool
Suits reports whether the given width/height matches this size option — an exact match for a non-flexible option, or falling within Min/MaxWidth/Height for a flexible one (unset bounds = unbounded on that side).
type Thumb ¶
type Thumb struct {
Width int `json:"width,omitempty" yaml:"width,omitempty"`
Height int `json:"height,omitempty" yaml:"height,omitempty"`
}
Thumb describes one autogenerated thumbnail size for an asset — structured replacement for the old undocumented mini-DSL (`thumbs: ["250x", "350x", "500x"]`, §3.2.1). Height is optional (0 = auto, keep the source aspect ratio).
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package adformattest provides test fixtures for adformat — the counterpart of admodels/types.MockFormats(), but backed by embed.FS (via adformat/examples) instead of the old, fragile runtime.Caller(1) + os.Open("../assets/...") pair, which broke when a package was moved or vendored.
|
Package adformattest provides test fixtures for adformat — the counterpart of admodels/types.MockFormats(), but backed by embed.FS (via adformat/examples) instead of the old, fragile runtime.Caller(1) + os.Open("../assets/...") pair, which broke when a package was moved or vendored. |
|
Package examples embeds the adformat/examples/*.yaml sample formats (§4 of the design plan) via embed.FS, so they can be loaded without a fragile runtime.Caller + os.Open dance (the old admodels/types/format_mock.go approach) and reused both by tests and by adformat/adformattest.
|
Package examples embeds the adformat/examples/*.yaml sample formats (§4 of the design plan) via embed.FS, so they can be loaded without a fragile runtime.Caller + os.Open dance (the old admodels/types/format_mock.go approach) and reused both by tests and by adformat/adformattest. |
|
Package openrtbnative is a reference adformat.Binding adapter (§3.2.12) associating adformat assets/fields with OpenRTB Native 1.2 asset objects — a concrete, typed replacement for the name-based guessing that adsource-openrtb currently does (see adsource-openrtb/request/v2/builder.go), and for the always-empty FormatFileRequirement.ID/FormatField.ID of the old model.
|
Package openrtbnative is a reference adformat.Binding adapter (§3.2.12) associating adformat assets/fields with OpenRTB Native 1.2 asset objects — a concrete, typed replacement for the name-based guessing that adsource-openrtb currently does (see adsource-openrtb/request/v2/builder.go), and for the always-empty FormatFileRequirement.ID/FormatField.ID of the old model. |
|
Package openrtbvideo is a reference adformat.Binding adapter (§3.2.12) associating a whole adformat.Format with an OpenRTB Video object's properties.
|
Package openrtbvideo is a reference adformat.Binding adapter (§3.2.12) associating a whole adformat.Format with an OpenRTB Video object's properties. |
|
Package tracking is a reference adformat.Binding adapter (§3.2.16) for protocol-agnostic fire-and-forget impression/click tracking pixels, applicable to any Format.Kind (native/banner/push/direct).
|
Package tracking is a reference adformat.Binding adapter (§3.2.16) for protocol-agnostic fire-and-forget impression/click tracking pixels, applicable to any Format.Kind (native/banner/push/direct). |
|
Package vasttracking is a reference adformat.Binding adapter (§3.2.16) for the full VAST 4.x tracking-event dictionary, used by in-stream video creatives (Format.Kind == KindVideo).
|
Package vasttracking is a reference adformat.Binding adapter (§3.2.16) for the full VAST 4.x tracking-event dictionary, used by in-stream video creatives (Format.Kind == KindVideo). |