Konfigurera användarindata via kunddatafält

Senaste uppdatering: 2023-11-07
  • Skapat för:
  • Developer
    User
    Admin
    Leader

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.

Mer information om var den här komponenten passar in i en integrering som skapas med Destination SDK finns i diagrammet i konfigurationsalternativ eller se följande sidor med översikt över målkonfigurationen:

Användningsexempel för kunddatafält

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:

  • Lagringsbucket-namn och sökvägar för molnet, för filbaserade mål.
  • Det format som accepteras av kunddatafälten.
  • Tillgängliga filkomprimeringstyper som användarna kan välja mellan.
  • Listor över tillgängliga slutpunkter för realtidsintegreringar (direktuppspelning).

Du kan konfigurera kunddatafält via /authoring/destinations slutpunkt. 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.

VIKTIGT

Alla parameternamn och värden som stöds av Destinationen SDK är skiftlägeskänslig. Undvik skiftlägeskänslighetsfel genom att använda parameternamn och värden exakt som de visas i dokumentationen.

Integrationstyper som stöds

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.

Integrationstyp Stöder funktioner
Integrering i realtid (direktuppspelning) Ja
Filbaserade (batch) integreringar Ja

parametrar som stöds

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

Parameter Typ Obligatoriskt/valfritt Beskrivning
name Sträng Obligatoriskt Ange ett namn för det anpassade fält som du introducerar. Det här namnet visas inte i plattformens användargränssnitt, såvida inte title fältet är tomt eller saknas.
type Sträng Obligatoriskt Anger typen av anpassat fält som du introducerar. Godkända värden:
  • string
  • object
  • integer
title Sträng Valfritt Anger fältets namn, så som det visas av kunderna i plattformsgränssnittet. Om fältet är tomt eller saknas ärver gränssnittet fältnamnet från name värde.
description Sträng Valfritt Ange en beskrivning för det anpassade fältet. Den här beskrivningen visas inte i plattformsgränssnittet.
isRequired Boolean Valfritt Anger om användare måste ange ett värde för det här fältet i arbetsflödet för målkonfiguration.
pattern Sträng Valfritt Tvingar fram ett mönster för det anpassade fältet, om det behövs. Använd reguljära uttryck för att framtvinga ett mönster. Om dina kund-ID:n inte innehåller siffror eller understreck anger du ^[A-Za-z]+$ i detta fält.
enum Sträng Valfritt Återger det anpassade fältet som en listruta och visar de alternativ som är tillgängliga för användaren.
default Sträng Valfritt Definierar standardvärdet från ett enum lista.
hidden Boolean Valfritt Anger om kunddatafältet visas i användargränssnittet eller inte.
unique Boolean Valfritt Använd den här parametern när du behöver skapa ett kunddatafält vars värde måste vara unikt för alla måldataflöden som har konfigurerats av en användares organisation. Till exempel Integration alias fältet i Anpassad personalisering målet måste vara unikt, vilket innebär att två separata dataflöden till det här målet inte kan ha samma värde för det här fältet.
readOnly Boolean Valfritt Anger om kunden kan ändra fältets värde eller inte.

I exemplet nedan är customerDataFields -avsnittet definierar två fält som användare måste ange i plattformens användargränssnitt när de ansluter till målet:

  • Account ID: Ett användarkonto-ID för målplattformen.
  • Endpoint region: Den regionala slutpunkten för det API som de ansluter till. The enum skapar en rullgardinsmeny med de värden som är definierade i som är tillgängliga för användarna att välja.
"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.

En gränssnittsbild som visar ett exempel på kunddatafält.

Namn och beskrivningar för målanslutning

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

VIKTIGT

Om du lägger till Name och Description fält i konfigurationen av kunddatafält, användarna ser dem duplicerade i användargränssnittet.

Beställa kunddatafält

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

Bild som visar ordningen för filformateringsalternativ i användargränssnittet för Experience Platform.

Gruppera kunddatafält

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.

Om du vill göra det använder du "type": "object" för att skapa gruppen och samla in önskade kunddatafält inom en properties objekt, som visas i bilden nedan, där grupperingen CSV Options är markerat.

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

Bild som visar gruppering av kunddatafält i användargränssnittet.

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.

Använd namedEnum enligt nedan och konfigurera ett default värdet 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
         }
      ]
   }
]

Skärminspelning som visar ett exempel på listruteväljare som har skapats med den konfiguration som visas ovan.

Skapa dynamiska listruteväljare för kunddatafält

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 listruteväljarna ser likadana ut som vanliga listruteväljare 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 responseFields mall för det dynamiska API-anropet enligt 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 dynamicEnum som visas nedan. I exemplet nedan är User listrutan hämtas 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 destinationServerId parameter till ID:t för målservern som du skapade i steg 1. Du kan se målserverns ID i svaret från hämta en målserverkonfiguration API-anrop.

Skapa villkorliga kunddatafält

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 conditional enligt nedan:

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

I ett större sammanhang kan du se conditional fält som används i målkonfigurationen nedan, tillsammans med fileType strängen och csvOptions det objekt som det är definierat i.

"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.

Skärminspelning som visar alternativet för villkorsstyrd filformatering för CSV-filer.

Åtkomst till mallsidiga kunddatafält

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 innesluten inom 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 bucket name and folder path into their respective customer data fields.

För att Experience Platform ska kunna ansluta till Amazon S3må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 mallsidiga värdena {{customerData.bucketName}} och {{customerData.path}} läsa 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 mallsidesfält.

Nästa steg

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:

På denna sida