[AEM Forms]{class="badge positive" title="Si applica ad AEM Forms)."}

Integrare l’interfaccia utente di Associa nell’applicazione

La funzionalità di comunicazione interattiva è disponibile nel programma per l’adozione anticipata. Invia un’e-mail dal tuo indirizzo di lavoro a aem-forms-ea@adobe.com per richiedere l’accesso.

Questo articolo spiega come integrare l’interfaccia utente Associa con l’applicazione, consentendo a professionisti che si rivolgono al cliente, come associati sul campo e agenti di servizio, di generare comunicazioni interattive personalizzate in tempo reale sulle istanze Publish.

Prerequisiti

Prima di integrare l’interfaccia utente Associa all’applicazione, assicurati di disporre di:

Configurazioni SAML aggiuntive per l’interfaccia utente associata

Quando configuri l’autenticazione SAML 2.0 per l’interfaccia utente Associate, devi applicare le seguenti impostazioni specifiche nei file di configurazione OSGi.

Gestore autenticazione SAML

Il Gestore autenticazione SAML è una configurazione di fabbrica OSGi che consente più configurazioni SAML per strutture di risorse diverse. In questo modo è possibile abilitare le distribuzioni AEM multisito e aggiungere le risorse Associate UI (Associate UI) alla configurazione SAML esistente.

Crea il file com.adobe.granite.auth.saml.SamlAuthenticationHandler~saml.cfg.json in ui.config/src/main/content/jcr_root/apps/<project-name>/osgiconfig/config.publish:

  {
    "path": ["/libs/fd/associate"],
    "serviceProviderEntityId": "https://publish-p{program-id}-e{env-id}.adobeaemcloud.com",
    "assertionConsumerServiceURL": "https://publish-p{program-id}-e{env-id}.adobeaemcloud.com/libs/fd/associate/saml_login"
    "idpUrl": "https://login.microsoftonline.com/{azure-tenant-id}/saml2",
    "idpCertAlias": "{your-certificate-alias}",
    "idpIdentifier": "https://sts.windows.net/{azure-tenant-id}/",
    "userIDAttribute": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    "createUser": true,
    "userIntermediatePath": "saml",
    "synchronizeAttributes": [
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname=profile/givenName",
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname=profile/familyName",
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress=profile/email"
      ],
      "addGroupMemberships": true,
      "defaultGroups": ["forms-associates"],
      "defaultRedirectUrl": "/libs/fd/associate/ui.html",
      "idpHttpRedirect": false,
      "service.ranking": 5002
  }

Autenticatore Sling

L’autenticatore Sling impone l’autenticazione per accedere alle risorse dell’interfaccia utente Associate al momento della pubblicazione.

Aggiornare il file org.apache.sling.engine.impl.auth.SlingAuthenticator~saml.cfg.json in ui.config/src/main/content/jcr_root/apps/<project-name>/osgiconfig/config.publish:

{
  "sling.auth.requirements": ["+/libs/fd/associate/ui.html"],
  "sling.auth.anonymous": false
}

Filtro Dispatcher

Aggiungi le regole seguenti per garantire il corretto funzionamento delle API di comunicazione interattiva e dell’interfaccia utente di associazione nell’istanza Publish.

Se non è già presente, aggiungere le regole seguenti al file dispatcher/src/conf.dispatcher.d/filters/filters.any:

  # Allow Interactive Communications APIs and Associate UI
  /XXXX { /type "allow" /method '(GET|OPTIONS)' /url "/adobe/communications" }
  /XXXX { /type "allow" /method '(GET|POST|OPTIONS)' /url "/adobe/communications/*" }
  /XXXX { /type "allow" /method "GET" /url "/content/dam/fd:fonts/*" }
  /XXXX { /type "allow" /method '(GET|OPTIONS)' /url "/libs/fd/associate/*" }

Richiamare l’interfaccia utente Associa nell’istanza di pubblicazione

Questa sezione illustra come avviare l’interfaccia utente Associa dalla tua applicazione. Segui questi passaggi per iniziare rapidamente: inizia con una pagina HTML di esempio pronta per l’uso, quindi configurala per l’ambiente.

Passaggio 1: inizia con la pagina HTML di esempio

Per verificare e comprendere rapidamente come funziona l’integrazione dell’interfaccia utente Associa, utilizza la seguente pagina di esempio di HTML. Copia il codice in un file HTML e aprilo nel browser.

L’esempio di HTML fornisce una semplice interfaccia modulo in cui puoi inserire i dettagli della comunicazione interattiva e avviare l’interfaccia utente Associa con un solo clic.

<!DOCTYPE html>
<html>
<head>
  <title>Associate UI Integration</title>
  <style>
    body {
      font-family: sans-serif;
      max-width: 600px;
      margin: 50px auto;
      padding: 20px;
    }
    .form-group {
      margin: 20px 0;
    }
    label {
      display: block;
      margin-bottom: 5px;
      font-weight: bold;
    }
    input, textarea {
      width: 100%;
      padding: 8px;
      border: 1px solid #ccc;
      border-radius: 4px;
      box-sizing: border-box;
    }
    textarea {
      height: 80px;
      font-family: monospace;
    }
    button {
      padding: 10px 20px;
      margin: 5px;
      cursor: pointer;
      border-radius: 4px;
    }
    .btn-primary {
      background: #007bff;
      color: white;
      border: none;
    }
    .btn-primary:hover {
      background: #0056b3;
    }
    .error {
      color: red;
      font-size: 12px;
      display: none;
    }
  </style>
</head>
<body>
  <h1>Launch Associate UI</h1>

  <form id="form">
    <div class="form-group">
      <label>IC ID *</label>
      <input type="text" id="icId" placeholder="Enter Interactive Communication ID" required>
    </div>

    <div class="form-group">
      <label>Prefill Service</label>
      <input type="text" id="serviceName" placeholder="e.g., CustomerDataService">
    </div>

    <div class="form-group">
      <label>Service Parameters (JSON)</label>
      <textarea id="serviceParams" placeholder='{"customerId": "12345"}'>{}</textarea>
      <span id="paramsError" class="error">Invalid JSON format</span>
    </div>

    <div class="form-group">
      <label>Options (JSON)</label>
      <textarea id="options" placeholder='{"mode": "edit", "locale": "en_US"}'>{}</textarea>
      <span id="optionsError" class="error">Invalid JSON format</span>
    </div>

    <button type="button" onclick="reset()">Reset</button>
    <button type="button" class="btn-primary" onclick="launch()">Launch Associate UI</button>
  </form>

  <script>
    // Replace with your AEM Publish instance URL
    const AEM_URL = 'https://publish-p{program-id}-e{env-id}.adobeaemcloud.com/libs/fd/associate/ui.html';

    function validateJSON(str, errorId) {
      const err = document.getElementById(errorId);
      try {
        const obj = JSON.parse(str || '{}');
        err.style.display = 'none';
        return obj;
      } catch (e) {
        err.style.display = 'block';
        return null;
      }
    }

    function launch() {
      const icId = document.getElementById('icId').value.trim();
      if (!icId) {
        alert('IC ID is required');
        return;
      }

      const params = validateJSON(document.getElementById('serviceParams').value, 'paramsError');
      const opts = validateJSON(document.getElementById('options').value, 'optionsError');

      if (!params || !opts) {
        alert('Please fix JSON errors before launching');
        return;
      }

      const data = {
        id: icId,
        prefill: {
          serviceName: document.getElementById('serviceName').value.trim(),
          serviceParams: params
        },
        options: opts
      };

      const win = window.open(AEM_URL, '_blank');
      if (!win) {
        alert('Pop-up blocked. Please enable pop-ups for this site.');
        return;
      }

      const handler = (e) => {
        if (e.data && e.data.type === 'READY' && e.data.source === 'APP') {
          win.postMessage({ type: 'INIT', source: 'PORTAL', data }, '*');
          window.removeEventListener('message', handler);
        }
      };

      window.addEventListener('message', handler);

      // Fallback timeout in case READY message is missed
      setTimeout(() => {
        if (win && !win.closed) {
          win.postMessage({ type: 'INIT', source: 'PORTAL', data }, '*');
          window.removeEventListener('message', handler);
        }
      }, 1000);
    }

    function reset() {
      document.getElementById('form').reset();
      document.getElementById('serviceParams').value = '{}';
      document.getElementById('options').value = '{}';
      document.getElementById('paramsError').style.display = 'none';
      document.getElementById('optionsError').style.display = 'none';
    }
  </script>
</body>
</html>

Passaggio 2: configurare l’URL dell’istanza di pubblicazione

Prima di poter avviare l’interfaccia utente Associa, devi puntare l’esempio all’istanza Publish di AEM Forms Cloud Service.

Nell’esempio di HTML precedente, individuare la riga seguente nella sezione <script>:

const AEM_URL = 'https://publish-p{program-id}-e{env-id}.adobeaemcloud.com/libs/fd/associate/ui.html';

Sostituisci i valori dei segnaposto con i dettagli dell’ambiente effettivo:

Ad esempio, se l’ID del programma è 12345 e l’ID dell’ambiente è 67890, l’URL diventa:

const AEM_URL = 'https://publish-p12345`-e67890.adobeaemcloud.com/libs/fd/associate/ui.html';

Passaggio 3: comprendere la funzione di integrazione di JavaScript

Il HTML di esempio utilizza la seguente funzione JavaScript per avviare l’interfaccia utente Associate. Questa funzione convalida l’ID IC, crea il payload dei dati, apre l’interfaccia utente Associate in una nuova finestra del browser e invia i dati utilizzando l’API postMessage del browser.

function launchAssociateUI(icId, prefillService, prefillParams, options) {
  if (!icId) {
    console.error('IC ID required');
    return;
  }

  const data = {
    id: icId,
    prefill: {
      serviceName: prefillService || '',
      serviceParams: prefillParams || {}
    },
    options: options || {}
  };

  const AEM_URL = 'https://your-aem.adobeaemcloud.com/libs/fd/associate/ui.html';
  const win = window.open(AEM_URL, '_blank');

  if (!win) {
    alert('Please enable pop-ups for this site');
    return;
  }

  const readyHandler = (event) => {
    if (event.data && event.data.type === 'READY' && event.data.source === 'APP') {
      win.postMessage({ type: 'INIT', source: 'PORTAL', data: data }, '*');
      window.removeEventListener('message', readyHandler);
    }
  };

  window.addEventListener('message', readyHandler);

  // Fallback timeout in case READY message is missed
  setTimeout(() => {
    if (win && !win.closed) {
      win.postMessage({ type: 'INIT', source: 'PORTAL', data: data }, '*');
      window.removeEventListener('message', readyHandler);
    }
  }, 1000);
}

La funzione accetta quattro parametri: l’ID IC (obbligatorio), il nome del servizio di precompilazione, i parametri del servizio di precompilazione e le opzioni aggiuntive. Questi parametri sono strutturati nel payload di dati come descritto di seguito.

Passaggio 4: comprendere la struttura del payload dei dati

Formato payload:

const data = {
  id: "your-ic-id",              // Required: Interactive Communication ID
  prefill: {                      // Optional: Data to prefill the IC
    serviceName: "YourService",
    serviceParams: { key: "value" }
  },
  options: {}                     // Optional: Additional configuration options
};

Componenti payload:

Esempi di payload dei dati

Payload minimo (solo ID IC)

Utilizza questa opzione quando non sono necessari dati di precompilazione:

{
  "id": "12345",
  "prefill": {
    "serviceName": "",
    "serviceParams": {}
  },
  "options": {}
}

Con Dati Precompilati

Utilizza questa opzione per popolare dinamicamente l’IC con i dati del cliente:

{
  "id": "12345",
  "prefill": {
    "serviceName": "IC_FDM",
    "serviceParams": {
      "customerId": "101",
      "accountNumber": "ACC-98765"
    }
  },
  "options": {}
}

Con Opzioni Di Rendering Di PDF

Utilizzate questa opzione per specificare ulteriori opzioni di rendering:

{
  "id": "12345",
  "prefill": {
    "serviceName": "IC_FDM",
    "serviceParams": {
      "customerId": "101",
      "accountNumber": "ACC-98765"
    }
  },
  "options": {
      "locale": "en_US",
      "includeAttachments": "true",
      "webOptimized": "false",
      "embedFonts": "false",
      "makeAccessible": "false"
  }
}

Passaggio 5: immettere l’ID IC e avviare l’interfaccia utente Associate

Ora puoi avviare l’interfaccia utente Associa utilizzando la pagina di esempio di HTML:

Immetti i dati e l’interfaccia utente Associa verrà visualizzata come mostrato di seguito:

Risoluzione dei problemi

Popup bloccato

Problema: la finestra Associa interfaccia utente non si apre.

Soluzione:

Dati non caricati

Problema: la comunicazione interattiva si apre ma i dati non si popolano.

Soluzione:

Errore di autenticazione

Problema: l’utente riceve un errore di autenticazione all’apertura dell’interfaccia utente Associate.

Soluzione:

Errori CORS

Problema: errori di condivisione risorse tra le origini nella console.

Soluzione:

Consulta anche