顧客データフィールドを使用したユーザー入力の設定
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 フィールドが空か見つからない場合を除いて、Platform UI に表示されません。type導入するカスタムフィールドのタイプを示します。使用できる値：
stringobjectinteger
titlename 値からフィールド名を継承します。descriptionisRequiredpattern^[A-Za-z]+$ を入力します。enumdefaultenum リストから定義します。hiddenuniquereadOnly以下の例では、customerDataFields セクションで、宛先に接続する際にユーザーが 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 は、名前 および 説明 フィールドを Platform UI の宛先接続画面に自動的に追加します。上記の例で確認できるように、名前 および 説明 フィールドは、顧客データフィールド設定に含まれることなく、UI でレンダリングされます。
顧客データフィールドの順序付け ordering
宛先設定で顧客データフィールドを追加した順序は、Platform UI に反映されます。
例えば、以下の設定は、UI にそのまま反映され、オプションは、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"
]
}
]
顧客データフィールドのグループ化 grouping
いくつかの顧客データフィールドを 1 つのセクション内にグループ化できます。UI で宛先への接続を設定する際に、ユーザーは、類似したフィールドを視覚的にグループ化することで、メリットが得られます。
これを行うには、以下の画像に示すように、"type": "object" を使用してグループを作成し、properties オブジェクト内に目的の顧客データフィールドを収集します（CSV オプション のグループ化がハイライト表示されています）。
"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 つのコンポーネントを設定する必要があります。
手順 1.以下に示すように、動的 API 呼び出し用の responseFields テンプレートを使用して 宛先サーバーを作成する 要があります。
{
"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"
}
]
}
手順 2. 次に示すように、dynamicEnum オブジェクトを使用します。 次の例では、User ドロップダウンが動的サーバーを使用して取得されます。
"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 に設定します。 宛先サーバー ID は、 宛先サーバー設定の取得API 呼び出しの応答で確認できます。
ネストされた顧客データフィールドの作成 nested-fields
複雑な統合パターン用にネストされた顧客データフィールドを作成できます。 これにより、顧客に対して一連の選択を連結できます。
例えば、ネストされた顧客データフィールドを追加して、顧客に宛先との統合タイプの選択を要求し、その直後に別の選択を要求できます。 2 つ目の選択は、統合タイプ内のネストされたフィールドです。
ネストされたフィールドを追加するには、次に示すように、properties パラメーターを使用します。 以下の設定例では、「Yourdestination – 統合固有の設定 顧客データフィールド内に 3 つの異なるネストされたフィールドを確認 きます。
isRequired パラメーターを設定できるようになりました。 例えば、以下の設定スニペットでは、ネストされた最初の 2 つのフィールドが必須としてマークされており（ハイライト表示された行 xxx）、ユーザーはフィールドの値を選択しない限り続行できません。 必須フィールドについて詳しくは、 サポートされるパラメーターの節を参照してください。 {
"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
宛先がユーザー入力を必要とする場合、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 でユーザーが情報を入力できるようにする方法について、理解を深めることができました。また、ユースケースに対して適切な顧客データフィールドを選択する方法や、Platform UI で顧客データフィールドを設定、順序付け、グループ化する方法についても理解しました。
その他の宛先コンポーネントについて詳しくは、以下の記事を参照してください。