[AEM Forms]{class="badge positive" title="Se aplica a AEM Forms."}

Integración de la interfaz de usuario asociada en la aplicación

Este artículo explica cómo integrar la interfaz de usuario de Associate con la aplicación, lo que permite a los profesionales de cara al cliente, como los asociados de campo y los representantes de servicio, generar comunicaciones interactivas personalizadas en tiempo real en instancias de publicación.

Requisitos previos

Antes de integrar la interfaz de usuario de Associate con su aplicación, asegúrese de lo siguiente:

Configuraciones adicionales de SAML para la IU asociada

Al configurar la autenticación SAML 2.0 para la interfaz de usuario asociada, debe aplicar la siguiente configuración específica en los archivos de configuración OSGi.

Controlador de autenticación SAML

El controlador de autenticación SAML es una configuración de fábrica de OSGi que permite varias configuraciones SAML para diferentes árboles de recursos. Esto habilita las implementaciones de AEM en varios sitios y le permite agregar recursos de la IU asociada a la configuración de SAML existente.

Crear el archivo com.adobe.granite.auth.saml.SamlAuthenticationHandler~saml.cfg.json en 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
  }

Sling Authenticator

El autenticador de Sling aplica la autenticación para acceder a los recursos de la IU asociada en la publicación.

Actualizar el archivo org.apache.sling.engine.impl.auth.SlingAuthenticator~saml.cfg.json en 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 de Dispatcher

Añada las siguientes reglas para asegurarse de que las API de comunicaciones interactivas y la interfaz de usuario asociada funcionan correctamente en la instancia de publicación.

Si aún no lo está, agregue las siguientes reglas al archivo 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/*" }

Invocando la IU asociada en la instancia de publicación

Esta sección le guiará a través del inicio de la interfaz de usuario de Associate desde su propia aplicación. Siga estos pasos para empezar rápidamente: empiece con una página de muestra de HTML lista para usar y, a continuación, configúrela para su entorno.

Paso 1: Comience con la Página de HTML de muestra

Para probar y comprender rápidamente cómo funciona la integración de la interfaz de usuario de Associate, utilice la siguiente página de muestra de HTML. Copie este código en un archivo de HTML y ábralo en su explorador.

El ejemplo de HTML proporciona una interfaz de formulario sencilla en la que puede introducir los detalles de la comunicación interactiva e iniciar la interfaz de usuario de Associate 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>

Paso 2: Configuración de la URL de instancia de publicación

Para poder iniciar la interfaz de usuario de Associate, debe apuntar el ejemplo a la instancia de publicación de AEM Forms Cloud Service.

En el ejemplo de HTML anterior, busque la línea siguiente en la sección <script>:

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

Reemplace los valores de marcador de posición con los detalles del entorno real:

Por ejemplo, si el identificador de programa es 12345 y el identificador de entorno es 67890, la dirección URL pasa a ser:

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

Paso 3: Comprender la función de integración de JavaScript

El HTML de ejemplo utiliza la siguiente función de JavaScript para iniciar la interfaz de usuario de Associate. Esta función valida el ID de CI, construye la carga útil de datos, abre la interfaz de usuario asociada en una nueva ventana del explorador y envía los datos mediante la API postMessage del explorador.

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 función acepta cuatro parámetros: el ID de CI (obligatorio), el nombre del servicio de relleno previo, los parámetros del servicio de relleno previo y las opciones adicionales. Estos parámetros se estructuran en la carga útil de datos como se describe a continuación.

Paso 4: Comprender la estructura de carga útil de datos

Formato de carga útil:

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

Componentes de carga útil:

Ejemplos de carga útil de datos

Carga útil mínima (solo ID de CI)

Utilice esta opción cuando no se requieran datos de relleno previo:

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

Con Datos De Relleno Previo

Use esto para rellenar dinámicamente la CI con datos del cliente:

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

Con Opciones De Procesamiento De PDF

Utilice esto para especificar opciones de renderización adicionales:

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

Paso 5: Introduzca el ID de CI e inicie la interfaz de usuario asociada

Ahora está listo para iniciar la interfaz de usuario de Associate mediante la página de HTML de ejemplo:

Introduzca los datos y la interfaz de usuario asociada aparecerá como se muestra a continuación:

Resolución de problemas

Ventana emergente bloqueada

Problema: La ventana Asociar interfaz de usuario no se abre.

Solución:

Datos que no se cargan

Problema: la comunicación interactiva se abre pero los datos no se rellenan.

Solución:

Error de autenticación

Problema: el usuario recibe un error de autenticación cuando se abre la interfaz de usuario asociada.

Solución:

Errores de CORS

Problema: Errores de uso compartido de recursos de origen cruzado en la consola.

Solución:

Ver también