A Publisher’s Guide to Prebid.js Legacy Native Implementation: Methods, Pitfalls, and Practical Advice

Native advertising promises better engagement by aligning ads to a publisher’s content and user experience. But integrating native demand into header bidding isn’t as turnkey as display ads, especially when using Prebid.js’ legacy native implementation methods.

If you’re responsible for ad revenue, understanding how legacy native works in Prebid.js can help you avoid common pitfalls, optimize setup across Google Ad Manager (GAM) or other ad servers, and keep control over native templating. Let’s cut through the noise and focus on the concrete details publishers actually need to implement, troubleshoot, and scale native header bidding.

How Prebid.js Legacy Native Works: The Basics

Legacy native ads in Prebid.js are constructed from flexible building blocks: assets like title, image, and brand are collected into the winning bid, then plugged into an HTML template you control. Unlike banner ads, the creative isn’t just a snippet—publishers must decide how the ad is rendered on their page or inside their ad server creative.

Key workflow steps:
– Set up your ad slot and corresponding HTML element as usual.
– Define which AdUnits are eligible for native demand, and configure which bidders support the native media type.
– Prebid.js triggers native bid requests; native assets are returned and temporarily stored client-side.
– The ad server (like GAM) makes its call as normal. If the native Prebid bid wins, the template is populated with bidder-provided assets and trackers.

Example: For a typical in-feed unit, you might request a native ad from Sharethrough and TripleLift. If Sharethrough wins, Prebid passes its image, headline, and click URL into your template—rendered in a style matching your site.

Determining Bidder Compatibility

Before rolling out native, check which of your bidders support the native format. Many do, but not all expose the same asset fields. Consult Prebid’s bidder documentation and test thoroughly for asset delivery and coverage.

Choosing Your Templating Approach: AdServer, AdUnit, or Custom Renderer

Legacy Prebid.js native offers three main ways to host and fill your native template, each with distinct operational impacts. All require disabling native targeting keys in your Prebid AdUnit config (set sendTargetingKeys: false).

AdServer-Defined Template (GAM Managed)

Template lives inside your ad server creative (e.g., a custom HTML creative in GAM), referencing Prebid macros (like ##hb_native_title##). This method gives you full ad server-level control and makes creative management straightforward, especially for teams used to running native via direct or network demand. In the ad server creative, you load native-render.js (can be self-hosted or via CDN), then call renderNativeAd() with adId and pubUrl parameters.

Best for: Teams wanting to manage updates via the ad server and keep templating centralized.

AdUnit-Defined Template (On-Page JavaScript)

The HTML template is defined directly in your Prebid AdUnit config using the adTemplate field. Prebid injects the filled template into the ad slot at render time. This gives developers greater flexibility to customize ad formats directly in code, but requires robust coordination with ad ops to ensure creatives remain stylistically compliant.

Best for: Publishers with technical resources comfortable editing JavaScript and wanting more immediate high-frequency template changes.

Custom Renderer Scenario (External JavaScript)

Here, you host an external JavaScript file pointed to by the rendererUrl field. That file must define a window.renderAd function, which Prebid calls with all native assets. This is the most advanced and scalable option for sites with highly custom rendering needs or reusable complex templates across multiple placements.

Best for: Publishers operating custom platforms, or agencies with many clients/sites using shared native ad templates.

Configuring Native Assets, Image Sizes, and Custom Fields

A well-specified native adunit defines which assets (like title, image, cta, brand) are required or optional. Publishers can be as granular as needed:

– Specify size constraints (in pixels or ratios) for images and icons depending on placement.
– Extend the standard asset set via the ext object for special bidder needs (e.g., extra tracking fields).

Image Sizing: Pixels vs. Aspect Ratios

Demand partners typically support either explicit size arrays (e.g., sizes: [150, 50]) or aspect ratios (e.g., 2:3 with minimums). Always verify which sizing convention your preferred bidders expect and test output in live preview.

Custom Assets and Inter-Bidder Variability

Not every bidder fills all assets—even basic fields like body, cta, or icon. You may also need to define custom assets (under mediaTypes.native.ext) for specific partner integrations. Prepend the asset name with the bidder code to avoid collisions, and ensure your render function or template accommodates such fields gracefully (with fallbacks if missing).

Common Pitfalls and Troubleshooting for Native Integration

Native implementations in Prebid have more moving pieces than simple banners, leading to repeat issues even for experienced teams. These are the key areas where many publishers stumble:

Not Disabling sendTargetingKeys

Failing to set sendTargetingKeys: false in your native AdUnit sends extraneous key-value pairs to the ad server, breaking the intended template population process and causing assets to go missing or display incomplete ads.

Template and Asset Mismatch

Sometimes the ad template expects assets (like ##hb_native_icon## or ##hb_native_cta##) that the winning bid doesn’t provide. Always set required: true for anything critical to your UX and be prepared to handle missing fields in your rendering logic.

Creative Rendering Failures in GAM

Relying on external scripts like native-render.js means you need proper permissions and a reliable CDN or self-host. Targeting the wrong adId pattern (especially in Send All Bids mode) is another common trip-up—auditing your creative code for adId assignment can save hours of debugging.

What this means for publishers

Legacy Prebid.js native gives publishers control over how native ads are presented, but demands careful coordination between ad tech, development, and ad ops. The flexibility in templating and asset definition can help produce better brand-safe, higher-value native placements, but missteps can lead to blank ads, lost revenue, or a poor user experience. Publishers must test deeply across device types, track rendering failures, and align native creative requirements with bidder capabilities.

Practical takeaway

For publishers running native via Prebid.js legacy methods, success hinges on clear choices: decide early where to manage creative templates (ad server, on-page, or external), and rigorously specify required assets in your native adunits. Always test with real bids from actual partners to confirm all necessary fields populate correctly.

Make sure to set sendTargetingKeys: false to avoid disrupting the workflow, and use robust error-checking in your rendering templates to handle the inherent inconsistencies of native demand. Investing the extra integration time upfront saves endless troubleshooting and maximizes both yield and user experience over time.