review: revisit render mode and rely on source param for placeholder

Author: spastorelli

packages/gitbook/src/components/Ads/Ad.tsx

@@ -73,14 +73,13 @@ export function Ad({
 
         let cancelled = false;
 
-        const preview = new URL(window.location.href).searchParams.has('ads_preview');
+        const previewParam = new URL(window.location.href).searchParams.get('ads_preview');
+        const preview = !!previewParam && previewParam !== 'placeholder';
         const realZoneId = preview ? PREVIEW_ZONE_ID : zoneId;
-        const adRenderMode =
-            preview &&
-            siteAdsStatus &&
-            (siteAdsStatus === SiteAdsStatus.Pending || siteAdsStatus === SiteAdsStatus.InReview)
-                ? 'placeholder'
-                : mode;
+        const showPlaceholderAd =
+            previewParam === 'placeholder' ||
+            (siteAdsStatus &&
+            (siteAdsStatus === SiteAdsStatus.Pending || siteAdsStatus === SiteAdsStatus.InReview))
 
         if (!realZoneId) {
             return;
@@ -91,7 +90,8 @@ export function Ad({
                 placement,
                 ignore: ignore || preview,
                 zoneId: realZoneId,
-                mode: adRenderMode,
+                mode,
+                source: showPlaceholderAd ? 'placeholder' : 'live'
             });
 
             if (cancelled) {

packages/gitbook/src/components/Ads/renderAd.tsx

@@ -13,11 +13,17 @@ interface FetchAdOptions {
     /** ID of the zone to fetch Ads for */
     zoneId: string;
     /** Mode to render the Ad */
-    mode: 'classic' | 'auto' | 'cover' | 'placeholder';
+    mode: 'classic' | 'auto' | 'cover';
     /** Name of the placement for the ad */
     placement: string;
     /** If true, we'll not track it as an impression */
     ignore: boolean;
+    /**
+     * Source of the ad (live: from the platform, placeholder: static placeholder)
+     * 
+     * Defaults to live.
+     * */
+    source?: 'live' | 'placeholder';
 }
 
 /**
@@ -26,9 +32,9 @@ interface FetchAdOptions {
  * and properly access user-agent and IP.
  */
 export async function renderAd(options: FetchAdOptions) {
-    const { mode } = options;
+    const { mode, source = 'live' } = options;
 
-    const result = mode !== 'placeholder' ? await fetchAd(options) : getPlaceholderAd();
+    const result = source === 'live' ? await fetchAd(options) : getPlaceholderAd();
     if (!result || !result.ad.description || !result.ad.statlink) {
         return null;
     }