Elastic signing event callbacks

When developing for elastic signing, you may need to handle various events generated by your users interacting with elastic templates. You can modify your web application to react to these events by implementing the callback methods described in this topic.

The callbacks provided in this guide are all client-side functions that are automatically called when their associated events occur, if you have implemented them. For example, if you define a method with the name onAgreed, that method will be called each time a user has completed an elastic template agreement. The logic within each callback method will be defined by you for your app’s individual requirements.

Because the callbacks are client-side, you must use JavaScript that runs in the browser to handle the triggering events. The Docusign Click SDKs cannot be used for this purpose because they provide only server-side code that is used to manage the elastic templates. Similarly, Webhooks cannot be used with Docusign Click client-side events, because these events are handled on the client side and will not be reported by Docusign Connect.

Types of elastic signing event callbacks

The example to the right shows JavaScript code for handling all six event callbacks. You do not have to implement all of them, and you can add your own code as needed.

A single event can trigger more than one callback. For example, when a user accepts an elastic signing agreement, both of these callbacks are triggered:

• onAgreeing: triggered when the user accepts the agreement
• onAgreed: triggered when the agreement has been stored with the Docusign platform

If your logic implements multiple functions that the same event can trigger, the logic should take that into account so that it doesn’t duplicate processing.

onMustAgree

This function is called just before a user is presented with an agreement (in the elastic template UI) that they are required to complete. This event will only fire if the user has not previously agreed to this elastic template or if there is a new required version of the elastic template available since they last agreed.

onAgreed

This function is called directly after a user agrees to an elastic template agreement, either explicitly or because they were presented an elastic template agreement to which they had previously agreed. This event is only generated after the user has finished interacting with the elastic template and the agreement has been successfully stored with the Docusign platform (this may take a few additional seconds). If you want to handle the user’s interaction directly, use the onAgreeing event instead.

onDeclined

This function is called when the user explicitly declines a elastic template agreement that was presented to them. This event is only generated after the user has finished interacting with the elastic template and the record of their declining the agreement has been successfully stored with the Docusign platform (this may take a few additional seconds). If you want to handle the user’s interaction directly, use the onDeclining event instead.

onError

This function is called whenever an error occurs in the agreement process. For example, if the user lost internet connectivity before the agreement was successfully stored on the Docusign platform, an error would occur and this method would be called. This method is not called as a result of configuration errors such as using the wrong accountId or clickwrapId.

onAgreeing

This function is called directly after a user agrees to a elastic template agreement explicitly by selecting AGREE (the button text can be customized when you create the elastic template). The triggering event is fired immediately, without waiting for the agreement to be stored on the Docusign platform. It will always be fired before the onAgreed event.

onDeclining

This function is called when the user explicitly declines the elastic template agreement that was presented to them. Unlike onDeclined, the triggering event for onDeclining is fired immediately, without waiting for the declination to be stored with the Docusign platform. This method will always execute before onDeclined.

let mustAgree = false;
docuSignClick.Clickwrap.render({
    environment: 'https://demo.docusign.net',
    accountId: '38a6e44d-xxxx-xxxx-xxxx-b4d04faa1618',
    clickwrapId: 'c2169dc1-xxxx-xxxx-xxxx-b61754677f63',
    // Called when the user will be presented with an agreement
    onMustAgree: function (agreementData) {
        // Set a local variable if needing to distinguish new agreements
        mustAgree = true;
    },
    // Called immediately upon user clicking ‘Agree’
    // Any calls to download will not work until onAgreed has been called
    onAgreeing: function (agreementData) {},
    // Called when the user has previously agreed OR has just successfully completed the agreement AND response has been successfully stored
    onAgreed: function (agreementData) {
      if (mustAgree) {
         // Custom logic for ‘new’ agreements
      }
    },
    // Called immediately upon user clicking ‘Decline’
    onDeclining: function (agreementData) {},
    // Called when a user declines and a response has been successfully stored (if Record Decline Responses is enabled)
    onDeclined: function (agreementData) {},
    // Called if any errors occur during agreement or configuration
    onError: function (error) {}
}, ‘#ds-terms-of-service’)