EasySend Web SDK

SDK for creating and working with EasySend API.

Usage

Basic setup:

• Creating player handler:

  import core from "easysend-sdk/essdk";
  const esPlayer = await core.getPlayer("http://example.easysend.app")

  Player handler is used for creating form handlers. It represents a single EasySend player instance.
• Creating form handler:
  • By form id:

    const esForm = esPlayer.getForm("form_id", "customer_id")

  • By form URL from generate_link API call:

    const esForm = esPlayer.useGeneratedLink("url_from_generate_link_api")

  Form handler is used for working with a single form. It represents a single EasySend form and helps user to manage it.

Working with EasySend form:

• Preload: Form has multiple ways of preloading it's content. Most suitable will be chosen.

  await esForm.preload()

  • Open: We can open a form in an iframe. Also it allows user to set form dimensions.

       const iframeManager = esForm.createIframe();
       iframeManager.onLoad(() => {
          // ON LOAD CALLBACK IF NEEDED 
       });
       iframeManager.showInContainer(
         preloadDiv[0], width, height
       );

    IMPORTANT: Each call to createIframe creates a new iframe manager instance. And this way we can create multiple iframes of the same form/process.

    IMPORTANT: Don't forget to release iframe manager when you don't need it anymore:

    IMPORTANT: Only one form instance is allowed inside one container. The old form will be hidden if a new form is opened in the same container.

• Open in tab: We can open a form in a new tab by simply calling

  await esForm.openInTab()

• Listen for form events (see Form events for more info):

  const eventListener = esForm.createEventsListener()

Form events

Form events are used for listening to form events.

• prevPage: Called when user navigates to the previous form step
• nextPage: Called when user navigates to the next form step
• uploadSuccess: Called when form is submitted.
• uploadFailed: Called when form has failed to submit.

Don't forget to release manager when you don't need it anymore:

eventListener.release()

Event listener listens for a form events based on the sending form URL. So it's important to use the same form URL for creating event listener as for opening the form. Also, it's important to create event listener before opening the form.'

Usage example

  let events = null;
  
  ////////////////////////////
  // STEP 1: Create player  //
  ////////////////////////////
  const getEsPlayer = async () => { // create player handler
    return await EasySend.default.getPlayer($("#domain").val());
  }

  //////////////////////////////////
  // STEP 2.A: Create form handler  //
  //////////////////////////////////
  const getEsForm = async () => {
    return (await getEsPlayer()).getForm(
      $("#form_id").val(), $("#customer").val()
    );
  }

  //////////////////////////////////////////////
  // STEP 2.B (ALTERNATIVE): Create form pregenerated link  //
  //////////////////////////////////////////////
  const getEsFormPregen = async () => {
    return (await getEsPlayer()).useGeneratedLink(
      "<generated-link for the form provided by the backend>"
    );
  }
  
  //////////////////////////////////////
  // STEP 3: Open form inside iframe  //
  //////////////////////////////////////
  const openFormInIFrame = (esForm) => {
    const preloadDiv = $("#preload_demo"); // div for iframe
    iframeManager = esForm.createIframe();
    iframeManager.onLoad(() => {
      const duration = performance.now() - startTime;
      logDuration("open iframe:", duration);
    });
    iframeManager.showInContainer(
      preloadDiv[0], $("#preload_width").val(), $("#preload_height").val()
    );

    if (iframeManager) {
      iframeManager.release();
      iframeManager = null;
    }
  
    events = esForm.createEventsListener() // create new event listener
    events.onFormSubmittedListener = () => { // set form submitted listener
      logEvent("event:", "success");
    }
    events.onFormFailedListener = () => { // set form failed listener
      logEvent("event:", "failed");
    }
  }

  $("#open_iframe").click(async () => {
    const esForm = await getEsForm();
    openFormInIFrame(esForm);
  });
  
  //////////////////////////////////////
  // Preload form to invisible iframe //
  //////////////////////////////////////
  $("#preload").click(async () => {
    const esForm = await getEsForm();
    await esForm.preload(); // preload form and cache static resources
  });

  ////////////////////////////
  // Open form inside a tab //
  ////////////////////////////
  $("#open").click(async () => {
    const esForm = await getEsForm();
    esForm.openInTab();
  });

Generate documentation

Documentation can be generated into the doc folder:

npm run docs

Testing

For running unit tests:

npm run test

For testing webpack-generated code manually:

npm run serve

This project uses Google's TypeScript style guide.

Building

Run a build command and examine a dist folder for generated bundle

npm run build

For dev build run:

npm run build:dev