TrustedFormNext Function

Feature Snapshot

Summary:
TrustedFormNext is a global function injected by the TrustedForm Certify SDK that generates a new certificate on the fly without requiring a reload of the SDK. It is a key part of Certify for Offer Paths, often used in “coreg” (coregistration) scenarios where multiple buyer offers are shown in a single session and each buyer needs their own certificate.

Key Benefits:

• Generates a separate TrustedForm certificate per buyer’s offer in a single path / coreg flow
• Ensures each buyer sees only the offer information that pertains to them
• Supports one-to-one consent compliance by tying consent to an individual certificate
• Helps protect consumer privacy by reducing the risk of sharing unrelated offer data with the wrong buyer

Typical Use Cases:

• “Coreg” / co-registration pages with multiple offers selected in one session
• Single-path application flows where each buyer must receive their own TrustedForm certificate
• Flows where you need to break one session into multiple certificates without reloading the page or SDK

How the TrustedFormNext Function works

trustedFormNext is exposed on the global window object after the TrustedForm Certify SDK has loaded.

• The first certificate is created using the parameters passed to the original TrustedForm <script> tag (e.g., field, ping_field, token, identifier).
• When you call trustedFormNext(options, cbReady) or trustedFormNext(options).then(...), TrustedForm:
  • Creates a new certificate using:
    • Any new values you pass in options, and
    • Any original values for options you don’t override
  • Updates the injected hidden fields on the page with the values for the new certificate

⚠️ Important timing note:
Between the call to trustedFormNext and the callback or promise resolution, no DOM mutations or user interactions should occur. Any changes to the page or user actions during this period can cause errors in recording either the current or the “next” certificate.

The function returns a response object via callback or promise with:

• cert_id / id – Certificate ID
• token – Full certificate URL
• ping_url – Ping URL
• external_id – The identifier value associated with this certificate

1. Load the TrustedForm Certify SDK and Create the First Certificate

Include the TrustedForm Certify script on your page as you normally would. This will generate the first certificate and set up the baseline configuration (field, ping_field, identifier, etc.).

Example (first certificate):

<!-- TrustedForm -->
<script type="text/javascript">
(function() {
  var tf = document.createElement('script');
  tf.type = 'text/javascript'; tf.async = true;
  tf.src = (document.location.protocol === "https:" ? "https" : "http") +
           "://api.trustedform.com/trustedform.js" +
           "?field=offer1_cert_url" +
           "&ping_field=offer1_ping_url" +
           "&identifier=coreg_beta_test" +
           "&l=" + new Date().getTime() + Math.random();
  var s = document.getElementsByTagName('script')[0];
  s.parentNode.insertBefore(tf, s);
})();
</script>
<noscript>
  <img src="https://api.trustedform.com/ns.gif" />
</noscript>
<!-- End TrustedForm -->

Expected Result:

• A first TrustedForm certificate is created for the initial offer (e.g., offer1).
• Hidden fields such as offer1_cert_url and offer1_ping_url are injected into your form

2. Generate a New Certificate for the Next Offer with trustedFormNext

When the user proceeds to the next offer in your coreg / offer path flow, call trustedFormNext to generate a new certificate. You may:

• Provide options to change the names of the hidden fields (e.g., offer2_cert_url) and/or the identifier
• Use either a callback or a promise to handle completion

⚠️ Critical timing requirement:
Once you call trustedFormNext, you must avoid DOM updates and user input until:

• The callback (cbReady) is invoked, or
• The promise resolves

Example using a callback:

showLoading(); // e.g., display an overlay to block user interaction

var options = { field: 'offer2_cert_url' };

function tfCallback(data) {
  console.log("New certificate data:", data);
  hideLoading(); // remove overlay only after the certificate is ready
}

trustedFormNext(options, tfCallback);

Example using a promise:

showLoading();

const options = { field: 'offer2_cert_url' };

trustedFormNext(options)
  .then((data) => {
    console.log("New certificate data:", data);
    hideLoading();
  })
  .catch((error) => {
    console.error("Error generating next certificate:", error);
    hideLoading();
  });

Expected Result:

• A second TrustedForm certificate is created (e.g., for offer2)
• Hidden fields on the page are updated so that offer2_cert_url receives the new certificate URL
• You can now submit the form for that offer using its dedicated certificate

3. Handle the Response Object

Whether you use a callback or a promise, trustedFormNext returns a response object with:

• id / cert_id – ID of the new certificate
• token – The full certificate URL
• ping_url – The ping URL
• external_id – Your identifier value

Use this data to:

• Confirm the new certificate was created, and
• Ensure your form or lead handling code uses the correct certificate URL and ping URL for the current offer

Validation & Monitoring (optional)

To validate your implementation:

• Use your browser’s DevTools to:
  • Confirm the initial TrustedForm script loads correctly
  • Observe the network activity when calling trustedFormNext
• Submit test leads for multiple offers and ensure:
  • Each offer has its own distinct certificate URL
  • The correct hidden field names (offer1_cert_url, offer2_cert_url, etc.) contain the right certificate URLs
• View the resulting certificates in your TrustedForm account to verify:
  • Each offer path has a separate certificate
  • Only the relevant offer data is shown on each certificate

Best Practices

• Always wait for the TrustedForm Certify SDK to fully load before attempting to call trustedFormNext.
• Block user interaction and DOM changes (e.g., via an overlay) between the call to trustedFormNext and the callback or promise resolution.
• Use clear, offer-specific field names (e.g., offer1_cert_url, offer2_cert_url) to avoid confusion in your integration.
• Use the identifier field to logically group or label certificates (e.g., “offerA”, “offerB”) if needed for reporting.
• Carefully manage the timing of UI updates when transitioning between offers to avoid interfering with certificate recording.

Troubleshooting

Frequently Asked Questions (FAQ)

Q: What is TrustedFormNext?
A: TrustedFormNext is a global function provided by the TrustedForm Certify SDK that allows you to generate a new TrustedForm certificate within an existing user session without reloading the SDK.

Q: Why is TrustedFormNext important?
A: It streamlines the certificate creation process for coregistration and multi-offer campaigns, minimizing session interruptions and reducing errors that may arise from reinitializing the SDK.

Q: How do I use TrustedFormNext?
A: First, ensure the TrustedForm Certify SDK is loaded so that window.trustedFormNext is available. Then invoke the function (using either a callback or promise), optionally passing an options object with updated parameters. Finally, integrate the returned certificate data into your lead processing system.

Q: Can I pass custom parameters with TrustedFormNext?
A: Yes, you can pass an options object containing keys like field, ping_field, token, and identifier to customize the behavior of the new certificate generation.

Glossary