Bagikan melalui

Mengambil formulir di Customer Insights - Journeys

  • Artikel

Pengambilan formulir digunakan untuk mendapatkan tanggapan dari formulir yang ada yang tidak dibuat menggunakan editor formulir Customer Insights - Journeys . Pengambilan formulir disarankan jika formulir yang ada juga mengirim tanggapan ke sistem selain Dynamics 365 atau jika formulir yang ada berisi logika kompleks yang tidak dapat dibuat ulang dengan mudah di editor formulir Customer Insights - Journeys . Jika formulir yang ada dapat dibuat ulang menggunakan Customer Insights - Journeys editor formulir, tidak disarankan untuk menggunakan fitur pengambilan formulir.

Pengambilan formulir menggunakan API yang sama dengan formulir standar untuk memproses pengiriman. Pemberitahuan keamanan yang sama berlaku untuk pengambilan formulir.

Penting

Pengambilan formulir memerlukan bantuan pengembang. Selalu lebih mudah untuk membuat formulir menggunakan editor formulir Customer Insights - Journeys dan menyematkannya ke halaman Anda yang sudah ada.

Penting

Pengambilan formulir memerlukan solusi DynamicsMKT_Forms versi 1.1.35355 atau lebih tinggi. Saat menyediakan instans uji coba, Anda tidak akan selalu memiliki versi terbaru secara otomatis. Pastikan Anda telah memperbarui Customer Insights - Journeys sebelum mencoba mengambil formulir.

Aktifkan pengambilan formulir

Fitur pengambilan formulir dinonaktifkan secara default. Anda dapat mengaktifkan sakelar Pengambilan formulir di Fitur Pengaturan>mengalihkan>Formulir.

Aktifkan pengambilan formulir di sakelar fitur.

Cara kerja pengambilan formulir

Pengambilan formulir meniru pengiriman formulir standar Customer Insights - Journeys . Untuk menautkan tanggapan formulir Customer Insights - Journeys yang ada, Anda perlu membuat formulir menggunakan editor formulir Customer Insights - Journeys . Setelah Anda menerbitkan formulir itu, Anda bisa mendapatkan skrip pengambilan formulir, yang perlu disematkan ke halaman web yang berisi formulir Anda yang ada. Skrip mencakup definisi bidang formulir yang ada yang memetakan atribut entitas prospek atau kontak. Anda dapat melihat semua tanggapan dan analitik di dalamnya Customer Insights - Journeys. Anda juga dapat menggunakan formulir ini dalam orkestrasi perjalanan dengan pemicu Formulir Pemasaran yang Dikirimkan . Pengiriman formulir ini juga dapat membuat atau memperbarui Persetujuan Titik Kontak dan Tujuan atau Topik terkait.

Panduan langkah demi langkah mengambil formulir

Membuat pengambilan formulir di editor formulir Customer Insights - Journeys

  1. Untuk membuat skrip formulir pengambilan baru, buka Customer Insights - Journeys>Formulir Saluran> dan pilih Baru di bilah perintah.

  2. Beri nama formulir dan pilih audiens yang tepat. Pilihan audiens target itu penting. Pemetaan atribut bidang> skrip pengambilan formulir hanya tersedia untuk atribut audiens target yang dipilih (entitas).

  3. Tambahkan semua bidang yang ingin Anda petakan ke bidang formulir yang sudah ada. Langkah ini tidak wajib; Pemetaan atribut > bidang didefinisikan dalam kode pengambilan formulir. Menambahkan bidang yang tepat ke dalam formulir menghasilkan placeholder untuk pemetaan atribut dalam skrip pengambilan formulir membuat definisi pemetaan lebih mudah.

  4. Tambahkan elemen persetujuan seperti Tujuan atau topik untuk membentuk dan mengonfigurasinya. Pelajari lebih lanjut cara mengelola izin untuk email dan SMS Customer Insights - Journeys.

    Penting

    Definisi persetujuan harus dilakukan di editor formulir. Perubahan yang dilakukan pada setelan persetujuan yang dilakukan dalam pengambilan formulir cuplikan kode akan diabaikan.

  5. Tambahkan tombol Kirim . Tombol kirim diperlukan untuk validasi formulir yang berhasil sebelum dipublikasikan.

  6. Terbitkan formulir menggunakan tombol Terbitkan di sudut kanan atas layar. Salin pengambilan formulir cuplikan kode dan sematkan cuplikan kode ke halaman web Anda dengan formulir yang ada atau serahkan cuplikan kode kepada pengembang Anda. Cuplikan kode sudah menyertakan tautan ke dokumentasi untuk memandu pengembang Anda.

    Tambahkan elemen persetujuan ke formulir.

    Penting

    Nama domain tempat formulir Anda yang ada dihosting harus diaktifkan untuk hosting formulir eksternal, jika tidak, pengiriman formulir tidak akan ditangkap. Pelajari autentikasi domain lebih lanjut.

Menyematkan skrip pengambilan ke halaman Anda dan definisi pemetaan

Cuplikan kode yang disalin pada langkah sebelumnya adalah template dan harus disesuaikan dengan kasus penggunaan tertentu. Anda perlu mengganti semua elemen yang ditandai seperti ***Please fill*** pada template yang dihasilkan dan menyesuaikan logika dengan skenario Anda.

Pengiriman formulir Anda yang ada dikirim menggunakan Customer Insights - Journeys API JavaScript, yang ditentukan dalam file FormCapture.bundle.js dan disertakan dalam cuplikan.

Pengaturan pengambilan formulir terdiri dari langkah-langkah berikut:

  1. Dapatkan referensi ke elemen formulir di halaman.
  2. Tentukan pemetaan bidang formulir pada bidang (atribut entitas) di Customer Insights - Journeys.
  3. Tentukan pemetaan bidang persetujuan pada model persetujuan di Customer Insights - Journeys.
  4. Kirim tanggapan formulir ke Customer Insights - Journeys.

1. Dapatkan referensi ke elemen form

Untuk mendapatkan referensi ke elemen form, Anda dapat menggunakan waitForElement fungsi helper. Ini juga berfungsi dengan elemen yang dirender secara dinamis dan mengembalikan janji yang diselesaikan setelah elemen dengan pemilih yang diberikan ditemukan di halaman. Untuk referensi CSS penyeleksi, lihat dokumentasi ini.

Contoh:

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

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

2. Tentukan pemetaan bidang formulir

Bidang dalam formulir perlu dipetakan ke bidang masing-masing (atribut entitas) di Customer Insights - Journeys. Pemetaan didefinisikan dalam fungsi d365mktformcapture.serializeForm(form, mappings).

Contoh:

<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>

Parameter form diambil oleh fungsi yang waitForElement dijelaskan di bagian sebelumnya. Parameternya mappings adalah array dengan elemen-elemen dari struktur berikut:

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
}

Fungsi ini sinkron dan mengembalikan hasil serialisasi dengan kontrak berikut:

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
}

Pastikan Anda menangani semua kesalahan yang FormFieldMappingResults dikembalikan oleh. Anda dapat membuat payload dengan Customer Insights - Journeys menelepon serializedForm.SerializedForm.build().

2.1 Pemetaan bidang OptionSet

Untuk OptionSet bidang, Anda perlu menentukan pemetaan ke nilai masing-masing yang harus disimpan Customer Insights - Journeys. Anda dapat memetakan nilai bidang OptionSet formulir yang ada di DataverseFieldValue properti.

Contoh:

<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 Pemetaan bidang pencarian
Mengatur nilai default untuk bidang pencarian

Anda dapat menggunakan nilai statis (default) dalam logika pemetaan untuk bidang pencarian. Anda perlu menentukan nama bidang dan nilai yang harus disimpan Customer Insights - Journeys.

Contoh:

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

<script>
  ...
  const mappings = [
    {
        DataverseFieldName: "currency",
        DataverseFieldValue: "{\"Id\":\"ffffd6c1-b32d-ee11-bdf3-6045bded6105\",\"LogicalName\":\"transactioncurrency\"}"
    },
  ];
  ...
</script>
Memetakan nilai bidang pencarian ke bidang di formulir Anda

Anda juga bisa memetakan nilai bidang pencarian ke nilai masing-masing di bidang formulir Anda yang sudah ada.

Contoh:

<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 Memetakan nilai bidang multi-pilih

Untuk multi-select bidang, Anda perlu menentukan pemetaan ke nilai masing-masing yang harus disimpan Customer Insights - Journeys. Anda dapat memetakan nilai bidang multi-pilih formulir yang ada di DataverseFieldValue properti.

Contoh:

  <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>

Bidang persetujuan harus dikonfigurasi di editor formulir in Customer Insights - Journeys. Pemetaan DataverseFieldName dan DataverseFieldValue dibuat secara otomatis sesuai.

Contoh:

<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. Kirim pengiriman formulir ke Customer Insights - Journeys

Setelah Anda mendapatkan referensi ke formulir, menentukan pemetaan, dan membuat serial formulir, Anda dapat menambahkan event listener ke submit event dan mengirimkannya menggunakan d365mktformcapture.submitForm(captureConfig, payload) fungsi. Panggilan ini mengembalikan janji, dan kesalahan dapat ditangani dalam catch logika.

Penting

Jika Anda memiliki validasi khusus atau pemeriksaan Captcha, pastikan Anda mengirimkan formulir hanya jika Customer Insights - Journeys validasi berhasil (misalnya, periksa isDefaultPrevented acara atau submit panggil submitForm secara eksplisit hanya setelah validasi lolos)

Contoh:

<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>

Mengatasi Masalah

Panggilan ke titik akhir pengiriman gagal dengan kesalahan CORS

Cross-Origin Resource Sharing (CORS) dapat menyebabkan pengiriman formulir gagal. Aktifkan domain Anda untuk hosting formulir eksternal. Pelajari autentikasi domain lebih lanjut.

Pastikan Anda telah menyiapkan bidang persetujuan masing-masing di editor formulir (lihat Membuat pengambilan formulir di Customer Insights - Journeys editor formulir) dan telah menggunakan pemetaan yang benar yang dihasilkan dalam proses penerbitan.