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.