Customer Insights - Journeys でフォームをキャプチャする

[アーティクル]
04/30/2024

フォームキャプチャは、Customer Insights - Journeys フォームエディターを使用して作成されていない既存のフォームから送信を取得するために使用されます。既存のフォームが Dynamics 365 以外のシステムにも送信される場合、または既存のフォームに複雑なロジックが含まれ、Customer Insights - Journeys フォームエディターで簡単に再作成できない場合は、フォームキャプチャをお勧めします。既存のフォームを Customer Insights - Journeys フォームエディターを使用して再作成できる場合は、フォームキャプチャ機能を使用しないことをお勧めします。

フォームキャプチャでは、標準フォームと同じ API を使用して送信を処理します。フォームキャプチャにも同じセキュリティ通知が適用されます。

重要

フォームキャプチャには開発者の支援が必要です。 Customer Insights - Journeys フォームエディターを使用してフォームを作成し、既存のページにフォームを埋め込む方が簡単な場合が多いです。

重要

フォームのキャプチャには、DynamicsMKT_Forms ソリューションのバージョン 1.1.35355 以降が必要です 。試用版インスタンスをプロビジョニングする場合、常に最新バージョンが自動的に提供されるわけではありません。フォームのキャプチャを試行する前に、Customer Insights - Journeys が更新されていることを確認してください。

フォームキャプチャを有効にする

フォームキャプチャ機能は既定で無効になっています。 フォームキャプチャ の切り替えは、設定>機能スイッチ>フォームで有効にできます。

機能スイッチでフォームキャプチャを有効にします。

フォームキャプチャの仕組み

フォームキャプチャは標準的な Customer Insights - Journeys フォームの送信を模倣します。既存のフォームの送信を Customer Insights - Journeys にリンクするには、Customer Insights - Journeys フォームエディターを使用してフォームを作成する必要があります。そのフォームを公開すると、フォームキャプチャスクリプトを取得できます。このスクリプトは、既存のフォームを含む Web ページに埋め込む必要があります。スクリプトには、リードまたは取引先担当者エンティティの属性にマッピングする既存のフォームフィールドの定義が含まれています。 Customer Insights - Journeys ではすべての送信と分析を確認できます。 送信されたマーケティングフォーム トリガーを使って、ジャーニーオーケストレーションでこのフォームを使用することもできます。このフォーム送信では、連絡先の同意および関連する目的またはトピックを作成または更新することもできます。

ステップバイステップでフォームをキャプチャする

Customer Insights - Journeys フォームエディターでフォームキャプチャを作成する

新しいキャプチャフォームスクリプトを作成するには、Customer Insights - Journeys>チャネル>フォームに移動し、コマンドバーの新規を選択します。
フォームに名前を付け、適切な対象者を選択します。ターゲット対象者の選択は重要です。フォームキャプチャスクリプトフィールド ->属性マッピングは、選択したターゲット対象者 (エンティティ) の属性に対してのみ利用可能です。
既存のフォームフィールドにマップするすべてのフィールドを追加します。この手順は必須ではありません、フィールド > 属性 マッピングはフォームキャプチャコードで定義されます。適切なフィールドをフォームに追加すると、フォームキャプチャスクリプトに属性マッピングのプレースホルダーが生成され、マッピング定義が容易になります。
目的やトピックなどの同意要素を追加し、構成します。 Customer Insights - Journeys で電子メールとテキストメッセージの同意を管理する方法について説明します。

重要

同意の定義はフォームエディターで行う必要があります。フォームキャプチャコードスニペットで行われた同意設定への変更は無視されます。
送信ボタンを追加します。公開前にフォームを正常に検証するには、送信ボタンが必要です。
右上隅の画面上部で公開ボタンを使用してフォームを公開します。フォームキャプチャコードスニペットをコピーし、既存のフォームを含む Web ページにコードスニペットを埋め込むか、コードスニペットを開発者に渡します。コードスニペットには、開発者にガイダンスを提供するドキュメントへのリンクがすでに含まれています。

重要

既存のフォームがホストされているドメイン名は、外部フォームホスティングに対して有効にする必要があります。それ以外の場合は、フォーム送信はキャプチャされません。ドメイン認証の詳細について説明します。

キャプチャスクリプトをページとマッピング定義に埋め込む

前述の手順でコピーしたコードスニペットはテンプレートとして機能するため、特定の使用例に合わせて調整する必要があります。生成されたテンプレート内で ***Please fill*** とマークされているすべての要素を置き換え、シナリオに合わせてロジックを調整する必要があります。

既存のフォーム送信は、FormCapture.bundle.js ファイルで定義され、スニペットに含まれる JavaScript API を使用して Customer Insights - Journeys に送信されます。

フォームキャプチャ設定は次の手順で行います:

ページ上のフォーム要素への参照を取得します。
Customer Insights - Journeys のフィールド (エンティティ属性) 上でフォームフィールドのマッピングを定義します。
Customer Insights - Journeys の同意モデルの同意フィールドのマッピングを定義します。
フォーム送信を Customer Insights - Journeys に送信します。

1. フォーム要素への参照を取得する

フォーム要素への参照を取得するには、waitForElement ヘルパー関数を使用できます。また、動的にレンダリングされる要素でも機能し、指定されたセレクターを持つ要素がページ上で見つかった時点で解決される Promise を返します。 CSS セレクターのリファレンスについては、このドキュメントを参照してください。

例:

<form id="form1">
...
</form>

<script>
d365mktformcapture.waitForElement("#form1").then(form => {
  ...
});
</script>

2. フォームフィールドのマッピングを定義する

フォーム内のフィールドは、Customer Insights - Journeys のそれぞれのフィールド (エンティティ属性) にマップする必要があります。マッピングは関数 d365mktformcapture.serializeForm(form, mappings) で定義されます。

例:

<form id="form1">
  <p>FirstName: <input type="text" name="firstName"/></p>
</form>

<script>
d365mktformcapture.waitForElement("#form1").then(form => {
  const mappings = [
    {
      FormFieldName: "firstName",
      DataverseFieldName: "firstname",
    },
  ];

  ...
  
  const serializedForm = d365mktformcapture.serializeForm(form, mappings);
  // console.log(JSON.stringify(serializedForm)); // NOTE: enable for debugging
  const payload = serializedForm.SerializedForm.build();
});
</script>

パラメータ form は、前のセクションで説明した waitForElement 関数によって取得されます。パラメータ mappings は、次の構造の要素を含む配列です:

export interface IFormFieldMapping {
    FormFieldName?: string; // name of form field
    DataverseFieldName: string; // name of field on Dynamics 365 side
    DataverseFieldValue?: string | IFormValueMapping[]; // optional - either a fixed value or a value mapping
}

export interface IFormValueMapping {
    FormValue: string; // form field value
    DataverseValue: string; // mapped value for that form field value that will be sent to Dynamics 365
}

この関数は同期的であり、次の契約でシリアル化の結果を返します:

export interface IFormSerializationResult {
    FormFieldMappingResults: IFormFieldMappingResult[]; // Status for each of the defined mappings
    SerializedForm: IFormSerializationBuilder; // The serialized form
}

export interface IFormFieldMappingResult {
    Mapping: IFormFieldMapping; // The defined mapping
    FormFieldMappingStatus: FormFieldMappingStatus; // Status of the mapping (see below for status values)
    Message: string; // Optional - an error/warning message for the mapping
}

export enum FormFieldMappingStatus {
    Success = 0,
    NotFound = 1,
    Error = 2
}

FormFieldMappingResults によって返されたすべてのエラーを必ず処理してください。 serializedForm.SerializedForm.build() を呼び出すことで、Customer Insights - Journeys へのペイロードを作成できます。

2.1 OptionSet フィールドのマッピング

OptionSet フィールドの場合、Customer Insights - Journeys に格納するそれぞれの値へのマッピングを定義する必要があります。既存のフォーム OptionSet フィールド値を DataverseFieldValue プロパティでマッピングできます。

例:

<form id="form1">
  <p>Radio: <input type="radio" name="radioInput" value="option1"/><input type="radio" name="radioInput" value="option2"/></p>
</form>

<script>
  ...
  const mappings = [
    {
        FormFieldName: "radioInput",
        DataverseFieldName: "dvradioInput",
        DataverseFieldValue: [ 
            { FormValue: "option1", DataverseValue: "1" }, 
            { FormValue: "option2", DataverseValue: "2" },
        ]
    },
  ];
  ...
</script>

2.2 検索フィールドのマッピング

検索フィールドの既定値を設定する

ルックアップフィールドのマッピングロジックでは、静的 (既定) 値を使用できます。 Customer Insights - Journeys に格納するフィールド名と値を定義する必要があります。

例:

<form id="form1">
  ...
</form>

<script>
  ...
  const mappings = [
    {
        DataverseFieldName: "currency",
        DataverseFieldValue: "{\"Id\":\"ffffd6c1-b32d-ee11-bdf3-6045bded6105\",\"LogicalName\":\"transactioncurrency\"}"
    },
  ];
  ...
</script>

ルックアップフィールドの値をフォーム内のフィールドにマッピングする

ルックアップフィールドの値を既存のフォームフィールドのそれぞれの値にマップすることもできます。

例:

<form id="form1">
  <p>Radio: <input type="radio" name="currency" value="usd"/><input type="radio" name="currency" value="eur"/></p>
</form>

<script>
  ...
  const mappings = [
    {
        FormFieldName: "currency",
        DataverseFieldName: "transactioncurrencyid",
        DataverseFieldValue: [ 
              { FormValue: "usd", DataverseValue: "{\"Id\":\"cd2cff48-08a3-ea11-a813-000d3a0a82b4\",\"LogicalName\":\"transactioncurrency\"}", }, 
              { FormValue: "eur", DataverseValue: "{\"Id\":\"91f1a052-259c-4719-a3ae-3a1d2987a3ed\",\"LogicalName\":\"transactioncurrency\"}", }, 
        ]
    },
  ];
  ...
</script>

2.3 複数選択フィールド値のマッピング

multi-select フィールドの場合、Customer Insights - Journeys に格納するそれぞれの値へのマッピングを定義する必要があります。既存のフォームの複数選択フィールドの値を DataverseFieldValue プロパティにマップできます。

例:

  <form id="form1">
    <p>Fieldset: <fieldset name="multiOptionInput">
      <input type="checkbox" name="multiOptionInput" value="100000000">0</input>
      <input type="checkbox" name="multiOptionInput" value="100000001">1</input>
      <input type="checkbox" name="multiOptionInput" value="100000002">2</input>
    </fieldset></p>
  </form>
 
<script>
...
const mappings = [
  {
    FormFieldName: "multiOptionInput",
    DataverseFieldName: "dvmultiOptionInput",
    DataverseFieldValue: [
      { FormValue: "100000000", DataverseValue: "0" },
      { FormValue: "100000001", DataverseValue: "1" },
      { FormValue: "100000002", DataverseValue: "2" },
    ]
  },
];
...
</script>

同意フィールドは、Customer Insights - Journeys のフォームエディターで設定する必要があります。 DataverseFieldName と DataverseFieldValue のマッピングは必要に応じて自動生成されます。

例:

<form id="form1">
  <p>Consent: <input type="checkbox" name="consentField"/></p>
</form>

<script>
  ...
  const mappings = [
    {
        FormFieldName: "consentField",
        DataverseFieldName: "msdynmkt_purposeid;channels;optinwhenchecked",
        DataverseFieldValue: "10000000-0000-0000-0000-000000000004;Email;true",
    },
  ];
  ...
</script>

4. フォーム送信を Customer Insights - Journeys に送信する

フォームへの参照を取得し、マッピングを定義し、フォームをシリアル化したら、イベントリスナーを submit イベントに追加し、d365mktformcapture.submitForm(captureConfig, payload) 関数を使用して送信できます。この呼び出しは Promise を返し、エラーは catch ロジックで処理できます。

重要

カスタム検証またはキャプチャチェックを実施している場合は、検証が成功した場合にのみフォームを Customer Insights - Journeys に送信します (たとえば、submit イベントで isDefaultPrevented をチェックするか、または検証に合格後にのみ submitForm を明示的に呼び出します)

例:

<form id="form1">
  <p>FirstName: <input type="text" name="firstName"/></p>
</form>

<script>
d365mktformcapture.waitForElement("#form1").then(form => {
  const mappings = [
    {
      FormFieldName: "firstName",
      DataverseFieldName: "firstname",
    },
  ];

  form.addEventListener("submit", (e) => {
    const serializedForm = d365mktformcapture.serializeForm(form, mappings);
    // console.log(JSON.stringify(serializedForm)); // NOTE: enable for debugging
    const payload = serializedForm.SerializedForm.build();

    const captureConfig = {
      FormId: "...", // the form id on Dynamics 365 side
      FormApiUrl: "..." // the API url of the Dynamics 365 backend service where the form will be submitted to
    }
    d365mktformcapture.submitForm(captureConfig, payload)
    .catch(e => {
      // error handling
    });
  }, true);
});
</script>

トラブルシューティング

送信エンドポイントへの呼び出しが CORS エラーで失敗する

クロスオリジンリソース共有 (CORS) により、フォーム送信のキャプチャが失敗する場合があります。外部フォームホストのドメインを有効にします。ドメイン認証の詳細について説明します。

フォームエディターでそれぞれの同意フィールドを設定し ( Customer Insights - Journeys フォームエディターでフォームキャプチャを作成するのセクションを参照)、公開プロセスで生成される正しいマッピングを使用していることを確認してください。

次の方法で共有

Customer Insights - Journeys でフォームをキャプチャする

フォームキャプチャを有効にする

フォームキャプチャの仕組み

ステップバイステップでフォームをキャプチャする

Customer Insights - Journeys フォームエディターでフォームキャプチャを作成する

キャプチャスクリプトをページとマッピング定義に埋め込む

1. フォーム要素への参照を取得する

2. フォームフィールドのマッピングを定義する

2.1 OptionSet フィールドのマッピング

2.2 検索フィールドのマッピング

検索フィールドの既定値を設定する

ルックアップフィールドの値をフォーム内のフィールドにマッピングする

2.3 複数選択フィールド値のマッピング

4. フォーム送信を Customer Insights - Journeys に送信する

トラブルシューティング

送信エンドポイントへの呼び出しが CORS エラーで失敗する

その他のリソース

次の方法で共有

Customer Insights - Journeys でフォームをキャプチャする

フォーム キャプチャを有効にする

フォーム キャプチャの仕組み

ステップバイステップでフォームをキャプチャする

Customer Insights - Journeys フォーム エディターでフォーム キャプチャを作成する

キャプチャ スクリプトをページとマッピング定義に埋め込む

1. フォーム要素への参照を取得する

2. フォーム フィールドのマッピングを定義する

2.1 OptionSet フィールドのマッピング

2.2 検索フィールドのマッピング

検索フィールドの既定値を設定する

ルックアップ フィールドの値をフォーム内のフィールドにマッピングする

2.3 複数選択フィールド値のマッピング

3. 同意フィールドのマッピングを定義する

4. フォーム送信を Customer Insights - Journeys に送信する

トラブルシューティング

送信エンドポイントへの呼び出しが CORS エラーで失敗する

同意値が正しく更新されない

その他のリソース

フォームキャプチャを有効にする

フォームキャプチャの仕組み

Customer Insights - Journeys フォームエディターでフォームキャプチャを作成する

キャプチャスクリプトをページとマッピング定義に埋め込む

2. フォームフィールドのマッピングを定義する

ルックアップフィールドの値をフォーム内のフィールドにマッピングする