From 00c7f1584edbb2561c444437c9af52dfdcdc6b44 Mon Sep 17 00:00:00 2001
From: Demetrio Girardi <dgirardi@prebid.org>
Date: Tue, 7 Oct 2025 07:21:13 -0700
Subject: [PATCH] Recommend hb_ver over @latest for PUC

---
 _includes/mobile/gam-native-adops.html        |  2 +-
 adops/adops-general-sbs.md                    |  5 +++-
 adops/creative-considerations.md              |  6 ++---
 adops/gam-creative-banner-sbs.md              | 18 ++++++++++---
 adops/gam-native.md                           |  2 +-
 ...g-up-prebid-with-the-appnexus-ad-server.md |  2 +-
 dev-docs/publisher-api-reference/setConfig.md | 26 +++++++++++++++++++
 overview/prebid-universal-creative.md         |  4 ++-
 prebid/native-implementation-legacy.md        |  6 ++---
 prebid/native-implementation.md               |  6 ++---
 10 files changed, 59 insertions(+), 18 deletions(-)

diff --git a/_includes/mobile/gam-native-adops.html b/_includes/mobile/gam-native-adops.html
index 07bba2763c..896a280030 100644
--- a/_includes/mobile/gam-native-adops.html
+++ b/_includes/mobile/gam-native-adops.html
@@ -20,7 +20,7 @@ <h1><a target="_blank" href="hb_native_linkurl" class="pb-click">hb_native_title
 		      <div class="attribution">hb_native_brand</div>
 		    </div>
 		  </div>
-		  <script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/native-trk.js"></script>
+		  <script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist/native-trk.js"></script>
 		  <script>
 		    var pbNativeTagData = {};
 		    pbNativeTagData.uuid = "%%PATTERN:hb_cache_id%%";
diff --git a/adops/adops-general-sbs.md b/adops/adops-general-sbs.md
index ae8a64eff6..369b71de20 100644
--- a/adops/adops-general-sbs.md
+++ b/adops/adops-general-sbs.md
@@ -116,6 +116,8 @@ If your ad server supports targeting creatives within the line item, it could co
 
 You’ve now added all fields required for targeting Prebid line items. You can add any other line item options you would normally use, such as additional targeting for geography. When you’ve filled in all the appropriate fields, save your line item.
 
+<a id="create-creatives" ></a>
+
 ## Create Your Creatives
 
 The process of creating your creatives will differ based on the type of creative.
@@ -131,7 +133,7 @@ We recommend using the [Prebid Universal Creative](/overview/prebid-universal-cr
 If you’re working with banner or in-renderer creatives, the HTML you’ll enter in the creatives will be similar to the following (utilizing whatever macro format is supported by your ad server):
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/%%PATTERN:hb_format%%.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist/%%PATTERN:hb_format%%.js"></script>
 <script>
   var ucTagData = {};
   ucTagData.adServerDomain = "";
@@ -157,6 +159,7 @@ If you’re working with banner or in-renderer creatives, the HTML you’ll ente
 * Replace `%%MACRO%%` with the appropriate macro for your ad server. (Refer to your ad server’s documentation or consult with a representative for specific details regarding the proper macros and how to use them.)
 * Replace BIDDERCODE with the appropriate code for the bidder your line item is targeting. For example, if you’re targeting BidderA, the macro variable for adId might look like `ucTagData.adId = "%%PATTERN:hb_adid_BidderA%%";`.
 * If you're hosting your own Prebid Universal Creative, make sure it's version 1.15 or later, or replace `%%PATTERN:hb_format%%.js` with `creative.js`.
+* The `hb_ver` targeting key, used above to construct the Prebid Universal Creative CDN URL, requires Prebid.js 10.11.0 or later. If that's not available, substitute `%%PATTERN:hb_ver%%` with a particular PUC version.   
 
 The example above uses the jsdelvr CDN as the domain from which the creative will serve. However, you may obtain the creative from a managed service or host it yourself. You might need to edit the creative and make adjustments to your creative settings depending on the CDN you're using.
 
diff --git a/adops/creative-considerations.md b/adops/creative-considerations.md
index 510dad5bcc..de5d2ecfea 100644
--- a/adops/creative-considerations.md
+++ b/adops/creative-considerations.md
@@ -66,8 +66,8 @@ the actual PUC.
 
 If you choose to use the Prebid Universal Creative, you'll need to decide where to load it from:
 
-1. Prebid hosts an always-up-to-date copy of the PUC code at `https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/*`. The upside of this location is that it's automatically updated so it contains new features automatically. The potential downside is that Prebid controls when it's upgrades.
-1. You can host the PUC at your own location. The upside of this option is that you can control when upgrades happen.
+1. Prebid hosts each PUC version at `https://cdn.jsdelivr.net/npm/prebid-universal-creative@${VERSION}/dist/*` - substitute `${VERSION}` with a version number. Using Prebid.js 10.11.0 or later, you may also use the `hb_ver` targeting key; see [create your creatives](/adops/adops-general-sbs.html#create-your-creatives).
+1. You can host the PUC at your own location. The upside of this option is more control over when upgrades happen.
 1. You can copy the body of the PUC into your ad server creative directly. This eliminates a browser fetch, but could make upgrades more difficult.
 
 ### Prebid.js 'dynamic creatives'
@@ -115,7 +115,7 @@ VAST URL required. See the [GAM Prebid Mobile Rendering Ad Ops](/adops/mobile-re
 {: .table .table-bordered }
 | :memo: Use Cases          |
 |:---------------------------|
-| - Prbeid.js Native |
+| - Prebid.js Native |
 
 Native ads require close collaboration between web designers, engineering, and ad ops. The primary decision to be made that affects ad ops is where to store the rendering template. The options are:
 
diff --git a/adops/gam-creative-banner-sbs.md b/adops/gam-creative-banner-sbs.md
index ab8e732a7a..abbd716c17 100644
--- a/adops/gam-creative-banner-sbs.md
+++ b/adops/gam-creative-banner-sbs.md
@@ -56,13 +56,18 @@ These instructions assume you're using the Prebid Universal Creative (PUC) after
 {: .alert.alert-warning :}
 Be sure to replace BIDDERCODE with the appropriate bidder. For example, if the bidder code is `PBbidder`, the `adid` would be `%%PATTERN:hb_adid_PBbidder%%`.
 
-Also, replace "PUCFILE" with:
+Replace "PUCFILE" with:
 
 - Prebid.js: "%%PATTERN:hb_format%%.js"
 - Prebid Mobile: "creative.js"
 
+Replace "VERSION" with:
+
+- Prebid.js 10.11.0 or later: "%%PATTERN:hb_ver%%"
+- Otherwise, a specific PUC version.
+
 ```html
-<script src = "https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/PUCFILE"></script>
+<script src = "https://cdn.jsdelivr.net/npm/prebid-universal-creative@VERSION/dist/PUCFILE"></script>
 <script>
   var ucTagData = {};
   ucTagData.adServerDomain = "";
@@ -99,13 +104,18 @@ Warning: Be sure none of the attribute names are longer than 20 characters. See
 
 In top-price mode, you can make use of the GAM `TARGETINGMAP` feature instead of listing out each attribute.
 
-Be sure to replace "PUCFILE" with:
+Replace "PUCFILE" with:
 
 - Prebid.js: "%%PATTERN:hb_format%%.js"
 - Prebid Mobile: "creative.js"
 
+Replace "VERSION" with:
+
+- Prebid.js 10.11.0 or later: "%%PATTERN:hb_ver%%"
+- Otherwise, a specific PUC version.
+
 ```html
-<script src = "https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/PUCFILE"></script>
+<script src = "https://cdn.jsdelivr.net/npm/prebid-universal-creative@VERSION/dist/PUCFILE"></script>
 <script>
   var ucTagData = {};
   ucTagData.adServerDomain = "";
diff --git a/adops/gam-native.md b/adops/gam-native.md
index e9e8b17610..e331b85f91 100644
--- a/adops/gam-native.md
+++ b/adops/gam-native.md
@@ -104,7 +104,7 @@ Example creative HTML:
     <div class="attribution">##hb_native_brand##</div>
   </div>
 </div>
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/%%PATTERN:hb_format%%.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist/%%PATTERN:hb_format%%.js"></script>
 <script>
     var pbNativeTagData = {};
     pbNativeTagData.pubUrl = "%%PATTERN:url%%";
diff --git a/adops/setting-up-prebid-with-the-appnexus-ad-server.md b/adops/setting-up-prebid-with-the-appnexus-ad-server.md
index 43aa5ca4c1..cfff8b85d0 100644
--- a/adops/setting-up-prebid-with-the-appnexus-ad-server.md
+++ b/adops/setting-up-prebid-with-the-appnexus-ad-server.md
@@ -80,7 +80,7 @@ Follow the banner creative setup instructions in [Add Creatives](https://docs.xa
 * Self-Audit the creative and confirm compliance.
 
 ```html
-<script src = "https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/#{HB_FORMAT}.js"></script>
+<script src = "https://cdn.jsdelivr.net/npm/prebid-universal-creative@#{HB_VER}/dist/#{HB_FORMAT}.js"></script>
 <script>
   var ucTagData = {};
   ucTagData.adServerDomain = window.location.host;
diff --git a/dev-docs/publisher-api-reference/setConfig.md b/dev-docs/publisher-api-reference/setConfig.md
index 2a4eb21edb..d42f354ee7 100644
--- a/dev-docs/publisher-api-reference/setConfig.md
+++ b/dev-docs/publisher-api-reference/setConfig.md
@@ -713,6 +713,7 @@ The `targetingControls` object passed to `pbjs.setConfig` provides some options
 | allBidsCustomTargeting | Boolean | Set to true to prevent custom targeting values from being set for non-winning bids |
 | lock               | Array of Strings | Targeting keys to lock |
 | lockTimeout        | Integer          | Lock timeout in milliseconds                                   |
+| version            | String           | Value to set in the `hb_ver` targeting key |
 
 {: .alert.alert-info :}
 Note that this feature overlaps and can be used in conjunction with [sendBidsControl.bidLimit](#setConfig-Send-Bids-Control).
@@ -937,6 +938,31 @@ If using standard targeting `hb_adid` is unique for each bid, so this would have
 
 <a name="setConfig-Configure-Responsive-Ads"></a>
 
+#### Details on the version setting
+{: .no_toc }
+
+Since version 10.11.0, Prebid populates the `hb_ver` targeting key with a recommended version of Prebid Universal Creative. This should be used in ad server creatives to fetch that particular version of PUC (see for example [general prebid ad server setup](/adops/adops-general-sbs.html#create-creatives)).
+
+You may set a different value for `hb_ver` using `version`:
+
+```javascript
+pbjs.setConfig({
+   targetingControls: {
+     version: '1.17.2'
+   }
+})
+```
+
+Or disable it by setting `false`: {
+
+```javascript
+pbjs.setConfig({
+  targetingControls: {
+    version: false
+  }
+})
+```
+
 ### Configure Responsive Ads
 
 See the [size mapping](/dev-docs/modules/sizeMapping.html) or [advanced size mapping](/dev-docs/modules/sizeMappingV2.html) modules.
diff --git a/overview/prebid-universal-creative.md b/overview/prebid-universal-creative.md
index e691b8fcc4..9a1c5c8e7f 100644
--- a/overview/prebid-universal-creative.md
+++ b/overview/prebid-universal-creative.md
@@ -36,8 +36,10 @@ Note that as of PUC v1.15, the recommended way of loading the creative
 in the ad server involves using the `hb_format` ad server key-value. Before 1.15, the ad server needed to load creative.js which covered banner and in-renderer video, or native-render.js for native. 1.15 simplifies this
 by allowing the ad server creative to load banner.js, video.js, or native.js, which can be done programmatically using ad server macros. e.g.
 
+Since version 10.11.0, Prebid.js populates the `hb_ver` ad server key-value which is recommended for selecting a specific PUC version.
+
 ```html
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/%%PATTERN:hb_format%%.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist/%%PATTERN:hb_format%%.js"></script>
 ```
 
 This loads the PUC from the Prebid-maintained location. Your managed
diff --git a/prebid/native-implementation-legacy.md b/prebid/native-implementation-legacy.md
index 6ae5c5808c..77d5ff08ad 100644
--- a/prebid/native-implementation-legacy.md
+++ b/prebid/native-implementation-legacy.md
@@ -221,7 +221,7 @@ Example creative HTML:
     <div class="attribution">##hb_native_brand##</div>
   </div>
 </div>
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/native-render.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist/native-render.js"></script>
 <script>
     var pbNativeTagData = {};
     pbNativeTagData.pubUrl = "%%PATTERN:url%%";     // GAM specific
@@ -335,7 +335,7 @@ Even though the body of the native creative is defined in the AdUnit, an AdServe
 Example Creative HTML
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/native-render.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist/native-render.js"></script>
 <script>
     var pbNativeTagData = {};
     pbNativeTagData.pubUrl = "%%PATTERN:url%%";     // GAM specific
@@ -399,7 +399,7 @@ Even though the body of the native creative is defined in the external JavaScrip
 Example creative HTML:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/native-render.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist/native-render.js"></script>
 <script>
     var pbNativeTagData = {};
     pbNativeTagData.pubUrl = "%%PATTERN:url%%";    // GAM specific
diff --git a/prebid/native-implementation.md b/prebid/native-implementation.md
index 7a036a873b..6e43a8891e 100644
--- a/prebid/native-implementation.md
+++ b/prebid/native-implementation.md
@@ -292,7 +292,7 @@ Example creative HTML:
     <div class="attribution">##hb_native_asset_id_3##</div>
   </div>
 </div>
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/%%PATTERN:hb_format%%.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist/%%PATTERN:hb_format%%.js"></script>
 <script>
     var pbNativeTagData = {};
     pbNativeTagData.pubUrl = "%%PATTERN:url%%";     // GAM specific
@@ -436,7 +436,7 @@ Even though the body of the native creative is defined in the AdUnit, an AdServe
 Example Creative HTML
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist//%%PATTERN:hb_format%%.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist//%%PATTERN:hb_format%%.js"></script>
 <script>
     var pbNativeTagData = {};
     pbNativeTagData.pubUrl = "%%PATTERN:url%%";     // GAM specific
@@ -526,7 +526,7 @@ Even though the body of the native creative is defined in the external JavaScrip
 Example creative HTML:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist//%%PATTERN:hb_format%%.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@%%PATTERN:hb_ver%%/dist//%%PATTERN:hb_format%%.js"></script>
 <script>
     var pbNativeTagData = {};
     pbNativeTagData.pubUrl = "%%PATTERN:url%%";    // GAM specific