Embedded form JS API (draft)

This is a draft document, API subject to change.

Submission Events

There are two ways to be notified of embedded Paperform submissions.

1. onsubmit attribute

You can add an attribute to the div of either of the following:

• onsubmit="myGlobalFunctionName"
• data-onsubmit="myGlobalFunctionName" (legacy)

So your embed code would look something like:

<div data-paperform-id="contact-paperform" onsubmit="myGlobalFunctionName"></div>
<script>
  (function() { 
    var script = document.createElement('script'); 
    script.src = "https://paperform.co/__embed";
    document.body.appendChild(script)); 
  })()
</script>

A global function by the name you use for myGlobalFunctionName will be called when the form is submitted.

It is passed a single argument which is an object with the following structure:

{  
  submission_id: "XXXXXXXXXX",  
  total: null, // If there was a price processed  
  data: [  
    {  
      title: "My Question Title",  
      key: "xjsdjc", // Pre-fill key  
      value: "Dean" // Answer for this question for this submission 
    },  
    ...  
  ]  
}

2. Event listener

Embedded forms also emit a custom event by the name of PaperformSubmission on submission, which can be listened to on the div from the embed, or on any parent element.

Details of the submission are located in event.detail.

Event listener example

window.addEventListener('PaperformSubmission', function(e) { console.log(e) })

Page Change Events

There are two ways to be notified of embedded Paperform page changes.

In either way, the page change event is triggered for page changes in both directions:

• movement forward one page
• movement backward one page

1. onpagechange attribute

You can add an attribute to the div of either of the following:

• onpagechange="myGlobalFunctionName"
• data-onpagechange="myGlobalFunctionName" (legacy)

So your embed code would look something like:

<div data-paperform-id="contact-paperform" onpagechange="myGlobalFunctionName"></div>
<script>
  (function() { 
    var script = document.createElement('script'); 
    script.src = "https://paperform.co/__embed";
    document.body.appendChild(script)); 
  })()
</script>

A global function by the name you use for myGlobalFunctionName will be called when the page is changed in the form.

It is passed a single argument which is an object with the following structure:

{
    form_id: "form-id",
    currentPage: 1,
    totalPages: 35
}

2. Event listener

Embedded forms also emit a custom event by the name of PaperformPageChange when the page changes on the form, which can be listened to on the div from the embed, or on any parent element.

Details of the page change are located in event.detail.

Event listener example

window.addEventListener('PaperformPageChange', function(e) { console.log(e) })

How to use the PaperformSubmission Event with Google Tag Manager

No scripts are required in the form Analytics since we already push events to the parent website where the form is embedded.

1. Embed Code

The following code can be used on your website to push the submission_id, form_id and total amount to the dataLayer after the form is submitted.

Replace your-form-id with the actual form id:

<div data-paperform-id="your-form-id" onsubmit="myGlobalFunctionName"></div>

<script>
  (function() {
    var script = document.createElement('script');
    script.src = "https://paperform.co/__embed.min.js";
    document.body.appendChild(script); })()
</script>

<script>
  function myGlobalFunctionName(event) {
    // Access the submission details
    const submissionId = event.submission_id;
    const formId = event.form_id;
    const total = event.total;
    console.log(submissionId, formId, total);
    
    // Push to the dataLayer
    try{
      var dataLayer = window.dataLayer || (window.dataLayer = []);
      if (event) {
        dataLayer.push({
          'event': 'PaperformSubmission',
          'submissionId': submissionId,
          'formId': formId,
          'total': total,
        });
      }
    }catch(e){}
  }
</script>

2. User-Defined Data Layer Variables

Add three User-Defined Data Layer Variables to your GTM container to capture the values that we push to the dataLayer.

3. Add Custom Event Trigger

Add the Trigger called “PaperformSubmission - ce” with a Trigger Type of Custom Event.

• Event Name: PaperformSubmission
• This trigger fires on Event that equals PaperformSubmission

4. Add GA4 Configuration Tag

If you are currently sending data to GA4 with your GTM container, then skip this step since it is most likely already set up. Otherwise, here are the steps to add it to your GTM container:

• Add the GA4 Configuration Tag

• Tag Type: Google Analytics > Google Tag

• Tag ID: the GA4 Measurement ID

  • from GA4 Admin > Data Collection & Modification > Web Stream Details > Measurement ID

• Trigger: All Pages

5. Track conversions with a GA4 Event tag

The following tag captures conversions when your form is submitted and sends the values from the dataLayer as event parameters to GA4. Once you see the custom event in your Google Analytics (within 24 hours), you can change it to a conversion event.

• Add the GA4 - PaperformSubmission Tag

• Tag Type: Google Analytics: GA4 Event

• Tag ID: the GA4 Measurement ID

• Event Parameters

  • formID value is {{dlv - formId}}
  • submissionId value is {{dlv - submissionId}}
  • total value is {{dlv - total}}

• Trigger: PaperformSubmission - ce