Konfigurera användarindata via kunddatafält

När du ansluter till ditt mål i användargränssnittet i Experience Platform kan du behöva ange specifik konfigurationsinformation eller välja specifika alternativ som du gör tillgängliga för dem. I Destination SDK kallas dessa alternativ för kunddatafält.

Om du vill veta var den här komponenten passar in i en integrering som skapats med Destination SDK kan du läsa diagrammet i dokumentationen för konfigurationsalternativ eller följande sidor med en översikt över målkonfigurationen:

Användningsexempel för kunddatafält use-cases

Använd kunddatafält för en mängd olika användningsområden där du vill att användare ska kunna mata in data i användargränssnittet i Experience Platform. Använd t.ex. kunddatafält när användare måste ange:

Du kan konfigurera kunddatafält via slutpunkten /authoring/destinations. På följande API-referenssidor finns detaljerade API-anropsexempel där du kan konfigurera komponenterna som visas på den här sidan.

I den här artikeln beskrivs alla konfigurationstyper för kunddatafält som stöds och som du kan använda för ditt mål. Artikeln innehåller även information om vad kunderna kommer att se i användargränssnittet för Experience Platform.

Integrationstyper som stöds supported-integration-types

Se tabellen nedan för mer ingående information om vilka typer av integreringar som stöder de funktioner som beskrivs på den här sidan.

parametrar som stöds supported-parameters

När du skapar egna kunddatafält kan du använda de parametrar som beskrivs i tabellen nedan för att konfigurera deras beteende.

I exemplet nedan definierar avsnittet customerDataFields två fält som användare måste ange i plattformsgränssnittet vid anslutning till målet:

"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
   }
]

Den resulterande gränssnittsupplevelsen visas i bilden nedan.

Namn och beskrivningar för målanslutning names-description

När du skapar ett nytt mål lägger Destination SDK automatiskt till Name- och Description-fält på målanslutningsskärmen i plattformsgränssnittet. Som du kan se i exemplet ovan återges fälten Name och Description i användargränssnittet utan att inkluderas i konfigurationen för kunddatafält.

Beställa kunddatafält ordering

Den ordning i vilken du lägger till kunddatafälten i målkonfigurationen återspeglas i plattformens användargränssnitt.

Konfigurationen nedan återspeglas till exempel i användargränssnittet, där alternativen visas i ordningen Name, Description, Bucket name, Folder path, File Type, Compression format.

"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"
   ]
}
]

Gruppera kunddatafält grouping

Du kan gruppera flera kunddatafält i ett avsnitt. När du konfigurerar anslutningen till målet i användargränssnittet kan användarna se och dra nytta av en visuell gruppering av liknande fält.

Det gör du genom att använda "type": "object" för att skapa gruppen och samla in önskade kunddatafält i ett properties -objekt, vilket visas i bilden nedan där grupperingen CSV Options är markerad.

"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
         }
      ]
   }
]

Skapa nedrullningsbara väljare för kunddatafält dropdown-selectors

I situationer där du vill att användarna ska kunna välja mellan flera alternativ, t.ex. vilket tecken som ska användas för att avgränsa fälten i CSV-filer, kan du lägga till nedrullningsbara fält i användargränssnittet.

Om du vill göra det använder du objektet namedEnum så som visas nedan och konfigurerar ett default-värde för de alternativ som användaren kan välja.

"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
         }
      ]
   }
]

Skapa dynamiska listruteväljare för kunddatafält dynamic-dropdown-selectors

I situationer där du vill anropa ett API dynamiskt och använda svaret för att dynamiskt fylla i alternativen i en listruta kan du använda en dynamisk listruteväljare.

De dynamiska listrutesäljarna ser identiska ut som de vanliga listrutesäljarna i användargränssnittet. Den enda skillnaden är att värdena hämtas dynamiskt från ett API.

Om du vill skapa en dynamisk nedrullningsbar väljare måste du konfigurera två komponenter:

Steg 1. Skapa en målserver med en responseFields-mall för det dynamiska API-anropet, vilket visas nedan.

{
   "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"
      }
   ]
}

Steg 2. Använd objektet dynamicEnum så som visas nedan. I exemplet nedan hämtas listrutan User med den dynamiska servern.

"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"
    }
  }
]

Ange parametern destinationServerId till ID:t för målservern som du skapade i steg 1. Du kan se målserver-ID som svar på API-anropet för att hämta en målserverkonfiguration.

Skapa kapslade kunddatafält nested-fields

Du kan skapa kapslade kunddatafält för komplexa integreringsmönster. På så sätt kan du kedja en serie markeringar för kunden.

Du kan t.ex. lägga till kapslade kunddatafält för att kräva att kunderna väljer en integreringstyp med målet, omedelbart följt av ett annat val. Den andra markeringen är ett kapslat fält inom integrationstypen.

Om du vill lägga till ett kapslat fält använder du parametern properties enligt nedan. I konfigurationsexemplet nedan kan du se tre separata kapslade fält i kunddatafältet Ditt mål - Integrationsspecifika inställningar.

    {
      "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,

Skapa villkorliga kunddatafält conditional-options

Du kan skapa villkorsstyrda kunddatafält, som bara visas i aktiveringsarbetsflödet när användarna väljer ett visst alternativ.

Du kan till exempel skapa alternativ för villkorsstyrd filformatering som bara visas när användarna väljer en viss filexporttyp.

I konfigurationen nedan skapas en villkorsstyrd gruppering för CSV-filformateringsalternativ. CSV-filalternativen visas bara när användaren väljer CSV som önskad filtyp för export.

Om du vill ange ett fält som villkorligt använder du parametern conditional enligt nedan:

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

I ett större sammanhang kan du se att fältet conditional används i målkonfigurationen nedan, tillsammans med strängen fileType och objektet csvOptions som det definierats i. Villkorsfälten definieras i parametern properties.

"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
   }
]

Nedan visas den resulterande gränssnittsskärmen baserat på konfigurationen ovan. När användaren väljer filtypen CSV visas ytterligare filformateringsalternativ som refererar till CSV-filtypen i användargränssnittet.

Åtkomst till mallsidiga kunddatafält accessing-templatized-fields

När målet kräver användarindata måste du tillhandahålla ett urval av kunddatafält till dina användare, som de kan fylla i via plattformsgränssnittet. Sedan måste du konfigurera målservern så att den läser användarindata från kunddatafälten korrekt. Detta görs genom mallsidiga fält.

Mallade fält använder formatet {{customerData.fieldName}}, där fieldName är namnet på kunddatafältet som du läser information från. Alla mallsidiga kunddatafält föregås av customerData. och omsluts av dubbla klammerparenteser {{ }}.

Låt oss titta på följande Amazon S3-destinationskonfiguration:

"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
   }
]

Den här konfigurationen uppmanar dina användare att ange sina Amazon S3-bucketnamn och mappsökväg i sina respektive kunddatafält.

För att Experience Platform ska kunna ansluta till Amazon S3 måste målservern vara konfigurerad att läsa värdena från dessa två kunddatafält, vilket visas nedan:

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

De mallatiserade värdena {{customerData.bucketName}} och {{customerData.path}} läser de värden som användaren anger så att Experience Platform kan ansluta till målplattformen.

Mer information om hur du konfigurerar målservern för att läsa mallsidiga fält finns i dokumentationen om hårdkodade jämfört med mallsidiga fält.

Nästa steg next-steps

När du har läst den här artikeln bör du få en bättre förståelse för hur du kan låta dina användare mata in information i användargränssnittet i Experience Platform via kunddatafält. Du vet nu också hur du väljer rätt kunddatafält för ditt användningsfall och konfigurerar, beställer och grupperar kunddatafält i plattformsgränssnittet.

Mer information om de andra målkomponenterna finns i följande artiklar: