[AEM Forms]{class="badge positive" title="Gilt für AEM Forms)."}

Integrieren der Associate-Benutzeroberfläche in Ihr Programm

Die Funktion für interaktive Kommunikation ist im Rahmen des Early-Adopter-Programms verfügbar. Senden Sie eine E-Mail von Ihrer Geschäftsadresse an aem-forms-ea@adobe.com, um Zugriff anzufordern.

In diesem Artikel wird erläutert, wie Sie die Benutzeroberfläche „Verknüpfen“ in Ihr Programm integrieren und es kundenorientierten Fachleuten wie Außendienstmitarbeitern und Service-Agenten ermöglichen, in Echtzeit personalisierte interaktive Kommunikation in Veröffentlichungsinstanzen zu generieren.

Voraussetzungen

Bevor Sie die Benutzeroberfläche „Verknüpfen“ mit Ihrer Anwendung integrieren, stellen Sie sicher, dass Sie über Folgendes verfügen:

Zusätzliche SAML-Konfigurationen für die Associate-Benutzeroberfläche

Beim Konfigurieren der SAML 2.0-Authentifizierung für die Associate-Benutzeroberfläche müssen Sie die folgenden spezifischen Einstellungen in Ihren OSGi-Konfigurationsdateien anwenden.

SAML-Authentifizierungshandler

Der SAML-Authentifizierungs-Handler ist eine OSGi-Werkskonfiguration, die mehrere SAML-Konfigurationen für verschiedene Ressourcenbäume zulässt. Dies ermöglicht AEM-Bereitstellungen an mehreren Standorten und das Hinzufügen von zugehörigen Benutzeroberflächenressourcen zu Ihrem bestehenden SAML-Setup.

Erstellen Sie die Datei 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
  }

Sling Authenticator

Der Sling Authenticator erzwingt die Authentifizierung für den Zugriff auf Ressourcen der zugehörigen Benutzeroberfläche in der Veröffentlichungsinstanz.

Aktualisieren Sie die Datei 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
}

Dispatcher-Filter

Fügen Sie die folgenden Regeln hinzu, um sicherzustellen, dass APIs für interaktive Kommunikation und die Benutzeroberfläche „Verknüpfen“ in der Veröffentlichungsinstanz korrekt funktionieren.

Falls noch nicht vorhanden, fügen Sie Ihrer dispatcher/src/conf.dispatcher.d/filters/filters.any-Datei die folgenden Regeln hinzu:

  # 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/*" }

Aufrufen der Associate-Benutzeroberfläche in der Veröffentlichungsinstanz

Dieser Abschnitt führt Sie durch den Start der Benutzeroberfläche „Associate“ von Ihrem eigenen Programm aus. Führen Sie diese Schritte aus, um schnell zu beginnen, beginnend mit einer einsatzbereiten Beispiel-HTML-Seite, und konfigurieren Sie sie dann für Ihre Umgebung.

Schritt 1: Mit der HTML-Beispielseite beginnen

Um schnell zu testen und zu verstehen, wie die Integration der Associate-Benutzeroberfläche funktioniert, verwenden Sie die folgende HTML-Beispielseite. Kopieren Sie diesen Code in eine HTML-Datei und öffnen Sie sie in Ihrem Browser.

Das HTML-Beispiel bietet eine einfache Formularoberfläche, in der Sie Details zur interaktiven Kommunikation eingeben und die Benutzeroberfläche „Zuordnen“ mit einem Klick starten können.

<!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>

Schritt 2: Konfigurieren der URL der Veröffentlichungsinstanz

Bevor Sie die Benutzeroberfläche „Associate“ starten können, müssen Sie das Beispiel auf Ihre AEM Forms Cloud Service-Veröffentlichungsinstanz verweisen.

Suchen Sie im obigen HTML-Beispiel die folgende Zeile im Abschnitt <script> :

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

Ersetzen Sie die Platzhalterwerte durch Ihre tatsächlichen Umgebungsdetails:

Wenn beispielsweise Ihre Programm-ID 12345 und die Umgebungs-ID 67890 ist, wird die URL zu:

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

Schritt 3: JavaScript-Integrationsfunktion verstehen

Im Beispiel verwendet HTML die folgende JavaScript-Funktion, um die Benutzeroberfläche „Associate“ zu starten. Diese Funktion validiert die IC-ID, erstellt die Daten-Payload, öffnet die Benutzeroberfläche „Associate“ in einem neuen Browser-Fenster und sendet die Daten über die postMessage-API des Browsers.

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

Die Funktion akzeptiert vier Parameter: die ID (erforderlich), den Namen des Vorbefüllungs-Services, die Parameter des Vorbefüllungs-Services und zusätzliche Optionen. Diese Parameter werden wie unten beschrieben in die Daten-Payload strukturiert.

Schritt 4: Grundlegendes zur Struktur der Daten-Payload

Payload-Format:

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

Payload-Komponenten:

Beispiele für Daten-Payloads

Minimale Payload (nur IC-ID)

Verwenden Sie diese Option, wenn keine Daten zum Vorbefüllen erforderlich sind:

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

mit Vorbefüllungsdaten

Verwenden Sie diese Option, um die ID dynamisch mit Kundendaten zu füllen:

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

mit PDF-Rendering-Optionen

Hier können Sie zusätzliche Rendering-Optionen angeben:

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

Schritt 5: IC-ID eingeben und Benutzeroberfläche des zugeordneten Benutzers starten

Jetzt können Sie die Benutzeroberfläche von Associate über die HTML-Beispielseite starten:

Geben Sie die Daten ein, und die Benutzeroberfläche „Verknüpfen“ wird wie unten dargestellt angezeigt:

Fehlerbehebung

Popup blockiert

Problem: Das Fenster „Benutzeroberfläche zuordnen“ wird nicht geöffnet.

Lösung:

Daten werden nicht geladen

Problem: Die interaktive Kommunikation wird geöffnet, aber es werden keine Daten angezeigt.

Lösung:

Authentifizierungsfehler

Problem: Der Benutzer erhält einen Authentifizierungsfehler, wenn die Benutzeroberfläche von Associate geöffnet wird.

Lösung:

CORS-Fehler

Problem: Fehler bei der herkunftsübergreifenden Ressourcennutzung in der Konsole.

Lösung:

Siehe auch