Embedded web forms methods and events
OneTrust embedded web forms are created and built within the OneTrust application and deployed directly onto your website. The following sections provide details on methods for implementing the embedded web form and available integration events.
Implementing embedded web forms
OneTrust embedded web forms are simply implemented by including the form SDK in the <head> of your website. Once you have finished creating and building the embedded web form in the OneTrust Universal Consent & Preference Management module, you can copy the integration script from the Integrations tab of the Collection point details screen for the embedded web form and integrate it on your website.
For more information, see Integrating OneTrust Embedded Web Form Collection Points.
When configuring the integration of your embedded web form, you can select whether to load the web form via a Manual or Instant method. If you select to use the Instant method, the web form will appear immediately on the page load of the website. Alternatively, if you select to use the Manual method, you can control exactly when the embedded web form should be seen by your users. However, in order to use the Manual method, you will need to use the InstallCP method on your website to force the web form to load.
InstallCP to manually load embedded web forms
InstallCP to manually load embedded web formsThis method must be used to install the collection point to the web form via an ad hoc method that can be called at any time.
Note: callback function is optional and returns a response of true or false.
OneTrust.webform.InstallCP("collection point id", function() {
// Callback function code goes here
// This function will be called after the collection point is installed
});
OtSdk('consent','InstallCP','collection point id', function() {
// Callback function code goes here
// This function will be called after the collection point is installed
});
Events
When the embedded web form is on your website, you will have the ability to customize behavior based on certain events happening on the web form. The following events are available:
Form loaded
Use the OnetrustFormLoadedevent to know that the web form has successfully loaded on the web page. The response includes the status of each collection point that is loaded successfully.
<script>
window.addEventListener('OnetrustFormLoaded', (event) => {
// value can be accessed here
console.log('OnetrustFormLoaded event triggered', event.detail);
});
</script>
{
"c4c93b24-653c-4e32-9082-12a908051700": true,
}
Form submitted
Use the OneTrustWebFormSubmitted event to know that the web form has been submitted. The response includes the details of the request payload which is used to create a consent receipt.
<script>
window.addEventListener('OneTrustWebFormSubmitted', (event) => {
// value can be accessed here
console.log('OneTrustWebFormSubmitted event triggered', event.detail);
});
</script>
{
"requestInformation": "token string",
"identifier": "[email protected]",
"test": false,
"language": "en-us",
"purposes": [
{
"Id": "6ce23e91-4105-48c8-b7b1-5e4db3cb0fa6",
"CustomPreferences": [
{
"Id": "96ddf2ff-5fc0-41d8-9d0f-d6b8343a9a6c",
"Options": [
"0ce72d65-e52f-4a49-9ea3-08ce23044b9e"
]
},
{
"Id": "c6ce3e45-ca31-4fc7-be8f-6f59ff69f3fe",
"Options": [
"83ebaf8b-35dc-42bf-9f5a-59746d5a1931"
]
}
]
}
],
"dsDataElements": {
"Email": "[email protected]"
}
}
Methods
When the embedded web form is on your website, the following methods can be used to perform specific actions:
OneTrust.webform.TriggerReceiptAction()
OneTrust.webform.TriggerReceiptAction()Use the OneTrust.webform.TriggerReceiptAction() method to create consent receipts and quickly view the related transactions in the application.
OneTrust.webform.TriggerReceiptAction({
cpId:'${collection point id}', // mandatory
receiptApiEndpoint:'${API url}', // mandatory
identifier:'${identifier}', // mandatory
token:'${jwt token string}', // mandatory
purposes:[], // optional
dsDataElements:{}, // optional,
customElements:{}, // optional
downloadRawReceipt: true, // optional
useBeacon: true, // optional
language: '${lang code}' // optional
})
Purpose structure:
{
Id: '${purpose id}]', // mandatory
TransactionType:'' // optional [NO_CHOICE, NOTGIVEN, OPT_OUT, NO_OPT_OUT]
}
OneTrust.webform.prefill()
OneTrust.webform.prefill()Use the OneTrust.webform.prefill({"fieldLabel":"fieldValue"}, "collection point id")method to fill out fields on behalf of the end-user. This helps to:
- Reduce end-user fatigue by pre-filling values and choices that have already been expressed, or are already known by the business.
- Use internal user-unfriendly identifiers such as CRM IDs or hashed emails as identifiers for your embedded web forms, hiding them from view.
Functional documentation on pre-filling and hiding fields
Field labels are the form field labels set on your web form for the default language. They are translation-independent, so that no matter the display language of your web form, the same label can be used for pre-filling fields.
Recommended configuration
When fields should be pre-filled as soon as the web form is loaded, we recommend using the command queue to let the pre-fill command execute as soon as the web form is ready.
OtSdk("consent", "preFill", {
"Email": "[email protected]",
"Use of personal data": "Checked",
"Brands of interest": ["Brand 1", "Brand 2"],
"Date of birth": "1995-09-19",
"Country": "IN"
}, "collection point id");
Pre-filling values
Phone number fields are not yet supported
// Pre-fill free text by passing the the content as is
OneTrust.webform.preFill({
"Email": "[email protected]",
"Free text input": "free text content"
}, "collection point id")
// Pre-fill purposes by passing the purpose label and the strings "Checked" or "Unchecked"
OneTrust.webform.preFill({
"Marketing communications": "Checked",
"Product newsletters": "Unchecked"
}, "collection point id")
// Pre-fill date fields by passing the date in ISO 8601 format YYYY-MM-DD or YYYY/MM/DD
OneTrust.webform.preFill({
"Date of birth": "1995/09/19",
"Moving date": "2022/09/19"
}, "collection point id")
// Pre-fill phone numbers by passing an object containing the country code and number separately.
OneTrust.webform.preFill({
"{builderPhoneLabel}":{
"Country code": '+91', // This will always be the same no matter the label
"Number": '4894646' // This will always be the same no matter the label
}
}, "collection point id")
Pre-filling selections
// Pre-fill country and state fields by passing country and state codes
OneTrust.webform.preFill({
"Country": "US",
"State": "FL"
}, "collection point id")
// Pre-fill multi-select fields by passing an array of options
// This applies to selection data elements and purpose preferences
OneTrust.webform.preFill({
"Multi-select field": ["Option 1", "Option 2"]
}, "collection point id")
// Pre-fill multi-select fields by passing the option as a string or as an array
// If multiple options are passed in an array, the first one will be applied
// This applies to selection data elements and purpose preferences
OneTrust.webform.preFill({
"Single-select field": ["Option 1"],
"Other single-select field": "Option 2"
}, "collection point id")
Updated 5 months ago