Callbacks provide information when specific events take place in your Widget implementation. Improve your application's usability and enhance user experience by building workflows, front-end responses, and automation around the callbacks that Okra offers.

Callback types

Event	Description	Example usage
`onSuccess`	Called when a user has successfully connected their account to your Okra Widget and created a record. The function expects one argument, the `metadata` JSON object.	- Display a confirmation message to the user to show that their account has been successfully linked. - Log the success events to build analytics and gain user insights.
`onClose`	Called when a user exits the Okra Widget flow. This callback does not expect any arguments.	- Display an appropriate call-to-action message or guide your users to an alternative workflow. - Log timestamps and event details to understand conversion and bounce rates.
`onError`	Called when an error occurs during the Okra Widget initialization. It accepts one argument, an `error` object that contains details about the error that occurred.	- Display error-specific warnings or messages on the front end for your users. - Define fallback workflows to keep users in your application.
`onEvent`	Called every time there is a significant event on your Widget. It takes one argument, an `event` object which is a `metadata` JSON object. The `event` parameter is always present, though some values may be `null`.	- Log the `event_name` parameters to gain insight into how your users interact with your application and build analytics around the data.

Sample implementation using JavaScript

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onSuccess: (data) => {
		console.log('You have linked an account!', data)
  }
});

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onClose: function () {
    console.log("widget is being closed");
}
});

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onError: function (error) {
    console.log("error has occured", error);
}
});

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ..., 
onEvent: (event) => {
  console.log("Event Payload", event);
	}
});

List of `onEvent` parameters

General events

These events give you information about general actions around the widget, like loading, app closure, and network issues.

Event name	Flow type	`onEvent` parameter name	Event trigger
Clicks to view terms	General	`consent_review`	Triggers when the Terms of Service page loads.
Widget loaded	General	`connected`	User sees the fully loaded landing page.
Widget initiation	General	`connecting`	User is attempting to connect to the widget - a user has launched our SDK. This event triggers when the loader is activated.
Search bank	General	`user_bank_search`	User is typing in the search field.
Poor network modal	General	`bad_network`	Triggers when the the poor network warning modal loads.
Network disconnected	General	`network_disconnected`	User is disconnected from the internet.
Network reconnected	General	`network_reconnected`	User reconnected to the internet.
Bounce	General	`bounce`	User closed widget without completing the account connection.
Completed widget flow	General	`app_close`	User closed the widget from a success or error screen.
Invalid link	General	`invalid_link`	Triggers when the invalid link error screen loads.

Data events

These events give you information about user interaction and widget events in the account connection flow.

Event name	Flow type	`onEvent` parameter name	Event trigger
Showing account type screen	Data flow	`data_account_type`	Triggers when the account type selection screen loads for a data widget.
Showing bank screen	Data flow	`data_viewed_banks`	Triggers when the bank selection screen loads.
Select bank	Data flow	`data_select_bank`	Triggers when the user selects a bank on the widget.
Credentials screen	Data flow	`data_login_screen`	Triggers when the account credentials entry screen loads.
Login attempt	Data flow	`data_login_attempt`	Triggers when the user clicks the continue button to confirm login credentials.
Login method	Data flow	`data_login_method_selection`	Triggers when the user chooses a login method: internet or mobile banking.
Select account(s)	Data flow	`data_select_accounts`	Triggers when the the account selection screen loads.
Success	Data flow	`data_connection_successful`	Triggers when the user is on the success screen.
Failed	Data flow	`data_connection_failed`	Triggers when the End result failed screen for a data connection loads.
Link a new account	Data flow	`data_new_account`	Triggers when the user is on the success screen and clicks the button to link a new account.
MFA Select auth method	Data flow	`data_mfa_select_method`	Triggers when the “Choose your MFA method” screen loads.
MFA Verify on bank app	Data flow	`data_mfa_verify_on_bank`	Triggers when the verify on bank app screen loads.
MFA Validate with an offline PIN	Data flow	`data_mfa_validate_offline`	Triggers when the user clicks to verify with an offline PIN.
Select bank	Data flow	`data_bank_guaranty-trust-bank`	Triggers when the widget saves the name of the bank the user chooses.
Success	Data flow	`data_nuban_verify_successful`	Triggers when the user is on the success screen after verifying their nuban.
Failed	Data flow	`data_nuban_verify_failed`	Triggers when the user is on the End result failed screen for a nuban verification.
Specify your banking app	Data flow	`data_bank_app_select`	Triggers when the modal that prompts the user to select their banking app loads.
Nuban Verify attempt	Data flow	`data_nuban_verify_attempt`	Triggers when the user clicks the continue button to confirm thier nuban.
Data MFA Security question	Data flow	`data_mfa_security_question`	Triggers when the security question screen loads.

Payments events

These events give you information about user interaction and widget events in the payment flow.

Event name	Flow type	`onEvent` parameter name	Event trigger
Select payment account type	Payments	`payment_account_type`	Triggers when the account type (business or personal) selection screen loads.
Select bank	Payments	`payment_bank_selection`	Triggers when the bank selection page loads.
Specify your banking app	Payments	`payment_bank_app_select`	Triggers when the modal that prompts the user to select their banking app loads.
Payment enter credentials	Payments	`payment_login_attempt`	Triggers when the user clicks the continue button to attempt to login.
Payment Account selection	Payments	`payment_select account`	Triggers when the “Select your account” screen loads.
Payments MFA Security question	Payments	`payment_mfa_security_question`	Triggers when the security question screen loads.
Payment success	Payments	`payment_connection_successful`	Triggers when the final success screen after the payment is complete loads.
Payment failed	Payments	`payment_connection_failed`	Triggers when the failed connection screen after a failed payment connection loads.
Select bank	Payments	`payment_bank_guaranty-trust-bank`	Triggers when the user selects a bank on the bank selection page.
Showing bank screen	Payments	`payment_viewed_banks`	Triggers when the bank selection screen loads.
Login method	Payments	`payment_login_method_selection`	Triggers when the widget logs the login method the user chooses: internet or mobile banking.
MFA Verify on bank app	Payments	`payment_mfa_verify_on_bank`	Triggers when the Verify in bank app screen loads.
MFA Validate with an offline PIN	Payments	`payment_mfa_validate_offline`	Triggers when the user clicks to verify with an offline PIN.
Credentials screen	Payments	`payment_login_screen`	Triggers when the account credentials entry screen loads.
Select bank	Payments	`payment_select_bank`	Triggers when the user selects a bank on the bank selection page.

RUX events

These events give you information about user interaction and widget events in the RUX (returning user experience) flow.

Event name	Flow type	`onEvent` parameter name	Event trigger
RUX select account load	RUX	`rux_selection`	The user views a list of their existing banks.
Enter password	RUX	`rux_enter_password`	Triggers when the Enter Password screen loads.
Link a new account	RUX	`rux_new_account`	Triggers when the user clicks on the Add another account button.
No RUX accounts available	RUX	`rux_not_found`	Triggers when the widget finds no user accounts for the provided identification.
Success	RUX	`rux_successful`	Triggers when the success screen for RUX connections loads.
Failed	RUX	`rux_failed`	Triggers when the failed connection screen for RUX connections loads.

Event Logs

The event logs on your Dashboard help you monitor and track user interactions in the Okra Widget. Leverage these features to get a comprehensive insight into the activities of your users:

Filter for user IDs to check event logs related to a specific user.
Filter for event logs from a specific date or time period using the date picker.
Export event logs to CSV or JSON format. Select the events you want to export and the format you prefer, and the Dashboard will send the events in an email.

Sample event callback

{
		event: true
    event_callback_url: webhook.site/10097dhr-ef8c-00d3-86f8-894a010f5706
    event_data: 
  		{
        tracking_id: MN09uhhgd
      }
    event_location: "https://app.okra.ng/:ref/bank?bank=rubies-bank"
    event_name: "USER_LOGIN_ATTEMPTED"
    event_time: null
    event_type: "DATA_EVENT"
}