Event Listeners

Accounting Data as a Service™ Connect triggers events according to authentication responses or different UI steps that are presented to the end user. These events can be listened to by using JavaScript callback functions and can be useful tools for tracing purposes as well as controlling the user experience.

To have the Event Listener enabled in your application, you need to make sure that you have the following parameters added to your Connect script in your application:

<!-- Insert this div where you want Connect to be initialized -->
<div id="railz-connect"></div>


<!-- Start of Railz Connect script -->
<script src="https://cdn.jsdelivr.net/npm/@railzai/railz-connect@latest/dist/railz-connect.js"></script>
<script>
  var widget = new RailzConnect();
  widget.mount({
    parentElement: document.getElementById('railz-connect'),
    widgetId: widgetId,

    // Event Listeners   
    onExit: (event, data) => {
    	/**Your code here*/
    },
    onSuccess: (event, data) => {
      /**Your code here*/
    },
    onError: (event, data) => {
      /**Your code here*/
    }
  });
</script>
<!-- End of Connect script -->

onSuccess

Load

The event is called when Connect is initialized and loaded in your application. It sends a load event with the following data as a payload.

Parameter	Type	Description
`businessName`	string	Displayed once Connects has loaded. The unique identifier of the business as defined by you or generated by us.
`metadata`	array	Displayed once Connect has loaded. The `metadata` provided by you.

{
  businessName: "Test",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ]
}

Authorization

The event is called when a user successfully connects to a service provider. It sends an authorization event with the following data as a payload.

Parameter	Type	Description
`businessName`	string	Displayed once Connects has loaded. The unique identifier of the business as defined by you or generated by Accounting Data as a Service™.
`metadata`	array	Displayed once Connect has loaded. The `metadata` provided by you.
`serviceName`	string	The service name the user connected to a business, e.g. `quickbooks`

{
  businessName: "Test",
  serviceName: "quickbooks",
  connectionUuid: "UUID-string",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ]
}

onExit

This event is called when a user exits Connect regardless of connection success or failure. It sends an exit event with the following data as a payload.

Parameter	Type	Description
`businessName`	string	Displayed once Connect has loaded. The unique identifier of the business as defined by you or generated by Accounting Data as a Service™.

{
  businessName: "Test"
}

onError

This event is called when an error occurs during the connection flow. It sends an error object within each event's payload. Error events are triggered when:

A connection was not successful.
Generic Connect errors.
Timed-out.

Parameter	Type	Description
`error`	object	An error object that contains the `errorCode` and `errorMessage`of the error that was last encountered by the user.
`error.errorCode`	string	The error code and error type that the user encountered.
`error.errorMessage`	string	A developer-friendly representation of the error code.

Load

{
  businessName: "Railz Test",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ],
  error: {
    errorCode: "timeout",
    errorMessage: "Request has timedout."
  }
}

Authorization

{
  businessName: "Railz Test",
	serviceName: "freshbooks",
  connectionUuid: "UUID-string",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ],
  error: {
    errorCode: "unauthorizedCredentials",
    errorMessage: "Unable to authorize connection with provided credentials."
  }
}

Timeout

{
  businessName: "Railz Test",
	serviceName: "freshbooks",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ],
  error: {
    errorCode: "timeout",
    errorMessage: "Request has timedout."
  }
}

📘
serviceName is optional in timeout error events. A timeout prior to the user selecting a service will not have a serviceName in the event response.