← Hilfe

JavaScript-API für Entwickler

Für die meisten Websites reicht der Einbettcode aus dem Dashboard. Wer mehr will, zum Beispiel einen eigenen Button „Avatar wieder öffnen“, eigenes Tracking oder eine Single-Page-App, steuert den Avatar über window.SAYSW.

Ohne JavaScript: Button zum Wiederöffnen

Hat ein Besucher den Avatar geschlossen, öffnet ihn jedes Element mit data-saysw-open wieder:

<button type="button" data-saysw-open>Video ansehen</button>

Mit einer Produkt-ID öffnet der Button einen bestimmten Avatar, auch einen anderen Avatar aus deinem Konto, der auf der Seite noch gar nicht eingebunden war:

<img src="produkt.jpg" alt="Unser Produkt" data-saysw-open="12345678">

Die Produkt-ID (8 Ziffern) steht im Dashboard beim Avatar.

Einbinden

Lege die Befehle in die Warteschlange SAYSW.cmd. Sie laufen, sobald der Player geladen ist, egal ob dein Script vor oder nach dem Einbettcode steht.

<script>
  window.SAYSW = window.SAYSW || {};
  (SAYSW.cmd = SAYSW.cmd || []).push(function (api) {
    api.on('unmute', function (e) { console.log('Ton an', e.pid); });
    api.on('ctaclick', function (e) {
      e.preventDefault();            // Player öffnet den Link nicht
      myRouter.push(e.detail.url);   // eigenes Routing
    });
  });
</script>

Beispiele

Avatar nach 60 Sekunden wieder öffnen, wenn er geschlossen wurde:

window.SAYSW = window.SAYSW || {};
(SAYSW.cmd = SAYSW.cmd || []).push(function (api) {
  api.on('close', function () {
    setTimeout(function () { api.open(); }, 60000);
  });
});

Beim Klick auf ein Bild einen anderen Avatar zeigen:

document.querySelector('#produktbild').addEventListener('click', function () {
  window.SAYSW = window.SAYSW || {};
  (SAYSW.cmd = SAYSW.cmd || []).push(function (api) { api.open(12345678); });
});

Einwilligung aus dem eigenen Cookie-Banner weitergeben:

window.SAYSW = window.SAYSW || {};
(SAYSW.cmd = SAYSW.cmd || []).push(function (api) { api.consent(true); });

Mehr dazu unter Cookie-Banner anbinden.

SAYSW

Mitglied Beschreibung
version Version des Players, z. B. "2.2.0"
cmd.push(fn) Befehl in die Warteschlange, fn(SAYSW)
ready() Promise mit der Liste der Avatare, sobald der erste bereit ist
list() alle offenen Avatare
get(pidOrIndex?) Avatar nach Produkt-ID oder Index, ohne Argument der erste
open(pid?) Avatar öffnen. Ohne pid den zuletzt geschlossenen, mit pid einen bestimmten (wird bei Bedarf nachgeladen)
consent(value?) Einwilligung setzen (true/false) oder lesen
on(type, fn) / off(type, fn) Ereignisse aller Avatare, '*' für alle. on gibt eine Abmeldefunktion zurück
scan() neu eingefügte <div class="ssw-widget" data-pid="…"> laden (Single-Page-Apps)

Ein Avatar

SAYSW.get() und die Ereignisse liefern ein Steuerobjekt:

Eigenschaft/Methode Beschreibung
pid, index, element Produkt-ID, Nummer auf der Seite, das div.ssw-widget
state 'loading', 'muted', 'playing', 'stopped' oder 'closed'
currentTime, duration, muted, infoOpen, ctaVisible, size aktueller Stand, nur lesen
play() mit Ton abspielen. Browser erlauben Ton nur nach einem Klick des Besuchers
mute() zurück in die stumme Vorschau
stop() anhalten und zurückspulen
close() schließen, wie das ×
reopen() geschlossenen Avatar an derselben Stelle wieder öffnen
seek(s) zu Sekunde s springen
volume(v?) Lautstärke 0 bis 1 setzen oder lesen
openInfo(), closeInfo() Info-Fenster öffnen oder schließen
clickCta() Ziel des sichtbaren Buttons öffnen
on, once, off Ereignisse dieses Avatars

Ereignisse

Jedes Ereignis hat type, pid, index und detail. Zusätzlich gibt es am div.ssw-widget ein DOM-Ereignis saysw:<type>, zum Beispiel el.addEventListener('saysw:close', …).

type Wann detail
ready Video geladen, Avatar erscheint –
statechange Zustand gewechselt {state}
unmute Ton an –
mute zurück in die stumme Vorschau –
stop angehalten –
progress gesehener Anteil steigt {percent}
timeupdate etwa alle 0,4 s {currentTime, duration}
ctashow, ctahide Button erscheint oder verschwindet {text, url}
ctaclick Klick auf den Button, mit preventDefault() abbrechbar {url, target, text}
infoopen, infoclose Info-Fenster –
ended Video mit Ton bis zum Ende gesehen –
close Avatar geschlossen –

Datenschutz

Die API ändert nichts am Datenschutz: Ohne Einwilligung setzt der Avatar kein Cookie und meldet keine Nutzungsdaten. Ereignisse, die du mit on() empfängst, bleiben in deiner Seite. Wenn du sie an ein eigenes Analyse-Tool weitergibst, brauchst du dafür die passende Einwilligung deiner Besucher.