Events

Understand how your users are interacting with Okra, using events.

Handle events in order to gracefully handle errors and build analytics around your Okra Widget.

Available Callbacks

CallbacksDescriptionExample
onSuccessCalled after the successful linking of an account to your Okra WidgetonSuccess = (json) => { console.log('handle success', json) }```
onErrorCalled after and error occurs while linking an account to your Okra WidgetonError = (json, error) => { console.log('handle error', error) }```
onCloseCalled when the Okra Widget is closed.onClose = (json) => { console.log('handle close', json) }```
onEventCalled anytime there is a significant event on your widget.onEvent = (event) => { console.log('Event tracking', event) }```

onSucces

A function that is called when a user has successfully connected their account to your Okra Widget and created a Record. The function should expect one argument, the metadata JSON object

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onSuccess: (data) => {
        console.log('You have linked an account!', data)
  }
});
{
    "auth": {
        "bank_details": {
            "_id": "5d6fe57a4099cc4b210bbebe",
            "name": "Alat",
            "slug": "alat",
            "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Alat.svg",
            "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/ALAT+by+Wema+Logo+Color.svg",
            "png_logo": "http://d1f1tz87xvarxp.cloudfront.net/Nigerian+Banks/Alat+by+Wema.png",
            "v2_logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Alat.svg",
            "v2_icon": "https://okra-images.s3.eu-west-3.amazonaws.com/ALAT+by+Wema+Logo+Color.svg"
        },
        "bank_id": "5d6fe57a4099cc4b210bbebe",
        "clientId": "okr-1652195470932-o6jJkRjX3AazT1SX11fUg",
        "customer_id": "61e7dc95d8b92c006348cf0e",
        "status": true,
        "type": "validate",
        "login_type": "bank"
    },
    "income": null,
    "identity": {
        "fullname": "Faith Sunday Smith",
        "firstname": "Faith",
        "lastname": "Smith",
        "middlename": "Sunday",
        "id": "627a80ac4bff31001e9ee9d6",
        "bvn": "50058467026",
        "nin": "5005848975",
        "score": 104,
        "env": "production-sandbox",
        "created_at": "2022-05-10T15:11:40.584Z",
        "last_updated": "2022-05-10T15:11:40.584Z",
        "aliases": [
            "Prosper  Gift Green",
            "Lily Agusto"
        ],
        "customer": "61e7dc95d8b92c006348cf0e",
        "dob": "2021-07-05T10:53:43+00:00",
        "gender": "M",
        "phone": [
            "09303471282",
            "06821834713"
        ],
        "email": [
            "[email protected]",
            "[email protected]"
        ],
        "address": [
            "516 Miss, Rachel Simpson Mission, Oye Delta"
        ],
        "verified": true,
        "status": "true",
        "verification_country": "NG",
        "lga_of_origin": "Ndokwa East",
        "lga_of_residenc": "Lagos Island",
        "marital_status": "Single",
        "nationality": "Nigeria",
        "state_of_origin": "Delta State",
        "state_of_residence": "Lagos State",
        "projects": [
            "62262a18ce77d5001d2b5ef3"
        ]
    },
    "error": null,
    "payment_authorization": null,
    "authorization_id": null,
    "authorizationId": null,
    "done": true,
    "accounts": [
        {
            "manual": false,
            "nuban": "2377140061",
            "id": "61e7dcb74063c16cf13c50c2",
            "connected": false,
            "name": "Prosper Smith",
            "type": "Current"
        },
        {
            "manual": false,
            "nuban": "2377141117",
            "id": "61e7dcb74063c16cf13c50d5",
            "connected": false,
            "name": "Prosper Smith",
            "type": "Domiciliary"
        },
        {
            "manual": false,
            "nuban": "2377146155",
            "id": "61e7dcb74063c16cf13c50e2",
            "connected": true,
            "name": "Prosper Smith",
            "type": "Domiciliary"
        }
    ],
    "record_id": "627a80914bff31001e9ee9d1",
    "record": "627a80914bff31001e9ee9d1",
    "bank_id": "5d6fe57a4099cc4b210bbebe",
    "customer_id": "61e7dc95d8b92c006348cf0e",
    "balance": {
        "formatted": [
            {
                "available_balance": 10089755,
                "ledger_balance": 10089755,
                "currency": "NGN",
                "name": "Prosper Smith",
                "nuban": "2377140061",
                "ref": "current-account",
                "status": "active",
                "type": "Current",
                "account": "61e7dcb74063c16cf13c50c2"
            },
            {
                "available_balance": 10079766,
                "ledger_balance": 10079766,
                "currency": "NGN",
                "name": "Prosper Smith",
                "nuban": "2377141117",
                "ref": "domicialiary-account",
                "status": "active",
                "type": "Domiciliary",
                "account": "61e7dcb74063c16cf13c50d5"
            },
            {
                "available_balance": 10139547,
                "ledger_balance": 10139547,
                "currency": "NGN",
                "name": "Prosper Smith",
                "nuban": "2377146155",
                "ref": "domicialiary-account",
                "status": "active",
                "type": "Domiciliary",
                "account": "61e7dcb74063c16cf13c50e2"
            }
        ],
        "data": {
            "formatted": [
                {
                    "available_balance": 10089755,
                    "ledger_balance": 10089755,
                    "currency": "NGN",
                    "name": "Prosper Smith",
                    "nuban": "2377140061",
                    "ref": "current-account",
                    "status": "active",
                    "type": "Current",
                    "account": "61e7dcb74063c16cf13c50c2"
                },
                {
                    "available_balance": 10079766,
                    "ledger_balance": 10079766,
                    "currency": "NGN",
                    "name": "Prosper Smith",
                    "nuban": "2377141117",
                    "ref": "domicialiary-account",
                    "status": "active",
                    "type": "Domiciliary",
                    "account": "61e7dcb74063c16cf13c50d5"
                },
                {
                    "available_balance": 10139547,
                    "ledger_balance": 10139547,
                    "currency": "NGN",
                    "name": "Prosper Smith",
                    "nuban": "2377146155",
                    "ref": "domicialiary-account",
                    "status": "active",
                    "type": "Domiciliary",
                    "account": "61e7dcb74063c16cf13c50e2"
                }
            ]
        }
    },
    "transactions": {
        "transactions": {
            "callback_url": "https://api.okra.ng/v2/callback?record=627a80914bff31001e9ee9d1&method=TRANSACTIONS"
        }
    },
    "launchAgain": false,
    "hideExit": false,
    "options": {
        "clientDefinedId": "Im testing out",
        "anotherclientDefinedId": "1234567890"
    },
    "meta": {
        "clientDefinedId": "Im testing out",
        "anotherclientDefinedId": "1234567890"
    },
    "success": true
}

onClose

The onClose callback is called when a user exits the Okra Widget flow. It takes two arguments, a nullable error object and a metadata JSON object. The metadata parameter is always present, though some values may be null.

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onClose: (json, error) => {
        console.log('Uh oh, you closed the widget', json)
  }
});

onError

The onExit callback is called when an error occurs during the Okra Widget initialization. It takes two arguments, a nullable error object and a metadata JSON object. The metadata parameter is always present, though some values may be null.

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onError: (json, error) => {
        console.log('You have connected!', json)
  }
});

onEvent

The onEvent callback is called anytime 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. You can find a list of events below:

🚧

Did you check if there was an error?
Make sure to check the withError parameter. If this is false, then the user did not receive an error. This is especially important with the WIDGET_USER_INTERNET_DISCONNECTED event. If there was no error then the user will be reconnected.


Event Logs

The event logs on your dashboard help monitor and track the interaction and activities of users on the Okra widget.
With the event log, you can get a comprehensive insight into all of the widget sessions a user interacts with.

Search

You can use the search feature to query specific keyword, such as the user ID, in other to output a specific event log related to a user.

Date

You can filter your search based on a certain date range on the calendar or choose from the default options, such as Today, Yesterday, Last 7 days, Last 14 days, Last 30 days,
This month and Last month.

Date RangeDate Range

Date Range

Export

You can export the event logs, by selecting the specific logs or choosing all the logs and the format, which is by default in JSON, and click the "send to mail" button to download it directly from your mail.


Event sample

{
        event: true
    event_callback_url: webhook.site/10097dhr-ef8c-40d3-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"
}

Auth Events

Landing screen

Event properties

Event NameEvent Description
user_connectingThe user is attempting to connect to the widget e.g. user has launched our SDK.
user_connectedThe SDK has been fully loaded and the user can now interact with the Okra widget.

Login method screen

Event properties

Event Name

Event Description

user_consent_granted

The user clicked on continue to grant data consent on sharing their accounts.

user_consent_review

The user clicked on view the Okra terms of service and privacy policy.

user_login_selection

The login method that the user selected from the login selection screen.

Possible options:
• Internet banking,
• Mobile banking


Bank screen

Event properties

Event NameEvent Description
user_viewed_banksThe user has landed on the bank selection screen.
user_account_type_selectionThe user toggled the Business/Personal button on the widget.

Search screen

Event properties

Event NameEvent Description
user_bank_searchThe user has engaged in the search for a bank in the search bar (for at least 5 secs).
user_bank_selectedThe user clicked on a bank.

No Search Result screen

Event properties

Event NameEvent Description
user_bank_search_no_resultsThe user hasn't received any results from their search term entered in the search bar.

Login screen

Event properties

Event NameEvent Description
user_login_attemptedThe user has entered their credentials and clicked on the login button in order to proceed with the connection.

Account Selection screen

Event properties

Event NameEvent Description
user_account_selectionThe user has landed on the account selection screen on the Okra Widget.
user_account_selectedThe user has selected the account they would like to connect to Okra.

Balance screen

Event properties

Event NameEvent Description
user_fetch_balanceOkra is pulling the user's balance.
user_retrieved_balanceOkra successfully retrieved the user's balance.
user_balance_sentA webhooks was triggered for the user's balance.
user_fetch_transOkra is pulling the user's transactions.

MFA screen

Event NameEvent Description
user_retry_otpThe user has clicked on the option to get a new OTP code.
user_mfa_questionThe user has landed on the MFA question screen on the Okra widget.
user_complete_mfaThe user has submitted their MFA answer.

Payment Events

Review Payment screen

Event properties

Event NameEvent Description
user_payment_reviewThe user is reviewing the payment
user_confirm_paymentThe user confirmed the payment.

Authorize Payment screen

Event properties

Events NameEvent Description
user_authorize_paymentThe user completed the payment authorization
user_payment_acknowledgedThe user clicks the Pay Now button

Returning User Events

Bank Selection screen

Event properties

Event NameEvent Description
user_rux_selectionA user viewed a list of their existing banks.
user_rux_bank_selectedThe user selects an existing account.
user_rux_not_foundNo user accounts were found for provided identification.

Network Events

EventsDescription
user_network_disconnectedThe user lost internet connectivity or experiencing connection issues.
user_network_reconnectedThe user has reconnected to the Okra widget.
user_timeoutThe connection attempt to the user has timed out.
user_bounceThe user has closed the Okra widget without completing the whole flow.
user_connection_failedThe user has failed to connect to their account. In order to get more details on the failure, please review the {property} in the same payload.
user_connection_successfulThe user has successfully connected their account to Okra.

General Events

Event NameEvent Description
WIDGET_COMPLETE_PROFILINGThe user has not completed setting up this internet or mobile banking account and was asked to complete profiling their profile.
user_profile_account_reviewThe user was asked to profile the device to the bank.
user_app_closeThe user has closed the widget from the success or failure screen.
user_app_redirectRedirect to page of choice after app close.

Did this page help you?