Konfigurieren von Benutzereingaben über Kundendatenfelder

Beim Herstellen einer Verbindung zu Ihrem Ziel in der Experience Platform-Benutzeroberfläche müssen Ihre Benutzerinnen und Benutzer möglicherweise bestimmte Konfigurationsdetails angeben oder zwischen bestimmten Optionen auswählen, die Sie ihnen zur Verfügung stellen. In Destination SDK werden diese Optionen als Kundendatenfelder bezeichnet.

Informationen dazu, wo diese Komponente in eine mit Destination SDK erstellte Integration passt, finden Sie im Diagramm in der Dokumentation zu Konfigurationsoptionen oder auf den folgenden Übersichtsseiten zur Zielkonfiguration:

Anwendungsbeispiele für Kundendatenfelder use-cases

Verwenden Sie Kundendatenfelder für eine Vielzahl von Anwendungsfällen, in denen Benutzerinnen und Benutzer Daten in die Experience Platform-Benutzeroberfläche eingeben müssen. Verwenden Sie beispielsweise Kundendatenfelder, wenn Benutzerinnen und Benutzer Folgendes bereitstellen müssen:

Sie können Kundendatenfelder über den Endpunkt /authoring/destinations konfigurieren. Detaillierte Beispiele für API-Aufrufe, in denen Sie die auf dieser Seite angezeigten Komponenten konfigurieren können, finden Sie auf den folgenden API-Referenzseiten.

In diesem Artikel werden alle unterstützten Konfigurationstypen von Kundendatenfeldern beschrieben, die Sie für Ihr Ziel verwenden können, und es wird gezeigt, was Kundinnen und Kunden in der Experience Platform-Benutzeroberfläche sehen werden.

Unterstützte Integrationstypen supported-integration-types

Die nachstehende Tabelle beschreibt ausführlich, welche Integrationstypen die auf dieser Seite beschriebenen Funktionen unterstützen.

Unterstützte Parameter supported-parameters

Bei der Erstellung Ihrer eigenen Kundendatenfelder können Sie die in der folgenden Tabelle beschriebenen Parameter verwenden, um ihr Verhalten zu konfigurieren.

Im folgenden Beispiel werden im Bereich customerDataFields zwei Felder definiert, die Benutzerinnen und Benutzer beim Herstellen einer Verbindung zum Ziel in die Platform-Benutzeroberfläche eingeben müssen:

"customerDataFields":[
   {
      "name":"accountID",
      "title":"User account ID",
      "description":"User account ID for the destination platform.",
      "type":"string",
      "isRequired":true
   },
   {
      "name":"region",
      "title":"API endpoint region",
      "description":"The API endpoint region that the user should connect to.",
      "type":"string",
      "isRequired":true,
      "enum":[
         "EU"
         "US",
      ],
      "readOnly":false,
      "hidden":false
   }
]

Das daraus resultierende Benutzeroberflächenerlebnis wird in der Abbildung unten dargestellt.

Namen und Beschreibungen von Zielverbindungen names-description

Beim Erstellen eines neuen Ziels fügt Destination SDK in der Platform-Benutzeroberfläche automatisch Felder für den Namen und die Beschreibung zum Bildschirm für die Zielverbindung hinzu. Wie Sie im obigen Beispiel sehen können, werden die Felder Name und Beschreibung in der Benutzeroberfläche gerendert, ohne in die Konfiguration der Kundendatenfelder einbezogen zu werden.

Reihenfolge der Kundendatenfelder ordering

Die Kundendatenfelder werden in der Plattform-Benutzeroberfläche in der Reihenfolge angezeigt, in der Sie sie in der Zielkonfiguration hinzufügen.

Beispielsweise wird die folgende Konfiguration entsprechend in der Benutzeroberfläche angezeigt, wobei die Optionen in der Reihenfolge Name, Beschreibung, Behältername, Ordnerpfad, Dateityp, Komprimierungsformat angezeigt werden.

"customerDataFields":[
{
   "name":"bucketName",
   "title":"Bucket name",
   "description":"Amazon S3 bucket name",
   "type":"string",
   "isRequired":true,
   "pattern":"(?=^.{3,63}$)(?!^(\\d+\\.)+\\d+$)(^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$)",
   "readOnly":false,
   "hidden":false
},
{
   "name":"path",
   "title":"Folder path",
   "description":"Enter the path to your S3 bucket folder",
   "type":"string",
   "isRequired":true,
   "pattern":"^[0-9a-zA-Z\\/\\!\\-_\\.\\*\\''\\(\\)]*((\\%SEGMENT_(NAME|ID)\\%)?\\/?)+$",
   "readOnly":false,
   "hidden":false
},
{
   "name":"fileType",
   "title":"File Type",
   "description":"Select the exported file type.",
   "type":"string",
   "isRequired":true,
   "readOnly":false,
   "hidden":false,
   "enum":[
      "csv",
      "json",
      "parquet"
   ],
   "default":"csv"
},
{
   "name":"compression",
   "title":"Compression format",
   "description":"Select the desired file compression format.",
   "type":"string",
   "isRequired":true,
   "readOnly":false,
   "enum":[
      "SNAPPY",
      "GZIP",
      "DEFLATE",
      "NONE"
   ]
}
]

Gruppieren von Kundendatenfeldern grouping

Sie können mehrere Kundendatenfelder in einem Abschnitt gruppieren. Beim Einrichten der Verbindung zum Ziel in der Benutzeroberfläche können Benutzerinnen und Benutzer eine visuelle Gruppierung ähnlicher Felder sehen und davon profitieren.

Verwenden Sie dazu "type": "object", um die Gruppe zu erstellen, und fassen Sie die gewünschten Kundendatenfelder in einem properties-Objekt zusammen, wie in der Abbildung unten gezeigt, wobei die Gruppierung CSV-Optionen hervorgehoben ist.

"customerDataFields":[
   {
      "name":"csvOptions",
      "title":"CSV Options",
      "description":"Select your CSV options",
      "type":"object",
      "properties":[
         {
            "name":"delimiter",
            "title":"Delimiter",
            "description":"Select your Delimiter",
            "type":"string",
            "isRequired":false,
            "default":",",
            "namedEnum":[
               {
                  "name":"Comma (,)",
                  "value":","
               },
               {
                  "name":"Tab (\\t)",
                  "value":"\t"
               }
            ],
            "readOnly":false,
            "hidden":false
         }
      ]
   }
]

Erstellen von Dropdown-Selektoren für Kundendatenfelder dropdown-selectors

In Situationen, in denen Sie Benutzerinnen und Benutzern die Auswahl zwischen verschiedenen Optionen ermöglichen möchten, z. B. welche Zeichen zum Trennen der Felder in CSV-Dateien verwendet werden sollen, können Sie Dropdown-Felder zur Benutzeroberfläche hinzufügen.

Verwenden Sie dazu das namedEnum-Objekt wie unten gezeigt und konfigurieren Sie einen default-Wert für die Optionen, die Benutzerinnen und Benutzer auswählen können.

"customerDataFields":[
   {
      "name":"csvOptions",
      "title":"CSV Options",
      "description":"Select your CSV options",
      "type":"object",
      "properties":[
         {
            "name":"delimiter",
            "title":"Delimiter",
            "description":"Select your Delimiter",
            "type":"string",
            "isRequired":false,
            "default":",",
            "namedEnum":[
               {
                  "name":"Comma (,)",
                  "value":","
               },
               {
                  "name":"Tab (\\t)",
                  "value":"\t"
               }
            ],
            "readOnly":false,
            "hidden":false
         }
      ]
   }
]

Erstellen dynamischer Dropdown-Selektoren für Kundendatenfelder dynamic-dropdown-selectors

In Situationen, in denen Sie eine API dynamisch aufrufen und die Antwort verwenden möchten, um die Optionen in einem Dropdown-Menü dynamisch auszufüllen, können Sie einen dynamischen Dropdown-Selektor verwenden.

Die dynamischen Dropdown-Selektoren sehen in der Benutzeroberfläche genauso aus wie die regulären Dropdown-Selektoren. Der einzige Unterschied besteht darin, dass die Werte dynamisch von einer API abgerufen werden.

Um einen dynamischen Dropdown-Selektor zu erstellen, müssen Sie zwei Komponenten konfigurieren:

Schritt 1. Erstellen Sie einen Zielservermit einer responseFields -Vorlage für den dynamischen API-Aufruf, wie unten dargestellt.

{
   "name":"Server for dynamic dropdown",
   "destinationServerType":"URL_BASED",
   "urlBasedDestination":{
      "url":{
         "templatingStrategy":"PEBBLE_V1",
         "value":" <--YOUR-API-ENDPOINT-PATH--> "
      }
   },
   "httpTemplate":{
      "httpMethod":"GET",
      "headers":[
         {
            "header":"Authorization",
            "value":{
               "templatingStrategy":"PEBBLE_V1",
               "value":"My Bearer Token"
            }
         },
         {
            "header":"x-integration",
            "value":{
               "templatingStrategy":"PEBBLE_V1",
               "value":"{{customerData.integrationId}}"
            }
         },
         {
            "header":"Accept",
            "value":{
               "templatingStrategy":"NONE",
               "value":"application/json"
            }
         }
      ]
   },
   "responseFields":[
      {
         "templatingStrategy":"PEBBLE_V1",
         "value":"{% set list = [] %} {% for record in response.body %} {% set list = list|merge([{'name' : record.name, 'value' : record.id }]) %} {% endfor %}{{ {'list': list} | toJson | raw }}",
         "name":"list"
      }
   ]
}

Schritt 2. Verwenden Sie das Objekt dynamicEnum wie unten dargestellt. Im folgenden Beispiel wird das Dropdown-Menü User mit dem dynamischen Server abgerufen.

"customerDataFields": [
  {
    "name": "integrationId",
    "title": "Integration ID",
    "type": "string",
    "isRequired": true
  },
  {
    "name": "userId",
    "title": "User",
    "type": "string",
    "isRequired": true,
    "dynamicEnum": {
      "queryParams": [
        "integrationId"
      ],
      "destinationServerId": "<~dynamic-field-server-id~>",
      "authenticationRule": "CUSTOMER_AUTHENTICATION",
      "value": "$.list",
      "responseFormat": "NAME_VALUE"
    }
  }
]

Legen Sie den Parameter destinationServerId auf die ID des Zielservers fest, den Sie in Schritt 1 erstellt haben. Sie können die Ziel-Server-ID in der Antwort des API-Aufrufs Abrufen einer Zielserverkonfiguration sehen.

Erstellen verschachtelter Kundendatenfelder nested-fields

Sie können verschachtelte Kundendatenfelder für komplexe Integrationsmuster erstellen. Auf diese Weise können Sie eine Reihe von Auswahlen für den Kunden ketten.

Sie können beispielsweise verschachtelte Kundendatenfelder hinzufügen, um von Kunden zu verlangen, einen Integrationstyp mit Ihrem Ziel auszuwählen, gefolgt von einer weiteren Auswahl. Die zweite Auswahl ist ein verschachteltes Feld innerhalb des Integrationstyps.

Verwenden Sie zum Hinzufügen eines verschachtelten Felds den Parameter properties , wie unten dargestellt. Im folgenden Konfigurationsbeispiel sehen Sie drei separate verschachtelte Felder im Kundendatenfeld Ihr Ziel - Integrationsspezifische Einstellungen .

    {
      "name": "yourdestination",
      "title": "Yourdestination - Integration Specific Settings",
      "type": "object",
      "properties": [
        {
          "name": "agreement",
          "title": "Advertiser data destination terms agreement. Enter I AGREE.",
          "type": "string",
          "isRequired": true,
          "pattern": "I AGREE",
          "readOnly": false,
          "hidden": false
        },
        {
          "name": "account-name",
          "title": "Account name",
          "type": "string",
          "isRequired": true,
          "readOnly": false,
          "hidden": false
        },
        {
          "name": "email",
          "title": "Email address",
          "type": "string",
          "isRequired": false,
          "pattern": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$",
          "readOnly": false,
          "hidden": false
        }
      ],
      "isRequired": false,
      "readOnly": false,
      "hidden": false,

Erstellen von bedingten Kundendatenfeldern conditional-options

Sie können bedingte Kundendatenfelder erstellen, die im Aktivierungs-Workflow nur angezeigt werden, wenn Benutzerinnen und Benutzer eine bestimmte Option auswählen.

Beispielsweise können Sie bedingte Dateiformatierungsoptionen erstellen, die nur angezeigt werden, wenn Benutzerinnen und Benutzer einen bestimmten Dateityp auswählen.

Die folgende Konfiguration erstellt eine bedingte Gruppierung für CSV-Dateiformatierungsoptionen. Die CSV-Dateioptionen werden nur angezeigt, wenn Benutzerinnen oder Benutzer CSV als gewünschten Dateityp für den Export auswählen.

Um ein Feld als bedingt festzulegen, verwenden Sie den Parameter conditional wie unten gezeigt:

"conditional": {
   "field": "fileType",
   "operator": "EQUALS",
   "value": "CSV"
}

In einem größeren Kontext können Sie sehen, wie das Feld conditional in der unten stehenden Zielkonfiguration neben der Zeichenfolge fileType und dem Objekt csvOptions verwendet wird, in dem es definiert ist. Die bedingten Felder werden im Parameter properties definiert.

"customerDataFields":[
   {
      "name":"fileType",
      "title":"File Type",
      "description":"Select your file type",
      "type":"string",
      "isRequired":true,
      "enum":[
         "PARQUET",
         "CSV",
         "JSON"
      ],
      "readOnly":false,
      "hidden":false
   },
   {
      "name":"csvOptions",
      "title":"CSV Options",
      "description":"Select your CSV options",
      "type":"object",
      "conditional":{
         "field":"fileType",
         "operator":"EQUALS",
         "value":"CSV"
      },
      "properties":[
         {
            "name":"delimiter",
            "title":"Delimiter",
            "description":"Select your Delimiter",
            "type":"string",
            "isRequired":false,
            "default":",",
            "namedEnum":[
               {
                  "name":"Comma (,)",
                  "value":","
               },
               {
                  "name":"Tab (\\t)",
                  "value":"\t"
               }
            ],
            "readOnly":false,
            "hidden":false
         },
         {
            "name":"quote",
            "title":"Quote Character",
            "description":"Select your Quote character",
            "type":"string",
            "isRequired":false,
            "default":"",
            "namedEnum":[
               {
                  "name":"Double Quotes (\")",
                  "value":"\""
               },
               {
                  "name":"Null Character (\u0000)",
                  "value":"\u0000"
               }
            ],
            "readOnly":false,
            "hidden":false
         },
         {
            "name":"escape",
            "title":"Escape Character",
            "description":"Select your Escape character",
            "type":"string",
            "isRequired":false,
            "default":"\\",
            "namedEnum":[
               {
                  "name":"Back Slash (\\)",
                  "value":"\\"
               },
               {
                  "name":"Single Quote (')",
                  "value":"'"
               }
            ],
            "readOnly":false,
            "hidden":false
         },
         {
            "name":"emptyValue",
            "title":"Empty Value",
            "description":"Select the output value of blank fields",
            "type":"string",
            "isRequired":false,
            "default":"",
            "namedEnum":[
               {
                  "name":"Empty String",
                  "value":""
               },
               {
                  "name":"\"\"",
                  "value":"\"\""
               },
               {
                  "name":"null",
                  "value":"null"
               }
            ],
            "readOnly":false,
            "hidden":false
         },
         {
            "name":"nullValue",
            "title":"Null Value",
            "description":"Select the output value of 'null' fields",
            "type":"string",
            "isRequired":false,
            "default":"null",
            "namedEnum":[
               {
                  "name":"Empty String",
                  "value":""
               },
               {
                  "name":"\"\"",
                  "value":"\"\""
               },
               {
                  "name":"null",
                  "value":"null"
               }
            ],
            "readOnly":false,
            "hidden":false
         }
      ],
      "isRequired":false,
      "readOnly":false,
      "hidden":false
   }
]

Unten sehen Sie den resultierenden Bildschirm der Benutzeroberfläche, der auf der oben beschriebenen Konfiguration basiert. Wenn die Benutzerinnen oder Benutzer den Dateityp CSV auswählen, werden in der Benutzeroberfläche zusätzliche Dateiformatierungsoptionen angezeigt, die sich auf den CSV-Dateityp beziehen.

Zugriff auf vorlagenbasierte Kundendatenfelder accessing-templatized-fields

Wenn für Ihr Ziel Benutzereingaben erforderlich sind, müssen Sie Ihren Benutzerinnen und Benutzern eine Auswahl von Kundendatenfeldern bereitstellen, die sie über die Platform-Benutzeroberfläche ausfüllen können. Anschließend müssen Sie Ihren Ziel-Server so konfigurieren, dass die Benutzereingabe aus den Kundendatenfeldern korrekt gelesen wird. Dies erfolgt über vorlagenbasierte Felder.

Vorlagenfelder verwenden das Format {{customerData.fieldName}}, wobei fieldName der Name des Kundendatenfelds ist, aus dem Informationen gelesen werden. Allen in der Vorlage enthaltenen Kundendatenfeldern wird customerData. vorangestellt, und sie werden in doppelte Klammern {{ }} eingeschlossen.

Betrachten wir beispielsweise die folgende Amazon S3-Zielkonfiguration:

"customerDataFields":[
   {
      "name":"bucketName",
      "title":"Enter the name of your Amazon S3 bucket",
      "description":"Amazon S3 bucket name",
      "type":"string",
      "isRequired":true,
      "pattern":"(?=^.{3,63}$)(?!^(\\d+\\.)+\\d+$)(^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$)",
      "readOnly":false,
      "hidden":false
   },
   {
      "name":"path",
      "title":"Enter the path to your S3 bucket folder",
      "description":"Enter the path to your S3 bucket folder",
      "type":"string",
      "isRequired":true,
      "pattern":"^[0-9a-zA-Z\\/\\!\\-_\\.\\*\\''\\(\\)]*((\\%SEGMENT_(NAME|ID)\\%)?\\/?)+$",
      "readOnly":false,
      "hidden":false
   }
]

Diese Konfiguration fordert Ihre Benutzerinnen und Benutzer zur Eingabe ihres Amazon S3-Behälternamens und -Ordnerpfads in die entsprechenden Kundendatenfelder auf.

Damit Experience Platform ordnungsgemäß eine Verbindung zu Amazon S3 herstellt, muss Ihr Ziel-Server so konfiguriert sein, dass die Werte aus diesen beiden Kundendatenfeldern gelesen werden, wie unten dargestellt:

 "fileBasedS3Destination":{
      "bucketName":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.bucketName}}"
      },
      "path":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.path}}"
      }
   }

Die Vorlagenwerte {{customerData.bucketName}} und {{customerData.path}} lesen die von Benutzerinnen oder Benutzern eingegebenen Werte, damit Experience Platform erfolgreich eine Verbindung zur Zielplattform herstellen kann.

Weitere Informationen zum Konfigurieren des Ziel-Servers zum Lesen von Vorlagenfeldern finden Sie in der Dokumentation zu hartcodierten im Vergleich zu vorlagenbasierten Feldern.

Nächste Schritte next-steps

Nachdem Sie diesen Artikel gelesen haben, sollten Sie besser verstehen, wie Sie Ihren Benutzerinnen und Benutzern ermöglichen können, Informationen über Kundendatenfelder in die Experience Platform-Benutzeroberfläche einzugeben. Jetzt wissen Sie auch, wie Sie das richtige Kundendatenfeld für Ihren Anwendungsfall auswählen und Kundendatenfelder in der Platform-Benutzeroberfläche konfigurieren, bestellen und gruppieren können.

Weitere Informationen zu den anderen Zielkomponenten finden Sie in den folgenden Artikeln: