Preload Groups

Preload Groups allow you to organize placements into logical groups that should be loaded together. This is useful for coordinating the loading of related placements.

How It Works

When placements are assigned to the same preload group, htag ensures that they are loaded together. Note that their rendering is still async and not binded together, preload groups only affect the loading process.

Groups are determined by string equality - placements with identical preload group strings will be treated as part of the same group. This means that "header" and "header" are the same group, but "header" and "Header" are different groups (case-sensitive).

The guarantee runs one way only, and it is narrower than it looks.

A bid request does not hold a single group: htag fills a request up to 20 ad units, so when no single group reaches that size it packs several whole groups into one. A group that is itself 20 or larger goes alone — as a whole, above the limit. Do not read “these placements were auctioned together” as “these placements share a preload group”.

And placements in one group share a request only when the group is loaded as a group — on the initial load and on a page transition. A targeted refreshAds({ elementIds }) requests exactly the placements you named, so it will not pull in the rest of their group.

Group Naming Rules

Preload groups follow these specific rules:

• Any string value: The preload group can be any string value you choose
• String equality: Groups are considered the same if and only if their string values are exactly equal
• Case sensitive: "sidebar" and "Sidebar" are treated as different groups
• Empty string behavior: An empty string ("") means the placement declares no group, and htag never fans out from it — requesting one such placement does not pull in the others. Those that happen to be queued together still travel in one request, but nothing coordinates them. For the coordinated features below an empty group has no members at all: a roadblock on a placement without a preload group finds no companions and does nothing.

Configuration

Preload groups are configured at the placement level using the preloadGroup parameter when defining a placement with the definePlacement method.

Placements with the same preload group value will be treated as part of the same group. If preload groups are not specified, placements will be treated as separate groups.

Coordinated Features

Roadblock and high-impact bids use the preload group differently, and the difference matters when a group is misconfigured:

• Roadblock companions are resolved from the group. htag takes the placements of the bid’s own preload group and, for PARTIAL, intersects them with roadblockElementIds. A companion listed outside the group is silently dropped, and a bid whose placement has no preload group gets no companions at all.
• High-impact companions are not filtered. highImpact.companions is used exactly as written, whatever preload group those placements are in.

Keeping every participating placement in one group is still the right configuration for both — it is what makes their bids arrive in the same request and be weighed against each other. But only roadblock enforces it.

Related Concepts

• Placements: Learn more about placement configuration
• Lazy Loading: Learn about delayed loading of placements
• Roadblock: Coordinated ad delivery requiring shared preload groups
• High Impact: Mutually exclusive ad format competition requiring shared preload groups