Personalizzare un widget generato customize-generated-widget

La piattaforma crea un widget EDS per ogni azione generata. Il widget riceve già il risultato dell’azione, esegue il rendering dei dati di esempio, applica lo stile host ed è collegato all’azione in LLM Apps.

Inizia testando il widget generato. Quindi personalizzane il contratto dati, l’interazione e la progettazione visiva.

Percorso: Trovare il blocco generato → allineare il relativo contratto dati → personalizzarlo in modo sicuro → l’anteprima in locale → distribuire e testare.

Trova il widget generato

Apri l’archivio EDS selezionato al momento della creazione dell’app. Ogni widget generato è un blocco EDS:

blocks/
└── <action-name>/
    ├── <action-name>.js
    └── <action-name>.css

La piattaforma configura anche gli URL del widget e i file di supporto SDK. Non è necessario creare un secondo progetto EDS o immettere nuovamente tali valori per personalizzare un widget generato.

Collegamento del widget da parte del SDK applicazioni LLM

Il pacchetto @adobe/llmapps-sdk connette il widget EDS all’host LLM. L’archivio EDS generato include:

scripts/
├── aem-embed.js
└── llmapps-sdk.js

aem-embed.js stabilisce la connessione host, carica la pagina EDS e chiama il blocco:

export default async function decorate(block, bridge) {
  // Customize the widget here.
}

Non si importa il SDK nel blocco. bridge connesso viene fornito automaticamente. Consente al widget di:

Questa guida descrive i metodi di bridge più comuni. Vedere il pacchetto @adobe/llmapps-sdk per l’API completa.

Comprendere il contratto dati

Il gestore azioni restituisce structuredContent e il blocco lo legge da bridge.toolResult.

// Handler result
return {
  content: [{ type: 'text', text: `Found ${products.length} products.` }],
  structuredContent: { products, total: products.length }
};

// EDS block
export default async function decorate(block, bridge) {
  const result = bridge ? await bridge.toolResult : null;
  const products = result?.structuredContent?.products ?? [];
  // Render products.
}

Quando modifichi structuredContent, aggiorna il gestore e il widget insieme. Vedi Personalizzare un gestore generato per il contratto di reso completo.

Rendering sicuro dei dati esterni

Considera l’output del gestore come dati non attendibili. Preferisci API DOM come textContent invece di inserire valori di risposta in innerHTML.

function createProductCard(product, bridge) {
  const card = document.createElement('article');
  card.className = 'product-card';

  const title = document.createElement('h3');
  title.textContent = String(product.name ?? 'Product');

  const button = document.createElement('button');
  button.type = 'button';
  button.textContent = 'Tell me more';
  button.addEventListener('click', () => {
    if (bridge && product.id) {
      bridge.sendMessage(`Show me details for product ${String(product.id)}`);
    }
  });

  card.append(title, button);
  return card;
}

Convalidare gli URL prima di assegnarli a href o src e consentire solo i protocolli richiesti dall’esperienza.

Utilizzare il bridge host

EDS passa un bridge connesso a decorate(block, bridge). Controlla le chiamate del ponte in modo che il blocco venga riprodotto anche durante l’anteprima EDS diretta.

Applicare gli stili host

if (bridge) {
  bridge.applyHostStyles();
}

Questo applica la tipografia host e le variabili tema. Il CSS del widget deve supportare i temi host sia chiaro che scuro.

Inviare un messaggio di follow-up

await bridge.sendMessage('Show me similar products.');

Utilizza sendMessage quando un’interazione deve continuare la conversazione.

Richiama un’altra azione

const result = await bridge.callTool('get-product-details', {
  id: product.id
});

Utilizza callTool per un’interazione esplicita che richiede un altro risultato dell’azione. Passa solo i valori convalidati e gestisci gli errori senza esporre i dettagli interni.

Mantieni sincronizzate le dimensioni del widget

if (bridge) {
  bridge.autoResize(block);
}

Chiamare autoResize dopo il rendering iniziale in modo che l’host possa rispondere alle modifiche al contenuto.

Visualizzare l’anteprima delle modifiche

I blocchi generati devono includere dati di esempio per l’anteprima diretta quando bridge non è disponibile.

Per visualizzare localmente l’anteprima del progetto EDS:

npm install -g @adobe/aem-cli
aem up

Apri la pagina del widget generato in http://localhost:3000. Verifica:

Quindi distribuisci l’app per la gestione temporanea e il test con structuredContent live nella piattaforma LLM.

Pubblicare la personalizzazione

Altre impostazioni EDS

Se non hai creato l’app automaticamente o non desideri integrare un sito EDS esistente, consulta Acquista un tuo progetto EDS.