顧客データフィールドを使用したユーザー入力の設定
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 フィールドを自動的に追加します。 上記の例で示すように、NameおよびDescription フィールドは、顧客データフィールド設定に含まれることなく、UIでレンダリングされます。
顧客データフィールドの順序付け ordering
宛先設定に顧客データフィールドを追加した順序は、Experience 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 Options オブジェクト内の目的の顧客データフィールドを収集します（下図を参照）。
"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に設定します。 宛先サーバー設定 API呼び出しを取得する応答に、宛先サーバーIDが表示されます。
ネストされた顧客データフィールドの作成 nested-fields
複雑な統合パターンに対して、ネストされた顧客データフィールドを作成できます。 これらのトークンを使用すると、顧客の一連の選択肢を連結できます。
例えば、ネストされた顧客データフィールドを追加して、顧客が宛先との統合タイプを選択し、その後すぐに別の選択を行うように要求できます。 2つ目の選択は、統合タイプ内のネストされたフィールドです。
ネストされたフィールドを追加するには、次に示すようにproperties パラメーターを使用します。 次の設定例では、宛先 – 統合特定設定の顧客データフィールド内に、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"
}
より広いコンテキストでは、以下の宛先設定でconditional フィールドがfileType文字列と、それが定義されているcsvOptions オブジェクトと共に使用されています。 条件付きフィールドは、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で、ユースケースに適した顧客データフィールドを選択し、顧客データフィールドを設定、並べ替え、グループ化する方法についても説明しました。
その他の宛先コンポーネントについて詳しくは、以下の記事を参照してください。