# JavaScript API: otwórz agenta Nodale z własnego kodu

<https://nodale.ai/pl/docs/api>

Polecenia nodale(), które może wywołać strona: otwórz agenta z własnego przycisku lub formularza, przekaż e-mail i kontekst, zgłoś zgodę odwiedzającego.

Gdy [tag jest zainstalowany](https://nodale.ai/pl/docs), twoja strona może wysyłać mu polecenia przez jedną funkcję, `nodale()`. Są dwa polecenia: `open` i `consent`. Tag nie udostępnia żadnej innej metody i nie wysyła do twojej strony żadnego zdarzenia.

## Kolejka poleceń

Tag definiuje `window.nodale`, gdy się uruchamia. Aby wywołać polecenie, zanim tag się załaduje, wklej nad nim ten stub. Polecenia czekają w kolejce, aż tag będzie gotowy:

```html
<script>
  window.nodale = window.nodale || function(){(window.nodale.q = window.nodale.q || []).push(arguments)}
</script>
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>
```

Zachowaj `||`. Skrypt, który później przypisze `window.nodale` bez tego operatora, usuwa polecenie tagu, a późniejsze wywołania trafiają donikąd.

## `nodale('open')`

Otwiera agenta z twojego własnego kodu, na przykład z własnego przycisku albo po wysłaniu własnego formularza.

```js
nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Kontakty miesięcznie': '1500' }
})
```

Wywołanie rozpoczyna rozmowę pisemną w oknie dialogowym agenta. O mikrofon nikt nie prosi: czeka on na odwiedzającego.

### Opcje

| Opcja | Typ | Co robi |
|---|---|---|
| `email` | string | Adres e-mail odwiedzającego, gdy twoja strona już go zna. Odwiedzający jest identyfikowany przed powitaniem agenta. |
| `context` | object | To, co odwiedzający już ci powiedział, jako pary etykieta i odpowiedź. Agent otrzymuje to na początku rozmowy. Jest to zapisywane przy rozmowie i nigdy nie jest pokazywane odwiedzającemu. |

Obie są opcjonalne. Tag sprawdza argument, zanim cokolwiek opuści stronę:

- **Argument** to nic albo zwykły obiekt bez klucza innego niż `email` i `context`. W każdym innym przypadku nic się nie otwiera.
- **`email`** to string o długości od 1 do 254 znaków po przycięciu. W przeciwnym razie jest odrzucany, a agent i tak się otwiera. Tag nie ocenia adresu: to serwer decyduje, czy go przyjąć.
- **`context`** zawiera najwyżej 20 odpowiedzi. Etykieta ma od 1 do 60 znaków, odpowiedź to string o długości najwyżej 300 znaków, a etykieta jest używana raz. Etykiety i odpowiedzi są przycinane, a pusta odpowiedź jest pomijana. Jeśli jedna reguła zostanie złamana, cały kontekst jest odrzucany, nigdy obcinany, a agent i tak otwiera się bez niego.

`nodale('open')` nigdy nie rzuca wyjątku i zwraca `undefined`.

### Gdzie działa

- **Tylko na pasku i przy wyświetlaniu `hidden`.** Przy wyświetlaniu Button, z elementem inline `<div data-nodale-agent>` oraz na stronie, na której agent nie jest pokazywany (reguła stron albo udział odwiedzających), wywołanie nic nie robi. Jeśli używasz `open`, zostaw udział odwiedzających wyłączony, inaczej dla części odwiedzających wywołanie nic nie robi.
- **Zanim tag się załaduje**, przez stub podany wyżej. Odtwarzane jest tylko ostatnie `open` z kolejki, raz.
- **Jedna rozmowa.** Widget rozpoczyna najwyżej jedną rozmowę i zachowuje pierwszy e-mail i kontekst, które otrzymał. `open` w trakcie rozmowy albo po jej zakończeniu tylko pokazuje okno dialogowe.
- **Gdy agent najpierw prosi o e-mail**, wywołanie pokazuje ten krok, a twój e-mail i kontekst są wysyłane, gdy odwiedzający go zatwierdzi.

### Z przycisku

```html
<button type="button" onclick="nodale('open')">Zadaj pytanie</button>
```

### Po własnym formularzu

```js
form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Wielkość firmy': form.elements.size.value,
      'Co chce zrobić': form.elements.message.value
    }
  })
})
```

## Wyświetlanie hidden

`hidden` to wyświetlanie przestrzeni roboczej, obok paska i przycisku. Przy nim nic nie jest widoczne, dopóki twoja strona nie wywoła `nodale('open')`.

- **Strona pozostaje w pełni używalna.** Ramka agenta jest zamontowana, ale niewidoczna, i nie przechwytuje żadnego kliknięcia.
- **Po otwarciu jest to pasek.** Zamknięcie okna dialogowego wraca do paska i zachowuje rozmowę. Pasek zostaje potem do końca życia karty przeglądarki.
- **Karta przeglądarki to pamięta.** Kolejna strona twojej witryny w tej samej karcie od razu pokazuje pasek, więc odwiedzający odnajduje rozmowę. Tag przechowuje to w `sessionStorage`, w kluczu, który nie zawiera żadnego identyfikatora. Nowa karta zaczyna jako ukryta.
- **Testowane tylko w przeglądarkach Chromium.** Safari i Firefox nie są jeszcze objęte naszymi testami przeglądarek: przeglądarka, która spowalnia niewidoczne ramki, może odpowiedzieć na `open` później.

## `nodale('consent')`

Informuje tag, czy odwiedzający zgodził się na śledzenie wizyt. Użyj go, gdy twoja witryna nie ma banera cookies, który tag potrafi odczytać, albo gdy samodzielnie zarządzasz zgodą.

```js
nodale('consent', 'granted')
nodale('consent', 'revoked')
```

- **Ma znaczenie tylko wtedy, gdy śledzenie wizyt jest włączone** w twojej przestrzeni roboczej. Śledzenie jest domyślnie wyłączone, a agent jest montowany w obu przypadkach.
- **Śledzenie zaczyna od odmowy.** Przed udzieleniem zgody nic nie jest żądane i żaden plik cookie nie jest zapisywany. Przy `revoked` tag się zatrzymuje i usuwa swój plik cookie.
- **Ma pierwszeństwo przed każdym banerem.** Gdy twoja strona już je wywołała, tag stosuje się do twojego wywołania i ignoruje to, co mówi baner.
- **Global Privacy Control wygrywa ze wszystkim.** Przeglądarka, która go wysyła, pozostaje w stanie odmowy przez całą wizytę, cokolwiek wywoła twoja strona.

Bez tego wywołania tag odczytuje odpowiedź z narzędzia do zarządzania zgodami na stronie: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, baner HubSpot, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP i Google Consent Mode v2. Niektóre z nich wymagają zadeklarowania Nodale jako dostawcy lub usługi: przewodnik po śledzeniu wizyt w aplikacji podaje konfigurację dla każdego z nich.

## Debugowanie

Tag nigdy nie rzuca wyjątku do twojej strony. Tłumaczy się przez `console.debug`, w liniach zaczynających się od `nodale tag:`. Włącz poziom verbose w konsoli przeglądarki, aby je zobaczyć.

| Linia | Co się stało |
|---|---|
| `open refused` | Argument nie jest zwykłym obiektem albo zawiera klucz inny niż `email` i `context`. |
| `open email dropped` | `email` nie jest stringiem o długości od 1 do 254 znaków. |
| `open context dropped` | `context` łamie jedną ze swoich reguł. |
| `open needs the floating or hidden display` | Przestrzeń robocza używa wyświetlania Button albo strona montuje agenta inline. |
| `open: agent not on this page` | Reguła stron albo udział odwiedzających wyłącza agenta na tej stronie. |
| `open not acknowledged` | Widget nie odpowiedział w ciągu 30 sekund. |

## Docs

- [Zainstaluj agenta Nodale na swojej witrynie](https://nodale.ai/pl/docs): Jeden tag script umieszcza agenta Nodale na twojej witrynie. Gdzie go wkleić, na co witryna musi zezwalać i jak sprawdzić, że działa. (Markdown: https://nodale.ai/pl/docs.md)
- [Serwer MCP: zarządzaj przestrzenią Nodale z Claude Code](https://nodale.ai/pl/docs/mcp): Połącz Claude Code z serwerem MCP Nodale, potem odczytuj i zmieniaj przestrzeń roboczą: wiedzę, materiały demo, ustawienia agenta, witryny, wdrożenie. (Markdown: https://nodale.ai/pl/docs/mcp.md)
