Skip to content

Advantage — Komplett Guide

Sist oppdatert: 2026-03-02 Advantage-bibliotek: @get-advantage/advantage ^0.11.0 Status: Topscroll, Midscroll og DoubleMidscrollSingleCreative er produksjonsklare

Hva er Advantage?

Advantage er en open source-protokoll som standardiserer high-impact annonseformater. Publishere installerer Advantage på sine sider, og kreativer kommuniserer med publisherens Advantage-wrapper via en sikker meldingskanal (MessagePort).

Kjerneprinsippet: publisherens wrapper styrer det visuelle formatet (parallax, sticky, scroll-area), mens kreativet styrer innholdet og animasjonene.

Formater vi støtter (single-tag delivery)

FormatAdvantage-enumHva det gjørScroll ProgressPreview
TopscrollTopScrollSticky header, 100% bredde, 70-80vh, parallaxNeiStandard fullscreen
MidscrollMidscrollFullskjerm midt på siden, clip-path parallaxNeiStandard fullscreen
Double Midscroll SCDoubleMidscrollSingleCreative200vh scroll-area, kreativet mottar scroll progress 0–1Ja200vh scroll-preview

Vi bruker alltid single creative-varianten av Double Midscroll. Den vanlige DoubleMidscroll og TripleMidscroll krever to separate tagger (foreground + background), som ikke passer vår leveransemodell med én tag.

Scroll Progress og Waypoints

FeatureTilgjengelig iBeskrivelse
Scroll ProgressKun DoubleMidscrollSingleCreativePublisher-wrapperen sender SCROLL_PROGRESS (0.0–1.0) via MessagePort mens brukeren scroller gjennom 200vh-området
WaypointsKun DoubleMidscroll/TripleMidscroll (to-tags)BroadcastChannel mellom forgrunn/bakgrunn-iframe. Ikke relevant for single-tag delivery

For Topscroll og Midscroll håndterer wrapperen all visuell effekt (parallax, sticky, clip-path). Kreativet trenger ikke scroll-events — det er bare en fullscreen-visning hvor wrapperen styrer presentasjonen.


Del 1 — Bygge Advantage-kreativer i Cavai

Dagens oppsett (manuelt via Script-operator)

Merk: Dette er dagens metode. Se Del 2 for den planlagte automatiseringen som fjerner behovet for manuell Script-operator.

Steg 1: Opprett kreativet

I Creative Wizard:

  1. Creative Type: Banner
  2. Format: Fullscreen
  3. Gi kreativet et beskrivende navn (f.eks. "Startsiden — Topscroll Kampanjenavn")

Alle Advantage-formater er responsive og fyller 100% av viewporten. Wrapperen på publisher-siden styrer den faktiske størrelsen (70vh for Topscroll, 100vh for Midscroll, 200vh for Double Midscroll). Kreativet trenger bare å være fullscreen.

Steg 2: Aktiver Advantage i Delivery

Gå til Delivery-tabben og slå på Enable Advantage.

Dette gjør to ting:

  • Inkluderer Advantage-kode i den kompilerte creative-bundelen (conditional compilation via #include when enableAdvantage exists)
  • Gjør ADVANTAGE og ADVANTAGE_FORMAT tilgjengelig i Script-operatorer

Uten denne togglen finnes ikke Advantage-kode i bundelen, og ADVANTAGE er udefinert i scripts.

Steg 3: Sett opp Script-operatoren

Legg til en Script-operator i starten av flowen. Denne bestemmer hvilket Advantage-format kreativet ber om. Publisherens wrapper mottar forespørselen og aktiverer formatet.

Topscroll

Enkleste formatet. Wrapperen gjør all parallax — kreativet rendrer statisk.

javascript
(() => {
  ADVANTAGE.initialize(ADVANTAGE_FORMAT.TopScroll)
    .then((ok) => {
      if (!ok) {
        console.log('TopScroll not confirmed — site may not support Advantage');
        return;
      }

      // Fade in kreativet
      const container = document.querySelector('[style*="opacity"]');
      if (container) {
        container.style.opacity = '1';
      }
    })
    .catch((err) => {
      console.log('Advantage initialize error:', err);
    });
})();

Topscroll vises som en sticky header med parallax-effekt. Wrapperen legger til en lukkeknapp og en "scroll ned"-pil automatisk.

Midscroll

Identisk oppsett som Topscroll — wrapperen gjør parallax via clip-path.

javascript
(() => {
  ADVANTAGE.initialize(ADVANTAGE_FORMAT.Midscroll)
    .then((ok) => {
      if (!ok) {
        console.log('Midscroll not confirmed');
        return;
      }

      const container = document.querySelector('[style*="opacity"]');
      if (container) {
        container.style.opacity = '1';
      }
    })
    .catch((err) => {
      console.log('Advantage initialize error:', err);
    });
})();

Double Midscroll (Single Creative)

Her mottar kreativet scroll progress (0–1) fra wrapperen. Bruk dette til å drive animasjoner basert på brukerens scroll-posisjon over 200vh.

javascript
(() => {
  ADVANTAGE.initialize(ADVANTAGE_FORMAT.DoubleMidscrollSingleCreative)
    .then((ok) => {
      if (!ok) {
        console.log('DoubleMidscrollSingleCreative not confirmed');
        return;
      }

      // Fade in
      const container = document.querySelector('[style*="opacity"]');
      if (container) {
        container.style.opacity = '1';
      }

      // Lytt til scroll progress
      ADVANTAGE.onScrollProgress((progress) => {
        const pct = Math.round(progress * 100);

        // Eksempel: flytt elementer basert på scroll
        const el = document.querySelector('.animated-element');
        if (el) {
          el.style.transform = `translateY(${progress * -200}px)`;
          el.style.opacity = Math.min(1, progress * 2);
        }

        // Trigger ting ved bestemte punkter
        if (progress >= 0.5) {
          document.querySelector('.second-scene')?.classList.add('visible');
        }
      });
    })
    .catch((err) => {
      console.log('Advantage initialize error:', err);
    });
})();

Scroll progress-verdier:

  • 0 = kreativet har akkurat kommet inn i viewporten
  • 0.5 = halvveis gjennom 200vh scroll-distansen
  • 1 = kreativet er ferdig scrollet gjennom

Steg 4: Design kreativet

Bygg innholdet i kreativet som vanlig med blokker i builderen. Noen tips:

  • Start med opacity 0 på ytterste container, og sett den til 1 i scriptet etter FORMAT_CONFIRMED. Dette forhindrer at kreativet flasher før Advantage er klart.
  • For DoubleMidscrollSingleCreative: Design med tanke på at innhold kan animeres basert på scroll. Bruk CSS-klasser som toggles ved scroll-milepæler.
  • For Topscroll og Midscroll: Design som en vanlig fullscreen-annonse. Parallax-effekten håndteres av wrapperen.
  • Responsivt: Alle Advantage-formater er responsive. Test på ulike skjermstørrelser.

Steg 5: Bygg og lever tag

Bygg kreativet som vanlig. Taggen leveres til publisheren som en standard Cavai-tag:

html
<script
  data-creative-id='46-238-472-1052'
  data-timestamp='2026-03-02T12:00:00.000Z'
>
(function() {
  var s   = document.createElement('script');
  s.src   = 'https://delivery-3.cavai.com/assets/creatives/1052/.../stub.js?bust=...';
  s.async = true;
  s.setAttribute('data-click-macro', '...');
  s.setAttribute('data-domain', '...');
  s.setAttribute('data-dsp', '...');
  document.head.appendChild(s);
})();
</script>

Taggen ser identisk ut som en vanlig Cavai-tag. Forskjellen er at den bygde bundelen inneholder Advantage-koden, og Script-operatoren sender REQUEST_FORMAT til publisherens wrapper.

Preview i builderen

Topscroll og Midscroll

Standard fullscreen-preview er alt som trengs. Wrapperen på publisher-siden styrer all parallax og sticky-oppførsel — i builderen trenger du bare å se kreativet som en vanlig fullscreen-annonse.

Bruk preview-modusene for å teste responsivt: mobil, tablet, responsive og full HD.

DoubleMidscrollSingleCreative

Når Advantage er aktivert og formatet er DoubleMidscrollSingleCreative, simulerer preview en scroll-publisher:

  • Preview-iframen blir scrollbar (200vh høyde)
  • Kreativet blir sticky (position: sticky, top: 0)
  • Scroll-events sendes til kreativet som SCROLL_PROGRESS
  • Wrapperen bekrefter alle format-forespørsler automatisk

Preview gir en god indikasjon på scroll-oppførsel, men den faktiske visuelle presentasjonen avhenger av publisherens Advantage-konfigurasjon.

Teknisk: Hva skjer under panseret

  1. Kreativet bygges med enableAdvantage — Advantage-kode inkluderes via conditional compilation (// #include when enableAdvantage exists)
  2. entry.ts kjører advantageService.initialize(stubConf.creativeType) ved oppstart (legacy-initialisering — overskrevet av Script-operatoren)
  3. Script-operatoren kaller ADVANTAGE.initialize(ADVANTAGE_FORMAT.XXX) med riktig format
  4. advantageMessenger.ts oppretter en AdvantageCreativeMessenger, starter en sesjon via postMessage, og sender REQUEST_FORMAT
  5. Publisheren bekrefter (FORMAT_CONFIRMED) eller avviser (FORMAT_REJECTED)
  6. For DoubleMidscrollSingleCreative: publisheren begynner å sende SCROLL_PROGRESS events via MessagePort

Del 2 — Planlagt automatisering

Mål

Fjerne behovet for manuell Script-operator. Brukeren velger Advantage-format i en dropdown, og plattformen håndterer alt automatisk.

Hva endres

1. Format-dropdown i Delivery

Når Enable Advantage toggles på, vises en dropdown med tilgjengelige formater:

  • Topscroll
  • Midscroll
  • DoubleMidscrollSingleCreative

Valgt format lagres som advantageFormat i delivery-innstillingene.

2. Auto-initialisering i entry.ts

Composer leser advantageFormat og inkluderer det i stubConf. entry.ts initialiserer automatisk:

typescript
// #include when enableAdvantage exists
const success = await advantageService.initialize(stubConf.advantageFormat)
if (success) {
  advantageService.onScrollProgress((progress) => {
    DataStore.scrollProgress.value = progress
  })
}
// #end

Ingen Script-operator nødvendig for Advantage-kommunikasjon.

3. Scroll Progress i DATASTORE

Ny reactive ref i DataStore: scrollProgress: ref(0).

Oppdateres automatisk av onScrollProgress-callbacken for DoubleMidscrollSingleCreative (verdi 0.0–1.0). For Topscroll/Midscroll forblir verdien 0 siden wrapperen ikke sender scroll-events.

Tilgjengelig i Script-operatorer:

javascript
// Les scroll progress i en animasjonsloop (DoubleMidscrollSingleCreative)
const progress = DATASTORE.scrollProgress.value;

// Eksempel: drive animasjoner basert på scroll
setInterval(() => {
  const p = DATASTORE.scrollProgress.value;
  myElement.style.transform = `translateY(${p * -200}px)`;
}, 16);

DATASTORE er allerede eksponert i Script-operatorer via specialAccess i Script.ts. Ingen ekstra konfigurasjon nødvendig — scrollProgress blir tilgjengelig automatisk som en del av DataStore.

4. Preview-logikk

Preview tilpasses basert på advantageFormat:

Valgt formatPreview-oppførsel
TopscrollStandard fullscreen-preview (wrapper håndterer parallax)
MidscrollStandard fullscreen-preview (wrapper håndterer clip-path)
DoubleMidscrollSingleCreative200vh scroll-preview med SCROLL_PROGRESS (eksisterende implementasjon)

5. Hva som må implementeres

Creative-Engine:

  • [ ] Legg til scrollProgress: ref(0) i DataStore (dataStore.ts)
  • [ ] Legg til advantageFormat i StubConf type (stub.ts)
  • [ ] Oppdater entry.ts: bruk stubConf.advantageFormat i stedet for stubConf.creativeType, auto-registrer scroll progress callback

Application-Frontend:

  • [ ] Legg til advantageFormat felt i delivery store (delivery.ts)
  • [ ] Legg til format-dropdown i Delivery UI (ved siden av Enable Advantage-toggle)
  • [ ] Oppdater deliveryExport.ts / TagGenerator.ts til å inkludere advantageFormat i tag settings
  • [ ] Oppdater preview-logikk: aktiver scroll-preview kun for DoubleMidscrollSingleCreative

Application-Backend:

  • [ ] Legg til advantageFormat felt i creative delivery-modellen

Composer:

  • [ ] Legg til advantageFormat i build-profilen så den flyter til stubConf

Bakoverkompatibilitet

Script-operatorer med manuell ADVANTAGE.initialize() vil fortsatt fungere. Script-kallet overskriver entry.ts-initialiseringen — akkurat som det gjør i dag. Brukere som allerede har satt opp Advantage via Script trenger ikke endre noe.


Del 3 — Publisher-guide: Implementere Advantage

Denne seksjonen er skrevet for å kunne deles med publishere (som Startsiden) som vil ta i bruk Advantage.

Forutsetninger

Publisheren trenger:

  • Tilgang til Advantage-biblioteket (open source, tilgjengelig via CDN)
  • Mulighet til å legge til HTML/JavaScript på sine sider
  • Hvis GAM brukes: mulighet til å konfigurere custom ad slots

Steg 1: Last inn Advantage-biblioteket

Legg til Advantage-scriptet på siden:

html
<script type="module">
  import { Advantage } from 'https://cdn.jsdelivr.net/npm/@get-advantage/advantage@0.11/dist/bundles/advantage.js';

  const advantage = Advantage.getInstance();
</script>

Advantage registrerer automatisk <advantage-wrapper> som en Custom Element. All kommunikasjon mellom kreativ og wrapper skjer via postMessage og MessagePort.

Steg 2: Plasser wrapper-elementer i HTML

For hver annonseplassering, legg til en <advantage-wrapper>:

html
<!-- Topscroll-plassering øverst på siden -->
<advantage-wrapper id="topscroll-slot">
  <div slot="advantage-ad-slot">
    <!-- Cavai-tag plasseres her (direkte eller via GAM) -->
  </div>
</advantage-wrapper>

<!-- Midscroll-plassering midt på siden -->
<advantage-wrapper id="midscroll-slot">
  <div slot="advantage-ad-slot">
    <!-- Cavai-tag plasseres her -->
  </div>
</advantage-wrapper>

Begrense tillatte formater per plassering

Bruk allowed-formats for å kontrollere hva som kan vises i hvert slot:

html
<!-- Kun Topscroll tillatt -->
<advantage-wrapper allowed-formats="TOPSCROLL">
  <div slot="advantage-ad-slot">...</div>
</advantage-wrapper>

<!-- Kun Midscroll og DoubleMidscrollSingleCreative tillatt -->
<advantage-wrapper allowed-formats="MIDSCROLL, DOUBLE_MIDSCROLL_SINGLE_CREATIVE">
  <div slot="advantage-ad-slot">...</div>
</advantage-wrapper>

Hvis kreativet ber om et format som ikke er i allowed-formats, svarer wrapperen med FORMAT_REJECTED og kreativet faller tilbake til standard visning.

Steg 3: Konfigurer format-integrasjoner (valgfritt)

Standard format-handlers følger med biblioteket. Men publisheren kan tilpasse oppførsel via formatIntegrations:

html
<script type="module">
  import { Advantage } from 'https://cdn.jsdelivr.net/npm/@get-advantage/advantage@0.11/dist/bundles/advantage.js';

  const advantage = Advantage.getInstance();

  advantage.configure({
    formatIntegrations: [
      {
        format: 'TOPSCROLL',
        options: {
          height: 70,                    // Viewport-høyde i % (default: 80)
          closeButtonText: 'Lukk annonse', // Norsk tekst
          autoCloseDuration: 0           // 0 = ikke auto-lukk
        },
        setup: (wrapper, adIframe) => {
          console.log('Topscroll aktivert');
          return Promise.resolve();
        }
      },
      {
        format: 'MIDSCROLL',
        setup: (wrapper, adIframe) => {
          console.log('Midscroll aktivert');
          return Promise.resolve();
        }
      },
      {
        format: 'DOUBLE_MIDSCROLL_SINGLE_CREATIVE',
        setup: (wrapper, adIframe) => {
          console.log('Double Midscroll Single Creative aktivert');
          return Promise.resolve();
        }
      }
    ]
  });
</script>

Format-opsjoner

Topscroll:

OpsjonDefaultBeskrivelse
height80Høyde i % av viewport (svh)
closeButtontrueVis lukkeknapp
closeButtonText"Close ad"Tekst på lukkeknapp
downArrowtrueVis "scroll ned"-pil
closeButtonAnimationDuration0.5Lukkeanimansjon i sekunder

Midscroll: Ingen opsjoner — wrapperen håndterer alt via CSS clip-path.

DoubleMidscrollSingleCreative: Ingen opsjoner — wrapperen setter opp 200vh scroll-area og sender scroll progress automatisk.

Steg 4: GAM-integrasjon

Hvis annonser leveres via Google Ad Manager:

Targeting-sizer

Advantage-formater bruker placeholder-sizer i GAM (ikke faktiske pikselstørrelser):

FormatAnbefalt GAM-størrelseMerknad
Topscroll1x2Standard placeholder for topscroll
Midscroll1x1Standard placeholder for midscroll
Double Midscroll SC2x1Skiller seg fra vanlig midscroll

Disse størelsene er bransjepraksis, men publisheren kan bruke egne sizer så lenge de er unike per format og ikke kolliderer med standard IAB-sizer.

GAM-oppsett

  1. Opprett en ny annonseplassering med placeholder-størrelsen
  2. Sett opp <advantage-wrapper> rundt GAM-ad-slottet:
html
<advantage-wrapper allowed-formats="TOPSCROLL">
  <div slot="advantage-ad-slot">
    <div id="gam-topscroll-slot">
      <script>
        googletag.cmd.push(function() {
          googletag.defineSlot('/publisher/topscroll', [1, 2], 'gam-topscroll-slot')
            .addService(googletag.pubads());
          googletag.pubads().enableSingleRequest();
          googletag.enableServices();
          googletag.display('gam-topscroll-slot');
        });
      </script>
    </div>
  </div>
</advantage-wrapper>
  1. I GAM: opprett en line item med Cavai-taggen som creative, targeting den nye størrelsen

Komplett eksempel: Publisher-side

Her er en komplett minimal HTML-side som støtter alle tre formater:

html
<!DOCTYPE html>
<html lang="no">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Publisher-side med Advantage</title>
</head>
<body>

  <!-- TOPSCROLL: Øverst på siden -->
  <advantage-wrapper allowed-formats="TOPSCROLL">
    <div slot="advantage-ad-slot">
      <!-- Sett inn Cavai Topscroll-tag her -->
    </div>
  </advantage-wrapper>

  <main>
    <h1>Artikkel-overskrift</h1>
    <p>Innhold her...</p>

    <!-- MIDSCROLL: Midt i innholdet -->
    <advantage-wrapper allowed-formats="MIDSCROLL, DOUBLE_MIDSCROLL_SINGLE_CREATIVE">
      <div slot="advantage-ad-slot">
        <!-- Sett inn Cavai Midscroll/Double-tag her -->
      </div>
    </advantage-wrapper>

    <p>Mer innhold her...</p>
  </main>

  <!-- Advantage-bibliotek -->
  <script type="module">
    import { Advantage } from 'https://cdn.jsdelivr.net/npm/@get-advantage/advantage@0.11/dist/bundles/advantage.js';

    const advantage = Advantage.getInstance();

    // Valgfritt: tilpass format-opsjoner
    advantage.configure({
      formatIntegrations: [
        {
          format: 'TOPSCROLL',
          options: {
            height: 70,
            closeButtonText: 'Lukk annonse'
          },
          setup: (wrapper, adIframe) => Promise.resolve()
        }
      ]
    });
  </script>

</body>
</html>

Kommunikasjonsprotokoll

For teknisk referanse — dette er meldingsflyten mellom Cavai-kreativet og publisherens Advantage-wrapper:

Cavai-kreativ (iframe)                    Publisher (advantage-wrapper)
       |                                           |
  1.   |── START_SESSION (med MessagePort) ───────>|
       |                                           |
  2.   |<──────────────────── CONFIRM_SESSION ─────|
       |                                           |
  3.   |── REQUEST_FORMAT ("TOPSCROLL") ──────────>|
       |                                           | wrapper.morphIntoFormat()
       |                                           | → setter opp CSS, UI, scroll
  4.   |<──────────────────── FORMAT_CONFIRMED ────|
       |                                           |
       |   (Kun for DoubleMidscrollSingleCreative) |
  5.   |<──────────────── SCROLL_PROGRESS (0.42) ──|
       |<──────────────── SCROLL_PROGRESS (0.43) ──|
       |<──────────────── SCROLL_PROGRESS (0.44) ──|
       |   ...                                     |

Hvis publisherens wrapper ikke støtter det forespurte formatet (f.eks. allowed-formats blokkerer det), svarer den med FORMAT_REJECTED. Kreativet kan da falle tilbake til standard visning.

Feilsøking

Kreativet vises ikke

  1. Sjekk at Advantage er aktivert i Delivery — uten dette finnes ikke ADVANTAGE i bundelen
  2. Sjekk at Script-operatoren er i flowen (med dagens oppsett) — uten scriptet sendes ingen REQUEST_FORMAT
  3. Sjekk publisher-konsollen — se etter [Advantage] log-meldinger

FORMAT_REJECTED

  • Publisheren har kanskje allowed-formats satt på wrapperen som ikke inkluderer formatet
  • Sjekk at format-strengen matcher (TOPSCROLL, MIDSCROLL, DOUBLE_MIDSCROLL_SINGLE_CREATIVE)

Scroll progress fungerer ikke (DoubleMidscrollSingleCreative)

  • Scroll progress sendes automatisk av wrapperen — kreativet trenger bare å lytte via ADVANTAGE.onScrollProgress() (dagens oppsett) eller lese DATASTORE.scrollProgress.value (etter automatisering)
  • Sjekk at du bruker DoubleMidscrollSingleCreative, ikke DoubleMidscroll (sistnevnte er for to-tags-varianten)

Kreativet flasher før Advantage er klart

  • Start med opacity: 0 på ytterste container
  • Sett opacity: 1 i scriptet etter FORMAT_CONFIRMED (etter .then((ok) => { if (ok) ... }))
  • Etter automatisering: plattformen kan håndtere dette automatisk

Referanser

Internal documentation