Event Listeners
Create a more controlled user experience through Railz Connect event listeners
Railz 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 Railz Connect script in your application:
<!-- Insert this div where you want Railz 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 Railz Connect script -->
onSuccess
Load
The event is called when Railz 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 Railz Connects has loaded. The unique identifier of the business as defined by you or generated by Railz. |
metadata | array | Displayed once Railz connect has loaded. The metadata provided by you. |
{
businessName: "Railz 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 Railz Connects has loaded. The unique identifier of the business as defined by you or generated by Railz. |
metadata | array | Displayed once Railz connect has loaded. The metadata provided by you. |
serviceName | string | The service name the user connected to a business, e.g. quickbooks |
{
businessName: "Railz Test",
serviceName: "quickbooks",
metadata: [
{
name: "businessLocation",
value: "canada",
webhookLocation: ["header", "body"]
}
]
}
onExit
This event is called when a user exits Railz 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 Railz Connects has loaded. The unique identifier of the business as defined by you or generated by Railz. |
{
businessName: "Railz 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 Railz 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",
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 aserviceName
in the event response.
Updated 9 months ago