easysend-sdk v0.1.0

EasySend Web SDK

SDK for creating and working with EasySend API.

Usage

Basic setup:

• Creating player handler:

  const esPlayer = await EasySend.default.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 a separate window by simply calling

  await esForm.open()

  Also it allows user to set form dimensions.
• 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
    preloadDiv.empty();
    const iframe = esForm.open( // open form in iframe inside div
      preloadDiv[0], $("#preload_width").val(), $("#preload_height").val()
    );
  
    if (events) { // release previous event listener
      events.release()
      events = 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