Kanál

Vložení widgetu na váš web

Tento průvodce ukazuje, jak přidat chat Breezaro na jakýkoli web vložením krátkého úryvku do HTML vašich stránek.

  • Funguje na jakékoli platformě, kde můžete upravit HTML nebo přidat blok vlastního kódu.
  • Není potřeba programovat. Zkopírovat, vložit, zveřejnit.
  • Hotovo během několika minut.
Krok za krokem

Kroky instalace

Postupujte podle těchto kroků pro přidání widgetu Breezaro na váš web.

1. Otevřete editor HTML nebo vlastního kódu na svém webu

Nastavení vlastního kódu v tvůrci webu

2. Vložte úryvek Breezaro

Vložení úryvku do bloku vlastního kódu
<script data-app-id="YOUR_APP_ID" src="https://breezaro.com/breezaro-widget.js" defer></script>

3. Vložte jej na všechny stránky těsně před uzavírací značku body

Výběr, kde se úryvek spustí
Výběr, kde se úryvek spustí

4. Uložte a zveřejněte

Widget spuštěný na webu
Krok za krokem

Ovládání widgetu z vašeho webu

Widget vystavuje malé JavaScriptové API. Použijte ho, když chcete chat otevřít vlastním tlačítkem nebo asistentovi sdělit, kdo je přihlášený návštěvník.

identify
Přihlásí návštěvníka, aby asistent mohl pracovat s jeho ověřenou identitou.
open
Otevře okno chatu.
close
Zavře okno chatu.
reset
Ukončí konverzaci navázanou na aktuální identitu. Zavolejte ho při odhlášení nebo přepnutí účtu. Po resetu je neoznačené identify odmítnuto až do znovunačtení stránky, takže při dalším volání identify na téže stránce předejte aktuální resetId jako čtvrtý argument.

Volání po načtení widgetu

Jakmile načítací skript proběhne, je window.breezaro připravené a můžete volat kterýkoli příkaz přímo. Tohle je běžný případ u jednostránkových aplikací nebo když se návštěvník přihlásí bez znovunačtení stránky.

JavaScript
breezaro('open');

Volání před načtením widgetu

Pokud musí volání proběhnout dřív, třeba když se stránka vykresluje na serveru a už ví, kdo návštěvník je, vložte nad načítací skript frontu. Ta volání zaznamená a přehraje je, jakmile je widget připravený.

HTML
<script>
  window.breezaro =
    window.breezaro ||
    function () {
      (window.breezaro.q = window.breezaro.q || []).push(arguments);
    };
  breezaro('open');

  // Queue 'identify' only WITH the current resetId. An untagged queued
  // identify is refused once this browser has ever signed out, because
  // nothing bounds when it was pushed.
  breezaro('identify', identity, undefined, { resetId: breezaroResetId() });
</script>

Obnovení podpisu na dlouho otevřené stránce

Platnost se kontroluje ve chvíli, kdy widget payload odešle, ne když zavoláte identify. Návštěvník, který stránku načte, nechá ji na pozadí a chat otevře až po hodinách, předloží několik hodin starý podpis a ten je odmítnutý. Asistent si místo toho řekne o kód z e-mailu.

Při běžném prohlížení se podpis obnovuje sám, protože každé načtení stránky razí nový. Jednostránková aplikace nebo stránka otevřená celé odpoledne ale ne. Stáhněte si v takovém případě ze svého backendu čerstvý podpis a zavolejte identify znovu, jakmile se karta vrátí do popředí.

Generaci resetu si přečtěte ještě před odesláním požadavku a předejte ji jako čtvrtý argument. Odhlášení, které proběhne během požadavku, tuto generaci posune a widget potom opožděnou identitu odmítne, místo aby zapsal identitu předchozího účtu do konverzace, kterou už používá další návštěvník.

JavaScript
const BREEZARO_APP_ID = 'YOUR_APP_ID';

function breezaroResetId() {
  try {
    const reset = JSON.parse(
      localStorage.getItem('breezaro-widget_reset_' + BREEZARO_APP_ID),
    );

    return typeof reset?.id === 'string' ? reset.id : null;
  } catch {
    return null;
  }
}

document.addEventListener('visibilitychange', async () => {
  if (document.visibilityState !== 'visible') return;

  // Read the generation BEFORE the round trip, not after it.
  const resetId = breezaroResetId();

  // Your own endpoint: it signs a fresh payload server-side, where the
  // secret lives, and returns { email, name, externalId, issuedAt, nonce, hmac }.
  const identity = await fetch('/my-api/breezaro-identity').then((r) => r.json());

  breezaro('identify', identity, undefined, { resetId });
});

Při odhlášení návštěvníka widget resetujte

Zavolejte reset ve chvíli, kdy se někdo odhlašuje, a vlastní odhlášení pak dokončete bez ohledu na to, co widget odpoví: zablokovaný nebo nenačtený skript nesmí návštěvníka nikdy uvěznit v relaci, kterou ukončil. Pokud se reset v krátkém časovém limitu nepotvrdí jako trvale uložený, zapište čerstvou značku resetu do resetovacího klíče widgetu sami, jak to dělá ukázka, aby další načtení stránky začalo s čistou konverzací. Resetujte i pokaždé, když se přihlášená osoba změní, například když návštěvník přepne účet bez načtení stránky, a když platnost přihlášení vyprší sama.

JavaScript
async function signOut() {
  // Ask the widget to reset, then sign out no matter what it answers: a blocked
  // or unmounted loader must never trap the user in a session they ended.
  const confirmed = await new Promise((resolve) => {
    const done = setTimeout(() => resolve(false), 500);

    breezaro('reset', undefined, (result) => {
      clearTimeout(done);
      resolve(Boolean(result?.ok && result.durable));
    });
  });

  // If the widget could not confirm a durable reset (ad blocker, storage error,
  // never mounted), write the marker the loader reads on the next load so the
  // next visitor starts a clean conversation instead of restoring this one.
  if (!confirmed) {
    try {
      localStorage.setItem(
        'breezaro-widget_reset_' + BREEZARO_APP_ID,
        JSON.stringify({ id: crypto.randomUUID(), at: Date.now() }),
      );
    } catch (_) {}
  }

  await fetch('/my-api/sign-out', { method: 'POST' });
  window.location.assign('/');
}