SDK Events

A comprehensive guide to the events posted by the Hubble SDK to the parent application.

The Hubble SDK can post events back to the parent application, allowing you to track user behavior and respond to actions within the gift card store. This is useful for analytics.

How to Listen for Events

To receive events from the SDK, you will need to register an event listener. Please refer to the platform-specific integration guides for detailed instructions on how to implement this.

Event Reference

The SDK emits various events with associated data. Below is a comprehensive list of events you can listen for.

Note: All navigation events automatically include an isModal (boolean) property indicating whether the screen is displayed as a modal overlay. The properties listed below are additional to this standard property.

`visit_home`

Sent when the user visits the home screen.

Additional Properties: None

Example:

{ "isModal": false }

`visit_search`

Sent when the user visits the search screen.

Additional Properties: None

Example:

{ "isModal": false }

`visit_category`

Sent when a user visits a specific category page.

Additional Properties:

categoryName (required) - The name of the category visited

Example:

{ "categoryName": "FASHION", "isModal": false }

`visit_brand_l2`

Sent when a user visits a specific brand’s page.

Additional Properties:

productId (required) - The unique product identifier
brandName (required) - The name of the brand viewed
amount (required) - The selected voucher amount

Example:

{
  "productId": "01VFBNDM43I2DHJSMCX",
  "brandName": "Amazon",
  "amount": 500,
  "isModal": false
}

`visit_checkout_summary`

Sent when the user visits the checkout summary screen.

Additional Properties:

brandName (required) - The brand being purchased
amount (required) - The transaction amount
couponCode (optional) - Applied coupon code if any
useCoins (optional) - Whether coins are being used
discount (optional) - Total discount amount
hubbleBaseDiscount (optional) - Base discount from Hubble
coinDiscount (optional) - Discount from coins
couponDiscount (optional) - Discount from coupon

Example:

{
  "brandName": "Amazon",
  "amount": 500,
  "couponCode": "SAVE10",
  "useCoins": true,
  "discount": 150,
  "hubbleBaseDiscount": 50,
  "coinDiscount": 50,
  "couponDiscount": 50,
  "isModal": false
}

`visit_voucher_edit_modal`

Sent when the user opens the voucher amount/quantity edit modal.

Additional Properties:

productId (required) - The unique product identifier
brandName (optional) - The name of the brand
quantity (optional) - Number of vouchers selected
amount (optional) - The selected voucher amount

Example:

{
  "productId": "01VFBNDM43I2DHJSMCX",
  "brandName": "Amazon",
  "quantity": 1,
  "amount": 500,
  "isModal": true
}

Default Screen Visit Events

A generic visit_{screen_name} event is sent whenever a user navigates to any screen within the SDK that doesn’t have a dedicated event section above.

Common Properties:

All default screen visit events automatically include:

isModal (boolean) - Whether the screen is displayed as a modal overlay

Note: Screens with additional properties like visit_brand_l2, visit_checkout_summary, and visit_voucher_edit_modal are documented in the Navigation Events section above.

For example:

Visiting the “Apply Coupons” screen sends visit_coupons with {"isModal": true} if opened as a modal
Visiting the transactions screen sends visit_transactions with {"isModal": false}

Screen Names

The following are the possible values for {screen_name}:

Home & Menu:

home
home_menu
iframe_modal

Authentication:

collect_phone
collect_otp
complete_profile

Voucher Processing:

coupons
voucher_generation_success
voucher_generation_fail
voucher_generation_loader

Payment Screens:

payment_loader
payment_options
invoice
upi_id_input
payment_status_polling

Transactions & History:

transactions
transaction_l2

Information Screens:

how_to_use
tnc
warning_modal
brand_unavailable_modal
category_browsing_modal

Help & Support:

help_and_support

Phone Verification:

phone_collection
phone_otp_verification

Coins:

custom_coin_input_modal
see_why_coins_limit_modal

Bank Transfer:

bank_transfer
bank_how_to_transfer_modal
bank_see_why_bs_modal
bank_summary_transfer_modal
bank_edit_amount
bank_transfer_success
bank_transfer_fail
bank_transfer_loader
bank_transfer_mode
bank_transfer_payouts
bank_transfer_high_waiting_time

Payment Events

`payment_initiated`

Sent when a payment is initiated by the user.

Properties:

brandName (required) - The brand being purchased
amount (required) - The payment amount
paymentMode (required) - The payment method (e.g., “UPI”, “CARD”)
productId (required) - The unique product identifier
consumeCoins (optional) - Whether coins are being used
couponCode (optional) - Applied coupon code if any

Example:

{
  "brandName": "Amazon",
  "amount": 500,
  "paymentMode": "UPI",
  "productId": "01GMAVS2CHXR0XP1BZSTA9A44K"
}

`payment_success`

Sent when the payment gateway confirms payment success.

Properties:

amount (required) - The payment amount
referenceId (required) - The payment order reference ID
provider (required) - The payment provider (e.g., “RAZORPAY”)

Example:

{
  "amount": 500,
  "referenceId": "ord_123",
  "provider": "RAZORPAY"
}

`payment_fail`

Sent when a payment fails at the gateway level.

Properties:

amount (required) - The payment amount
referenceId (required) - The payment order reference ID
provider (required) - The payment provider
failureReason (required) - The reason for payment failure

Example:

{
  "amount": 500,
  "referenceId": "ord_123",
  "provider": "RAZORPAY",
  "failureReason": "Payment declined"
}

`payment_upi_intent_triggered`

Sent when a UPI intent is triggered to open a UPI app for payment.

Properties:

referenceId (required) - The payment order reference ID
amount (required) - The payment amount
upiApp (optional) - The name of the specific UPI app selected

Platform behavior:

iOS: The SDK displays a custom selection modal for UPI app selection. When the user selects a specific UPI app from this list, the upiApp property is included in the event.

Android: The SDK triggers Android’s built-in system modal for UPI app selection. Since the app selection is handled by the system and not the SDK, the upiApp property is not available and will not be sent. Only referenceId and amount are included.

Example:

{
  "upiApp": "GPAY",
  "amount": 500,
  "referenceId": "ord_123"
}

Possible upiApp values (iOS only):

Value	UPI App
`PhonePe`	PhonePe
`PayTM`	Paytm
`GPAY`	Google Pay
`CRED`	CRED

`click_payment_cancel`

Sent when a user clicks the cancel/close button during an active payment flow.

Properties:

referenceId (required) - The payment order reference ID
amount (required) - The payment amount
paymentStatus (required) - The current payment order status
provider (optional) - The payment provider (e.g., “RAZORPAY”)

Example:

{
  "referenceId": "ord_123",
  "amount": 500,
  "paymentStatus": "ACTIVE",
  "provider": "RAZORPAY"
}

Voucher Events

`voucher_generation_processing`

Sent when the order status is “ACTIVE” and voucher generation is in progress. This indicates the system is processing the order and generating vouchers after payment confirmation. The order will eventually resolve to either voucher generation success or failure.

Properties:

amount (required) - The order amount
referenceId (required) - The order reference ID
provider (required) - The payment provider (e.g., “RAZORPAY”, “PAYU”)
paymentMode (optional) - The payment method used (e.g., “UPI_INTENT”, “CARD”)

Example:

{
  "amount": 500,
  "referenceId": "ord_123",
  "provider": "RAZORPAY",
  "paymentMode": "UPI_INTENT"
}

`voucher_generation_success`

Sent when voucher(s) are successfully generated after payment.

Properties:

brandName (required) - The brand for which vouchers were generated
amount (required) - The total voucher amount
vouchersCount (required) - The number of vouchers generated

Example:

{
  "brandName": "Amazon",
  "amount": 500,
  "vouchersCount": 1
}

`voucher_generation_fail`

Sent when voucher generation fails after payment.

Properties:

brandName (required) - The brand for which voucher generation was attempted
amount (required) - The attempted voucher amount
vouchersCount (required) - The number of vouchers attempted
orderId (required) - The order ID for reference

Example:

{
  "brandName": "Amazon",
  "amount": 500,
  "vouchersCount": 1,
  "orderId": "ord_123"
}

User Interaction Events

`search_query`

Sent whenever the user types in the search field.

Properties:

query (required) - The search query text

Example:

{ "query": "amazon card" }

`banner_clicked`

Sent when the user clicks on a promotional banner.

Properties:

bannerId (required) - The unique identifier of the banner
bannerType (required) - The type of banner (e.g., “PROMOTIONAL”, “OFFER”)
bannerUrl (optional) - The URL the banner links to

Example:

{
  "bannerId": "banner_123",
  "bannerType": "PROMOTIONAL",
  "bannerUrl": "https://example.com/offer"
}

`coin_payment`

Sent when the entire payment is made using only coins (no actual payment gateway involved).

Properties:

amount (required) - The total amount
coins (required) - Number of coins used
baseDiscount (required) - Base discount applied
couponDiscount (required) - Coupon discount applied
totalDiscount (required) - Total discount amount

Example:

{
  "amount": 500,
  "coins": 10,
  "baseDiscount": 100,
  "couponDiscount": 50,
  "totalDiscount": 150
}

Error Events

`init_error`

Sent when the SDK fails to initialize properly.

Properties:

error (required) - The error object or message describing the initialization failure

Example:

{
  "error": "Failed to load configuration"
}

`auth_error`

Sent when authentication fails or the user’s session has expired.

Properties:

error (required) - Description of the authentication error

Example:

{
  "error": "Invalid session or session has expired"
}

`unexpected_error`

Sent when an unexpected error occurs during the transaction flow.

Properties:

brandName (optional) - The brand being purchased
amount (optional) - The transaction amount
reason (required) - Description of the error
errorType (optional) - Categorization of the error type
paymentMode (optional) - The payment method being used
orderId (optional) - The order ID if available

Example:

{
  "brandName": "Amazon",
  "amount": 500,
  "reason": "Failed to create payment order",
  "errorType": "REDEMPTION_INIT_FAILED",
  "paymentMode": "UPI"
}

Session Events

`exited`

Sent when the user exits or closes the SDK.

Properties:

through (optional) - How the user exited (e.g., “home_back_button”)

Example:

{
  "through": "home_back_button"
}