# Com incrustar un assistent GUIAT a la teva web

Aquest document explica com mostrar un assistent guiat publicat per
l'AOC a `https://assistent.aoc.cat/<slug>/` directament dins de
qualsevol pàgina web, **sense `<iframe>`** i amb estils aïllats.

> Versió pública: <https://assistent.aoc.cat/embed/HOWTO-EMBED.md>
> Codi font del bundle: [guiat-embed-player](https://gitlab.gitlab.videoatencion.com/videoatencion/assistents-guiats/players/guiat-embed-player)

---

## Snippet mínim

Dos elements: un `<div>` declaratiu i un `<script>`. L'script escaneja
la pàgina i substitueix qualsevol `[data-guiat-embed]` per un Web
Component aïllat.

```html
<div data-guiat-embed
     data-guiat="gestions-padro"
     data-vars='{"ens":"ajuntamentdetremp"}'></div>

<script src="https://assistent.aoc.cat/embed/embed.js" async></script>
```

Això mostrarà l'assistent **Tràmits del padró d'habitants** amb les
URLs reals de l'Ajuntament de Tremp, dins d'un marc subtil i amb la
icona de maximitzar a la cantonada superior dreta.

---

## Dues variants del bundle

| Fitxer                  | Mida (gzip) | Quan usar-lo                                              |
|-------------------------|-------------|-----------------------------------------------------------|
| `embed.js`              | **85 KB**   | **Defecte.** Només pot mostrar l'assistent guiat (arbre de preguntes/respostes/resultats). |
| `embed-with-form.js`    | 433 KB      | Si el GUIAT incrusta un **formulari intern** dins d'algun node home/question/result. Carrega SurveyJS. |

La majoria de GUIATs no fan servir formularis inline → `embed.js` és el
correcte. Si tu GUIAT ho fa, el botó del formulari mostrarà un missatge
de fallback amb un enllaç a aquesta documentació indicant que cal la
variant complete.

```html
<!-- Variant amb formularis: més pesada però completa -->
<script src="https://assistent.aoc.cat/embed/embed-with-form.js" async></script>
```

L'API (atributs `data-*`, `GuiatEmbed.init()`, esdeveniments) és
idèntica entre les dues variants.

---

## Què hi pots tocar

Tots els paràmetres es passen com a atributs `data-*` al `<div>`.
L'únic obligatori és `data-guiat`.

| Atribut         | Tipus  | Default      | Descripció                                                                                |
|-----------------|--------|--------------|-------------------------------------------------------------------------------------------|
| `data-guiat`    | string | (obligatori) | **Slug** del GUIAT publicat. El bundle fa fetch a `assistent.aoc.cat/<slug>/flow.json`. També accepta UUID o URL completa. |
| `data-lang`     | string | `ca`         | Codi ISO d'idioma inicial. L'usuari pot canviar-lo des del selector si el GUIAT té traduccions. |
| `data-logo`     | URL    | (logo AOC)   | Override de logo. URL absoluta (p. ex. `https://seu-e.cat/logotips/<codi>.PNG`). |
| `data-config`   | JSON   | `{}`         | Configuració del player (mateixa shape que `config.json`). Vegeu sota. |
| `data-vars`     | JSON   | (cap)        | **Punt d'entrada principal per personalitzar l'assistent.** Qualsevol objecte; queda a `window.GuiatEmbedVars` i el `home.script` del GUIAT el llegeix. Vegeu exemples per GUIAT més avall. |
| `data-frame`    | bool   | `true`       | Marc suau arrodonit al voltant del contingut. `false` per integració flat. |
| `data-maximize` | bool   | `true`       | Icona de maximitzar (top-right). Click obre overlay fullscreen; Esc/segon click el restaura. |

> **Disseny intencional**: l'embed no coneix cap nom de paràmetre concret
> (codi, ens, idescat…) ni manipula la URL del host. Tot el que cada
> GUIAT necessita per personalitzar-se entra via `data-vars`. El
> `home.script` del propi GUIAT decideix què mira. Beneficis: l'embed
> no creix amb cada cas particular, i cada GUIAT documenta els seus
> propis paràmetres a la seva pròpia secció (sota).

### `data-config` — opcions del player

JSON amb la mateixa shape que la `config.json` interna del web-player.
Les més útils per a un embed:

```html
<div data-guiat-embed
     data-guiat="canals-alertes-plantilla-b"
     data-config='{"dualMode":false,"defaultLanguage":"ca"}'></div>
```

- `dualMode: false` — amaga el botó "Duplicar" (obrir en finestra nova)
  que apareix per defecte a la cantonada superior dreta.
- `defaultLanguage: "ca"` — força idioma inicial; equival a `data-lang`.
- `fullScreenFormModal: true` — si el GUIAT té formulari final, el mostra
  en modal a tota la pantalla.

### `data-vars` — dades per als scripts del GUIAT

Aquest objecte queda exposat com a `window.GuiatEmbedVars` **abans**
que els scripts del GUIAT (home, options, results) s'executin. Els
scripts poden llegir-lo per personalitzar el comportament.

---

## Per assistent: gestions-padro

L'assistent **`gestions-padro`** té 9 resultats (volants/certificats,
canvi de domicili, alta, baixes, modificació de dades, etc.) i el seu
`home.script` accepta **dos modes** de configuració via `data-vars`:

### Mode A — mapa directe de tràmits (recomanat per a ajuntaments)

Si tens les URLs reals dels tràmits del teu ens, passa-les directament.
Cap fetch a la BBDD, cap dependència d'una taxonomia central.

```html
<div data-guiat-embed
     data-guiat="gestions-padro"
     data-lang="ca"
     data-vars='{"tramits":{
         "R001":"https://seu.example.cat/tramits/volant-empadronament",
         "R002":"https://seu.example.cat/tramits/volant-convivencia",
         "R003":"https://seu.example.cat/tramits/canvi-domicili",
         "R004":"https://seu.example.cat/atencio-ciutadana",
         "R006":"https://seu.example.cat/tramits/alta-padro-naixement",
         "R007":"https://seu.example.cat/tramits/modificacio-dades",
         "R008":"https://seu.example.cat/atencio-ciutadana",
         "R010":"https://seu.example.cat/tramits/alta-padro"
     }}'></div>

<script src="https://assistent.aoc.cat/embed/embed.js" async></script>
```

Identificadors de resultat per a aquest GUIAT:

| `id` | Resultat |
|------|----------|
| R001 | Volant / certificat d'empadronament |
| R002 | Volant / certificat de convivència |
| R003 | Canvi de domicili al Padró |
| R004 | Alta al Padró sense autorització → OAC |
| R005 | Baixa per canvi de domicili (informatiu, sense enllaç) |
| R006 | Alta al Padró per naixement |
| R007 | Modificació de dades personals |
| R008 | Baixa per defunció → OAC |
| R010 | Alta al Padró (genèrica) |

Els ids que no posis al mapa es queden amb l'URL genèrica del JSON.

### Mode B — lookup automàtic per ens (nom-curt seu-e o CODIINE)

Si el teu ens ja està a la BBDD pública mantinguda per l'AOC
(`assistent.aoc.cat/assets/tramits_padro.json`), pots passar només el
nom-curt o el CODIINE i el script resol totes les URLs sol:

```html
<div data-guiat-embed
     data-guiat="gestions-padro"
     data-lang="ca"
     data-vars='{"ens":"ajuntamentdetremp"}'></div>

<script src="https://assistent.aoc.cat/embed/embed.js" async></script>
```

També accepta CODIINE: `"ens":"081234"`.

### Cas standalone (sense embed)

L'assistent `gestions-padro` també funciona standalone visitant
`https://assistent.aoc.cat/gestions-padro/?ens=ajuntamentdetremp`.
El mateix `home.script` cau enrere a llegir `?ens=` quan no hi ha
`window.GuiatEmbedVars`. Mateixa lògica, dos contextos.

---

## Per assistent: canals-alertes-plantilla-b

L'assistent **`canals-alertes-plantilla-b`** és **standalone-only**: el
seu `home.script` substitueix `xxxxx` a les URLs `c.aoc.cat/...xxxxx`
pel valor de `?codi=...` de la URL. Embed-style amb `data-vars` no està
implementat en aquest assistent — useu la URL standalone:

```
https://assistent.aoc.cat/canals-alertes-plantilla-b/?codi=800180001
```

(Mateix patró per a `canals-alertes`, `canals-alertes-universitats`,
`canals-alertes-universitats-general`, `canals-alertes-plantilla-a`.)

---

## API programàtica

Si no vols el patró declaratiu, pots invocar manualment:

```html
<div id="my-guiat"></div>

<script src="https://assistent.aoc.cat/embed/embed.js"></script>
<script>
  GuiatEmbed.init({
    target:   '#my-guiat',
    guiat:    'gestions-padro',
    language: 'ca',
    config:   { dualMode: false },
    vars:     {
      tramits: {
        R001: 'https://seu.example.cat/tramits/volant-empadronament',
        R003: 'https://seu.example.cat/tramits/canvi-domicili',
      },
    },
    frame:    true,
    maximize: true,
    onComplete: function(result) {
      console.log('L\'usuari ha arribat a', result);
    },
  });

  // Per netejar més tard:
  // GuiatEmbed.destroy('#my-guiat');
</script>
```

---

## Embed flat sense marc ni maximitzar

```html
<div data-guiat-embed
     data-guiat="gestions-padro"
     data-vars='{"ens":"ajuntamentdetremp"}'
     data-frame="false"
     data-maximize="false"></div>

<script src="https://assistent.aoc.cat/embed/embed.js" async></script>
```

### Múltiples assistents a la mateixa pàgina

Cap problema — cada embed té el seu propi Shadow DOM:

```html
<h2>Tens un dubte ètic?</h2>
<div data-guiat-embed data-guiat="canals-alertes-plantilla-b"></div>

<h2>Modificació de dades del padró?</h2>
<div data-guiat-embed data-guiat="gestions-padro"></div>

<script src="https://assistent.aoc.cat/embed/embed.js" async></script>
```

---

## Què no cal saber

L'embed s'encarrega de:

- **Aïllament CSS**: el contingut viu dins un Shadow DOM, els teus
  estils no afecten l'assistent i els seus no t'afecten a tu.
- **Aïllament d'URL**: ni `BrowserRouter` ni `window.history` són
  tocats per l'embed — la URL de la teva pàgina queda intacta.
- **Múltiples instàncies**: cada `[data-guiat-embed]` és independent.
- **Idioma**: si el GUIAT té traduccions, l'usuari les pot canviar des
  del selector intern de l'assistent.
- **Responsivitat**: l'embed creix amb el seu contenidor. Pots
  controlar amplada/alçada des del CSS del teu `<div>` host:

  ```css
  .my-embed-wrapper {
    max-width: 720px;
    margin: 0 auto;
  }
  ```

---

## CORS — important per a integradors externs

El snippet recomanat fa `fetch()` cap a `https://assistent.aoc.cat/<slug>/flow.json`
des del navegador del visitant. Si el teu site no és `assistent.aoc.cat`
mateix, el navegador exigeix que la resposta porti
`Access-Control-Allow-Origin: *` (o el teu domini explícit).

**Estat actual del bucket S3 d'AOC**: aquest header NO s'envia. Per tant,
sites que NO siguin `assistent.aoc.cat` veuran "Error: Failed to fetch"
fins que infra d'AOC habiliti CORS al bucket.

**Workaround temporal** mentre no s'arregli: passar l'UUID del GUIAT (no
el slug). Llavors el bundle fa fetch contra l'API del GUIAT editor
(`guiat.k8s.videoatencion.com`), que sí té CORS `*`:

```html
<div data-guiat-embed
     data-guiat="ade49c3b-4a5f-4bf4-b02c-5e94a0e0e943"
     data-vars='{"ens":"ajuntamentdetremp"}'></div>
```

Quan CORS estigui al bucket d'AOC, podràs tornar al snippet curt.

---

## Si alguna cosa no rutlla

- Obre la consola del navegador. L'embed escriu warnings amb prefix
  `[guiat-embed]` o `[plantilla]` (scripts del GUIAT) si troba problemes.
- Verifica que `assistent.aoc.cat/<slug>/flow.json` és accessible des
  del teu navegador. Si retorna 404, el slug és incorrecte.
- Si fas servir `data-vars`, comprova que el JSON està ben format. Un
  apòstrof dins una cadena ha d'estar com a `&apos;` (HTML escape) o
  cal escapar les cometes amb una altra estratègia.
- Si el logo no canvia amb `data-codi`, verifica que
  `https://seu-e.cat/logotips/<codi>.PNG` retorna una imatge real (no
  un PNG buit de 0 bytes) — alguns codis no tenen logo i el fallback
  manté el logo AOC.

---

## Llista de slugs publicats

```
canals-alertes-plantilla-a              Plantilla A (genèrica, denúncies)
canals-alertes-plantilla-b              Plantilla B (general, queixes/dilemes)
canals-alertes                          Versió original
canals-alertes-universitats             Variant per universitats
canals-alertes-universitats-general     Variant universitats — General
canals-alertes-gencat                   Variant Generalitat
canals-alertes-sabadell                 Variant Aj. Sabadell
gestions-padro                          Tràmits del padró d'habitants
ajuts-menjador                          Confirmació de dades — Ajuts de menjador
re2026                                  Regularització Extraordinària 2026
reidentificacio-idcat                   Reidentificació idCAT
identitat-digital                       Assistent Identitat Digital
idcatmobil-plus                         idCAT Mòbil+
serveis-entitat                         Serveis que pot implantar una entitat
```

Per a la llista actualitzada: <https://assistent.aoc.cat/>.