Carregamento sob demanda de anúncios

1/**
2 * lazyAds.js — Cap. 17: "Aparecer ou Sumir"
3 *
4 * Lazy loader for ad slots based on IntersectionObserver. Ads are one of the
5 * heaviest things on a page and hurt Core Web Vitals; loading them only when
6 * they are about to enter the viewport keeps the initial render fast while
7 * still monetising below-the-fold inventory.
8 *
9 * Markup contract — mark each ad container with `data-ad-slot`:
10 *
11 *   <div data-ad-slot data-ad-format="script"
12 *        data-ad-src="https://ads.example.com/tag.js"></div>
13 *
14 *   <div data-ad-slot data-ad-format="iframe"
15 *        data-ad-src="https://ads.example.com/unit.html"
16 *        data-ad-width="300" data-ad-height="250"></div>
17 *
18 *   <div data-ad-slot data-ad-format="callback" data-ad-id="sidebar-1"></div>
19 *
20 * Supported formats:
21 *   - "script"   : injects a <script src="data-ad-src"> into the slot.
22 *   - "iframe"   : injects an <iframe src="data-ad-src"> into the slot.
23 *   - "callback" : calls options.render(slot, slotData) so you can hand off to
24 *                  a third-party SDK (e.g. googletag.display, Prebid, etc.).
25 *
26 * Everything is wrapped in try/catch and per-element error handling so one
27 * broken slot never breaks the others.
28 */
29
30/**
31 * @typedef {Object} LazyAdsOptions
32 * @property {string}  [selector]    CSS selector for ad slots. Default "[data-ad-slot]".
33 * @property {string}  [rootMargin]  IntersectionObserver rootMargin. Default "200px".
34 * @property {number}  [threshold]   IntersectionObserver threshold. Default 0.
35 * @property {Element} [root]        Optional scroll root. Default null (viewport).
36 * @property {(slot: Element, data: Object) => void} [render]
37 *           Callback used for slots with data-ad-format="callback".
38 * @property {(slot: Element, data: Object) => void} [onLoad]  Called after a slot loads.
39 * @property {(slot: Element, error: Error) => void} [onError] Called when a slot fails.
40 */
41
42/** Sensible defaults, merged with whatever the caller passes in. */
43const DEFAULT_OPTIONS = {
44  selector: "[data-ad-slot]",
45  rootMargin: "200px", // start loading ~200px before the slot is visible
46  threshold: 0,
47  root: null,
48  render: undefined,
49  onLoad: undefined,
50  onError: undefined,
51};
52
53/**
54 * Reads the `data-ad-*` attributes off a slot element into a plain object.
55 * @param {Element} slot
56 */
57function readSlotData(slot) {
58  const ds = slot.dataset || {};
59  return {
60    format: ds.adFormat || "script",
61    src: ds.adSrc || "",
62    id: ds.adId || "",
63    width: ds.adWidth || "",
64    height: ds.adHeight || "",
65    // Everything else in the dataset is passed through for callbacks.
66    dataset: ds,
67  };
68}
69
70/**
71 * Marks a slot's loading state via a data attribute and CSS-friendly class,
72 * so you can style loading / loaded / failed states.
73 * @param {Element} slot
74 * @param {"loading"|"loaded"|"failed"} state
75 */
76function setState(slot, state) {
77  slot.setAttribute("data-ad-state", state);
78}
79
80/**
81 * Loads a "script" format ad by injecting a <script> tag into the slot.
82 * Resolves/rejects via the provided callbacks (onerror handling included).
83 * @param {Element} slot
84 * @param {Object} data
85 * @param {LazyAdsOptions} options
86 */
87function loadScript(slot, data, options) {
88  if (!data.src) {
89    throw new Error("lazyAds: script slot is missing data-ad-src");
90  }
91  const script = document.createElement("script");
92  script.src = data.src;
93  script.async = true;
94
95  // Success / failure are asynchronous for network-loaded scripts.
96  script.onload = () => {
97    setState(slot, "loaded");
98    if (typeof options.onLoad === "function") options.onLoad(slot, data);
99  };
100  script.onerror = () => {
101    setState(slot, "failed");
102    if (typeof options.onError === "function") {
103      options.onError(slot, new Error(`lazyAds: failed to load ${data.src}`));
104    }
105  };
106
107  slot.appendChild(script);
108}
109
110/**
111 * Loads an "iframe" format ad by injecting an <iframe> into the slot.
112 * @param {Element} slot
113 * @param {Object} data
114 * @param {LazyAdsOptions} options
115 */
116function loadIframe(slot, data, options) {
117  if (!data.src) {
118    throw new Error("lazyAds: iframe slot is missing data-ad-src");
119  }
120  const iframe = document.createElement("iframe");
121  iframe.src = data.src;
122  if (data.width) iframe.width = data.width;
123  if (data.height) iframe.height = data.height;
124  iframe.loading = "lazy";
125  iframe.setAttribute("frameborder", "0");
126  iframe.setAttribute("scrolling", "no");
127  // Restrict what the ad iframe can do; loosen only if your provider needs it.
128  iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-popups");
129
130  iframe.onload = () => {
131    setState(slot, "loaded");
132    if (typeof options.onLoad === "function") options.onLoad(slot, data);
133  };
134  iframe.onerror = () => {
135    setState(slot, "failed");
136    if (typeof options.onError === "function") {
137      options.onError(slot, new Error(`lazyAds: failed to load ${data.src}`));
138    }
139  };
140
141  slot.appendChild(iframe);
142}
143
144/**
145 * Hands the slot off to a caller-provided render callback (third-party SDKs).
146 * @param {Element} slot
147 * @param {Object} data
148 * @param {LazyAdsOptions} options
149 */
150function loadCallback(slot, data, options) {
151  if (typeof options.render !== "function") {
152    throw new Error(
153      'lazyAds: slot uses data-ad-format="callback" but no options.render was provided',
154    );
155  }
156  // The render callback is responsible for actually drawing the ad. If it
157  // throws, the surrounding try/catch in loadSlot() marks the slot failed.
158  options.render(slot, data);
159  setState(slot, "loaded");
160  if (typeof options.onLoad === "function") options.onLoad(slot, data);
161}
162
163/**
164 * Loads a single ad slot according to its format, with robust error handling.
165 * @param {Element} slot
166 * @param {LazyAdsOptions} options
167 */
168function loadSlot(slot, options) {
169  // Guard against double-loading (e.g. if observer fires twice before unobserve).
170  if (slot.getAttribute("data-ad-state")) return;
171
172  setState(slot, "loading");
173  const data = readSlotData(slot);
174
175  try {
176    switch (data.format) {
177      case "script":
178        loadScript(slot, data, options);
179        break;
180      case "iframe":
181        loadIframe(slot, data, options);
182        break;
183      case "callback":
184        loadCallback(slot, data, options);
185        break;
186      default:
187        throw new Error(`lazyAds: unknown ad format "${data.format}"`);
188    }
189  } catch (error) {
190    // Synchronous failures (bad config, throwing render callback) land here.
191    setState(slot, "failed");
192    if (typeof options.onError === "function") {
193      options.onError(slot, error instanceof Error ? error : new Error(String(error)));
194    } else {
195      // Never let a single broken slot bubble up and break page scripts.
196      // eslint-disable-next-line no-console
197      console.error(error);
198    }
199  }
200}
201
202/**
203 * Initialises lazy ad loading.
204 *
205 * @param {LazyAdsOptions} [userOptions]
206 * @returns {{ observer: IntersectionObserver | null, destroy: () => void, refresh: () => void }}
207 *          Control object. `refresh()` re-scans the DOM for new slots (useful
208 *          for SPAs / infinite scroll); `destroy()` disconnects the observer.
209 */
210export function initLazyAds(userOptions = {}) {
211  const options = { ...DEFAULT_OPTIONS, ...userOptions };
212
213  // Fallback: if IntersectionObserver is unavailable, load everything eagerly.
214  if (typeof IntersectionObserver === "undefined") {
215    const slots = document.querySelectorAll(options.selector);
216    slots.forEach((slot) => loadSlot(slot, options));
217    return { observer: null, destroy() {}, refresh() {} };
218  }
219
220  const observer = new IntersectionObserver(
221    (entries, obs) => {
222      for (const entry of entries) {
223        if (!entry.isIntersecting) continue;
224        const slot = entry.target;
225        // Stop observing before loading so the callback can't fire twice.
226        obs.unobserve(slot);
227        loadSlot(slot, options);
228      }
229    },
230    {
231      root: options.root,
232      rootMargin: options.rootMargin,
233      threshold: options.threshold,
234    },
235  );
236
237  /** Scans the DOM and observes any not-yet-tracked slots. */
238  function refresh() {
239    const slots = document.querySelectorAll(options.selector);
240    slots.forEach((slot) => {
241      // Skip slots already loaded or already being observed.
242      if (slot.getAttribute("data-ad-state")) return;
243      if (slot.getAttribute("data-ad-observed") === "true") return;
244      slot.setAttribute("data-ad-observed", "true");
245      observer.observe(slot);
246    });
247  }
248
249  refresh();
250
251  return {
252    observer,
253    refresh,
254    destroy() {
255      observer.disconnect();
256    },
257  };
258}
259
260export default initLazyAds;

1/**
2 * preconnect.js — Cap. 17: "Aparecer ou Sumir"
3 *
4 * Injects <link rel="preconnect"> (with a <link rel="dns-prefetch"> fallback)
5 * for a list of ad / CDN origins. Preconnecting warms up the DNS + TCP + TLS
6 * handshake before the ad script is actually requested, shaving latency off
7 * the eventual load without downloading anything up front.
8 *
9 * We keep it dependency-free and idempotent: calling it twice with the same
10 * origins will not create duplicate <link> tags.
11 */
12
13/**
14 * Normalises a URL/origin string down to its origin (scheme + host + port).
15 * Returns null for invalid input so bad entries are skipped rather than thrown.
16 * @param {string} input
17 * @returns {string | null}
18 */
19function toOrigin(input) {
20  try {
21    // Accept full URLs ("https://ads.example.com/x") or bare origins.
22    const url = new URL(input, window.location.href);
23    return url.origin;
24  } catch {
25    return null;
26  }
27}
28
29/**
30 * True if a <link> with the given rel+href already exists in <head>.
31 * @param {string} rel
32 * @param {string} href
33 */
34function linkExists(rel, href) {
35  return Boolean(
36    document.head.querySelector(`link[rel="${rel}"][href="${href}"]`),
37  );
38}
39
40/**
41 * Creates and appends a <link> to <head>.
42 * @param {string} rel
43 * @param {string} href
44 * @param {boolean} crossOrigin
45 */
46function appendLink(rel, href, crossOrigin) {
47  if (linkExists(rel, href)) return; // de-dupe
48  const link = document.createElement("link");
49  link.rel = rel;
50  link.href = href;
51  // preconnect to CORS resources (most ad tags) needs the crossorigin attr,
52  // otherwise the browser opens a *second* connection for the real request.
53  if (crossOrigin) link.crossOrigin = "anonymous";
54  document.head.appendChild(link);
55}
56
57/**
58 * Adds preconnect (+ dns-prefetch fallback) hints for a list of origins.
59 *
60 * @param {string[] | string} origins  One origin/URL or a list of them.
61 * @param {{ crossOrigin?: boolean }} [opts]
62 *        crossOrigin defaults to true — most ad networks are cross-origin.
63 * @returns {string[]} The de-duplicated list of origins that were added.
64 *
65 * @example
66 *   addPreconnect([
67 *     "https://securepubads.g.doubleclick.net",
68 *     "https://www.googletagservices.com",
69 *   ]);
70 */
71export function addPreconnect(origins, { crossOrigin = true } = {}) {
72  if (typeof document === "undefined") return []; // SSR guard
73
74  const list = Array.isArray(origins) ? origins : [origins];
75
76  // Normalise + de-duplicate origins before touching the DOM.
77  const seen = new Set();
78  const added = [];
79
80  for (const entry of list) {
81    const origin = toOrigin(entry);
82    if (!origin) continue; // skip invalid
83    if (seen.has(origin)) continue; // skip duplicates within this call
84    seen.add(origin);
85
86    // dns-prefetch is the fallback for browsers that ignore preconnect and is
87    // cheap, so we add both. preconnect does the heavy lifting where supported.
88    appendLink("dns-prefetch", origin, false);
89    appendLink("preconnect", origin, crossOrigin);
90
91    added.push(origin);
92  }
93
94  return added;
95}
96
97export default addPreconnect;