Personalizzare un widget generato customize-generated-widget

Dopo la generazione corretta, la piattaforma fornisce un widget EDS collegato all’azione in LLM Apps. Il widget esegue il rendering dei dati rappresentativi per l’anteprima e legge i risultati del gestore quando si è connessi a una piattaforma LLM supportata. Rivedi la progettazione e il comportamento generati prima di personalizzare il widget.

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

In questa guida: scopri come trovare il widget generato e adattarlo ai dati dell’azione e alla progettazione del tuo marchio. Quindi visualizza l’anteprima locale delle modifiche e testale nell’app implementata.

Trova il widget generato

Aprire l’archivio EDS connesso durante la configurazione infrastruttura. Se utilizzi l’infrastruttura gestita di Adobe, richiedi l’accesso al codice prima di continuare. Ogni widget generato è un blocco EDS:

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

Lo slug utilizza i trattini: un’azione con identificatore di codice search_products utilizza un blocco come blocks/search-products/. La pagina widget generata è in genere /eds-widgets/search-products-demo. Utilizzare l’URL widget effettivo nei metadati azione.

La piattaforma configura anche gli URL del widget e i file di supporto SDK. Non è necessario creare un secondo progetto EDS o immettere nuovamente gli URL del widget 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. I punti di ingresso nell’archivio EDS generato sono:

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.
}

L’incorporamento recupera il contenuto .plain.html della pagina widget e ne importa i blocchi. Non si importa il SDK nel blocco. L’incorporamento fornisce automaticamente bridge; il normale caricamento della pagina EDS non lo fornisce. Il ponte 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 ${records.length} products.` }],
  structuredContent: { arguments: { query: 'coffee' }, records }
};

// EDS block
const PREVIEW_RESULT = {
  records: [{ id: 'P-100', name: 'Frescopa House Blend' }]
};

export default async function decorate(block, bridge) {
  const live = bridge?.isConnected && bridge.hostContext?.preview !== true;
  const result = live ? await bridge.toolResult : null;
  const data = live ? result?.structuredContent : PREVIEW_RESULT;
  const records = Array.isArray(data?.records) ? data.records : [];
  // Render records or an error state when result?.isError is true.
}

In questo esempio, PREVIEW_RESULT è l’oggetto di dati di esempio locale del blocco. I widget attualmente generati utilizzano structuredContent.arguments e structuredContent.records; verificare la forma esatta nei file generati. Non sostituire mai un risultato live vuoto con record di anteprima.

bridge.toolResult viene risolto solo con il primo risultato. Utilizzare bridge.onToolResult(callback) se un widget rimane montato e deve gestire i risultati successivi.

Quando modifichi structuredContent, aggiorna il gestore e il widget insieme. Non presumere che i dati strutturati siano nascosti dal modello; fanno parte del risultato dell’azione dell’host. 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.disabled = !bridge?.isConnected;
  const status = document.createElement('p');
  status.setAttribute('role', 'status');
  button.addEventListener('click', async () => {
    if (bridge?.isConnected && typeof product.id === 'string') {
      try {
        await bridge.sendMessage(`Show me details for product ${product.id}`);
      } catch {
        status.textContent = 'Unable to send the request. Try again.';
      }
    }
  });

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

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

Utilizzare il bridge host

L’incorporamento passa un ponte a decorate(block, bridge). Proteggi le chiamate interattive con bridge?.isConnected in modo che il blocco venga riprodotto anche durante l’anteprima EDS diretta. Un oggetto bridge può esistere in modalità standalone senza essere connesso; l’attesa di toolResult in modalità standalone non viene mai risolta. L’anteprima delle app LLM imposta anche bridge.hostContext.preview per consentire al blocco di scegliere dati di esempio.

Applicare gli stili host

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

Il metodo applica le variabili CSS host e gli stili di carattere disponibili. L’applicazione degli stili host è facoltativa: i widget generati possono utilizzare i propri token di progettazione. L’incorporamento mantiene .light e .dark classi nel relativo corpo shadow. Utilizza bridge.hostContext.theme e bridge.onContextChange(callback) quando il blocco deve anche reagire alle modifiche del tema.

Inviare un messaggio di follow-up

if (bridge?.isConnected) {
  await bridge.sendMessage('Show me similar products.');
}

Utilizza sendMessage per continuare la conversazione dopo un’interazione.

Richiama direttamente un’azione

if (bridge?.isConnected) {
  const result = await bridge.callTool('search_products', { query: 'coffee' });
  // Re-render this widget from result.structuredContent, or show result.isError.
}

Utilizza callTool per un’interazione esplicita che richiede un risultato dell’azione. Passa l’identificatore di codice dell’azione di destinazione effettiva, non il nome della cartella di blocco o il nome visualizzato; search_products è un esempio. L’host deve supportare le chiamate di azione e l’azione di destinazione deve consentire la visibilità dell’app. La chiamata di un’azione non esegue automaticamente il rendering del widget corrente. Passa solo i valori convalidati e gestisci le chiamate rifiutate senza esporre i dettagli interni.

Se è necessario modificare la visibilità dell’azione di destinazione, modificare solo tale azione in Dettagli azione, salvare la modifica e ridistribuire nell’ambiente in fase di test.

Mantieni sincronizzate le dimensioni del widget

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

Per consentire all’host di rispondere alle modifiche al contenuto, chiamare autoResize dopo il rendering iniziale. Il metodo restituisce una funzione di pulizia che interrompe l’osservazione quando il widget viene rimosso.

Visualizzare l’anteprima delle modifiche

I blocchi generati includono dati di esempio per l’anteprima diretta quando il bridge è mancante, disconnesso o contrassegnato come anteprima. Mantenere il fallback dei dati di esempio separato dagli stati live vuoti e di errore.

Per visualizzare localmente l’anteprima del progetto EDS:

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

Aprire il percorso dall’URL del widget dell’azione sul server locale, ad esempio http://localhost:3000/eds-widgets/search-products-demo, anziché solo dalla directory principale del sito. Verifica:

L’anteprima EDS diretta non verifica i dati dell’handshake host o dell’azione live. Pubblica le modifiche EDS e verifica con structuredContent live nella piattaforma LLM supportata.

Pubblicare la personalizzazione

La pubblicazione EDS è distinta dalla distribuzione nell’app. Se Stage e Production utilizzano gli stessi URL EDS, le modifiche dei widget in corrispondenza di tali URL influiscono su entrambi gli ambienti; la distribuzione in Stage non crea una copia di widget isolata.

Altre impostazioni EDS

Se le azioni sono state create personalmente o si desidera integrare un sito EDS esistente compatibile, vedere Aggiungere un progetto EDS personalizzato.