顧客データフィールドを使用したユーザー入力の設定
Experience Platform UIで宛先に接続する際に、特定の設定の詳細を指定するか、ユーザーが利用できる特定のオプションを選択する必要がある場合があります。 Destination SDK では、これらのオプションは、顧客データフィールドと呼ばれます。
このコンポーネントが Destination SDK で作成される統合のどこに適合するかを把握するには、設定オプションドキュメントの図を参照するか、以下の宛先設定の概要ページを参照してください。
顧客データフィールドの使用例 use-cases
ユーザーがExperience Platform UIにデータを入力する必要がある様々なユースケースで、顧客データフィールドを使用します。 例えば、ユーザーが以下を指定する必要がある場合に、顧客データフィールドを使用します。
- ファイルベースの宛先用の、クラウドストレージバケット名およびパス。
- 顧客データフィールドによって受け入れられる形式。
- ユーザーが選択できる、使用可能なファイル圧縮タイプ。
- リアルタイム（ストリーミング）統合に使用できるエンドポイントのリスト。
/authoring/destinations エンドポイントを介して顧客データフィールドを設定できます。 このページに表示されるコンポーネントを設定できる、詳細な API 呼び出しの例については、以下の API リファレンスページを参照してください。
この記事では、宛先に使用できるサポートされているすべての顧客データフィールド設定タイプについて説明し、顧客がExperience Platform UIでどのような情報を表示するかを示します。
サポートされる統合タイプ supported-integration-types
このページで説明される機能をサポートする統合のタイプについて詳しくは、以下の表を参照してください。
サポートされるパラメーター supported-parameters
独自の顧客データフィールドを作成する際に、以下の表で説明されているパラメーターを使用して、その動作を設定できます。
nametitle フィールドが空か見つからない場合を除き、Experience Platform UIには表示されません。type導入するカスタムフィールドのタイプを示します。 使用できる値：
stringobjectinteger
titlename 値からフィールド名を継承します。descriptionisRequiredpattern^[A-Za-z]+$ を入力します。enumdefaultenum リストから定義します。hiddenuniquereadOnly次の例では、customerDataFields セクションは、ユーザーが宛先に接続する際にExperience Platform UIに入力する必要がある2つのフィールドを定義しています。
Account ID：宛先プラットフォームのユーザーアカウント ID。Endpoint region：ユーザーが接続する API の地域エンドポイント。enumセクションでは、ユーザーが選択できる内で定義された値を含むドロップダウンメニューが作成されます。
"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
}
]
以下の画像に、結果の UI エクスペリエンスを示します。
宛先接続名と説明 names-description
新しい宛先を作成すると、Destination SDKはExperience Platform UIの宛先接続画面に 名前 および説明 フィールドを自動的に追加します。 上記の例からわかるように、NameおよびDescription フィールドは、顧客データフィールド設定に含まれることなく、UIでレンダリングされます。
顧客データフィールドの順序付け ordering
宛先設定で顧客データフィールドを追加する順序は、Experience Platform UIに反映されます。
例えば、以下の設定はUIに適切に反映され、オプションは名前、説明、バケット名、フォルダーパス、ファイルタイプ、圧縮形式の順序で表示されます。
"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"
]
}
]
顧客データフィールドのグループ化 grouping
いくつかの顧客データフィールドを 1 つのセクション内にグループ化できます。 UI で宛先への接続を設定する際に、ユーザーは、類似したフィールドを視覚的にグループ化することで、メリットが得られます。
これを行うには、"type": "object"を使用してグループを作成し、グループ化 CSV オプション がハイライト表示されている次の画像に示すように、properties オブジェクト内の目的の顧客データフィールドを収集します。
"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
}
]
}
]
顧客データフィールド用のドロップダウンセレクターの作成 dropdown-selectors
ユーザーがいくつかのオプションから選択できるようにしたい状況（例えば、CSV ファイルのフィールドを区切るためにどの文字を使用するか）では、UI にドロップダウンフィールドを追加できます。
これを行うには、以下に示すように、namedEnum オブジェクトを使用して、ユーザーが選択できるオプションの default 値を設定します。
"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
}
]
}
]
顧客データフィールド用の動的ドロップダウンセレクターの作成 dynamic-dropdown-selectors
APIを動的に呼び出し、応答を使用してドロップダウンメニューのオプションを動的に入力する場合は、動的ドロップダウンセレクターを使用できます。
動的ドロップダウンセレクターは、UIの通常のドロップダウンセレクターと同じように見えます。 唯一の違いは、値がAPIから動的に取得されることです。
動的ドロップダウンセレクターを作成するには、次の2つのコンポーネントを設定する必要があります。
-
次に示すように、動的API呼び出しの
responseFieldsテンプレートを含む宛先サーバーを作成します。code language-json { "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" } ] } -
次に示すように、
dynamicEnumオブジェクトを使用します。 次の例では、動的サーバーを使用してUserドロップダウンが取得されています。code language-json line-numbers h-13-21 "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" } } ]
destinationServerId パラメーターを、手順1で作成した宛先サーバーのIDに設定します。 宛先サーバー設定🔗 API呼び出しを取得する応答に、宛先サーバーIDが表示されます。
ネストされた顧客データフィールドの作成 nested-fields
複雑な統合パターンに対して、ネストされた顧客データフィールドを作成できます。 これらのトークンを使用すると、顧客の一連の選択肢を連結できます。
例えば、ネストされた顧客データフィールドを追加して、顧客が宛先との統合タイプを選択し、その後すぐに別の選択を行うように要求できます。 2つ目の選択は、統合タイプ内のネストされたフィールドです。
ネストされたフィールドを追加するには、次に示すようにproperties パラメーターを使用します。 次の設定例では、宛先 – 統合特定設定の顧客データフィールド内に、3つのネストされたフィールドが表示されます。
isRequired パラメーターを設定できます。 たとえば、以下の設定スニペットでは、最初の2つのネストされたフィールドが必須（強調表示された行）としてマークされ、顧客はフィールドの値を選択しない限り続行できません。 必須フィールドについて詳しくは、 サポートされるパラメーター セクションを参照してください。 {
"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,
条件付き顧客データフィールドの作成 conditional-options
ユーザーが特定のオプションを選択する際にのみアクティベーションワークフローに表示される、条件付き顧客データフィールドを作成できます。
例えば、ユーザーが特定のファイル書き出しタイプを選択する場合にのみ表示される条件付きファイル形式オプションを作成できます。
以下の設定は、CSV ファイル形式オプション用の条件付きグループを作成します。 CSV ファイルオプションは、ユーザーが CSV を書き出し用のファイルタイプとして選択する場合にのみ表示されます。
フィールドを条件付きとして設定するには、以下に示すように、conditional パラメーターを使用します。
"conditional": {
"field": "fileType",
"operator": "EQUALS",
"value": "CSV"
}
より広いコンテキストでは、以下の宛先設定で、fileType 文字列とそれが定義されている csvOptions オブジェクトと共に conditional フィールドが使用されているのを確認できます。 条件付きフィールドは、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
}
]
以下に、上記の設定に基づいた結果の UI 画面を確認できます。 ユーザーがファイルタイプで CSV を選択すると、CSV ファイルタイプを参照する追加のファイル形式オプションが UI に表示されます。
テンプレート化された顧客データフィールドへのアクセス accessing-templatized-fields
宛先でユーザー入力が必要な場合は、顧客データフィールドの選択をユーザーに提供する必要があります。このフィールドは、Experience Platform UIを通じて入力できます。 次に、顧客データフィールドからユーザー入力を正しく読み取るために宛先サーバーを設定する必要があります。 これは、テンプレート化されたフィールドを使用して行われます。
テンプレート化されたフィールドは、{{customerData.fieldName}} という形式を使用します（fieldName は、情報を読み取る顧客データフィールドの名前）。 すべてのテンプレート化された顧客データフィールドは、先頭に customerData. が付き、二重中括弧 {{ }} で囲まれています。
例えば、次のAmazon S3宛先設定について考えてみましょう。
"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
}
]
この設定では、Amazon S3 バケット名およびフォルダーパスをそれぞれの顧客データフィールドに入力することを促すプロンプトをユーザーに表示します。
Experience Platform が Amazon S3 に正しく接続するために、以下に示すように、これらの 2 つの顧客データフィールドから値を読み取るように宛先サーバーが設定されている必要があります。
"fileBasedS3Destination":{
"bucketName":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.bucketName}}"
},
"path":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.path}}"
}
}
テンプレート化された値{{customerData.bucketName}}と{{customerData.path}}は、ユーザーが指定した値を読み取り、Experience Platformが宛先プラットフォームに正常に接続できるようにします。
テンプレート化されたフィールドを読み取るための宛先サーバーの設定方法について詳しくは、ハードコーディングされたフィールドとテンプレート化されたフィールドの比較のドキュメントを参照してください。
次の手順 next-steps
ユーザーが顧客データフィールドを通じてExperience Platform UIに情報を入力する方法を理解できました。 また、ユースケースに適した顧客データフィールドを選択し、Experience Platform UIで顧客データフィールドを設定、並べ替え、グループ化する方法についても説明します。
その他の宛先コンポーネントについて詳しくは、以下の記事を参照してください。