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 양식 편집기를 사용하여 양식을 만들어야 합니다. 양식을 게시하면 양식 캡처 스크립트를 얻을 수 있습니다. 이 스크립트는 기존 양식이 포함된 웹 페이지에 포함해야 합니다. 스크립트에는 잠재 고객 또는 연락처 엔티티의 속성에 매핑되는 기존 양식 필드의 정의가 포함되어 있습니다. Customer Insights - Journeys에서 모든 제출물 및 분석을 볼 수 있습니다. 또한 이 양식을 여정 오케스트레이션에서 마케팅 양식 제출 트리거와 함께 사용할 수도 있습니다. 이 양식 제출은 또한 연락처 지점 동의 및 관련 목적 또는 주제를 생성하거나 업데이트할 수 있습니다.

양식 캡처 단계별 가이드

Customer Insights - Journeys 양식 편집기에서 양식 캡처 만들기

새 캡처 양식 스크립트를 만들려면 Customer Insights - Journeys>채널>양식으로 이동하여 명령줄에서 새로 만들기를 선택합니다.
양식의 이름을 지정하고 적합한 대상을 선택합니다. 대상 고객을 선택하는 것이 중요합니다. 양식 캡처 스크립트 필드->속성 매핑은 선택한 대상 고객(엔티티)의 속성에 대해서만 사용할 수 있습니다.
기존 양식 필드에 매핑하려는 모든 필드를 추가합니다. 이 단계는 필수가 아닙니다. 필드 > 특성 매핑은 양식 캡처 코드에 정의됩니다. 양식에 올바른 필드를 추가하면 양식 캡처 스크립트에서 속성 매핑을 위한 자리 표시자가 생성되어 매핑 정의를 더 쉽게 할 수 있습니다.
양식에 목적 또는 주제와 같은 동의 요소를 추가하고 구성합니다. Customer Insights - Journeys에서 이메일 및 문자 메시지에 대한 동의를 관리하는 방법에 대해 자세히 알아보십시오.

중요

동의 정의는 양식 편집기에서 수행해야 합니다. 양식 캡처 코드 조각에서 동의 설정에 대한 변경 사항은 무시됩니다.
제출 버튼을 추가합니다. 게시하기 전에 양식을 성공적으로 유효성 검사하려면 제출 버튼이 필요합니다.
화면 오른쪽 상단에 있는 게시 버튼을 사용하여 양식을 게시합니다. 양식 캡처 코드 조각을 복사하여 기존 양식이 있는 웹 페이지에 코드 조각을 삽입하거나 개발자에게 코드 조각을 전달합니다. 코드 조각에는 개발자를 안내하는 문서 링크가 이미 포함되어 있습니다.

중요

기존 양식이 호스팅되는 도메인 이름이 외부 양식 호스팅을 위해 활성화되어 있어야 합니다. 그렇지 않으면 양식 제출이 캡처되지 않습니다. 도메인 인증에 대해 자세히 알아보세요.

페이지에 캡처 스크립트 포함 및 매핑 정의하기

이전 단계에서 복사한 코드 조각은 템플릿이므로 특정 사용 사례에 맞게 조정해야 합니다. 생성된 템플릿에서 ***Please fill***로 표시된 모든 요소를 교체하고 시나리오에 맞게 논리를 조정해야 합니다.

기존 양식 제출은 FormCapture.bundle.js 파일에 정의되고 코드 조각에 포함된 JavaScript API를 사용하여 Customer Insights - Journeys로 전송됩니다.

양식 캡처 설정은 다음 단계로 구성됩니다.

페이지의 양식 요소에 대한 참조를 가져옵니다.
Customer Insights - Journeys에서 필드(엔티티 속성)에 대한 양식 필드의 매핑을 정의합니다.
Customer Insights - Journeys에서 동의 모델에 대한 동의 필드의 매핑을 정의합니다.
양식 제출을 Customer Insights - Journeys로 보냅니다.

1. 양식 요소에 대한 참조를 가져오기

양식 요소에 대한 참조를 얻으려면 waitForElement 도우미 함수를 사용할 수 있습니다. 이 함수는 동적으로 렌더링되는 요소에서도 작동하고 페이지에서 지정된 선택기가 있는 요소가 발견되면 해결되는 프로미스를 반환합니다. 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) 함수를 사용하여 전송할 수 있습니다. 이 호출은 프로미스를 반환하고 오류는 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 오류와 함께 실패합니다.

동의 값이 올바르게 업데이트되지 않습니다.

추가 리소스