Interact With Portal

Introduction

This feature enables your widget to communicate with the portal via the postMessage API. You can request user authentication and navigation actions through standardized message events.

Event Data Structure

Widget Send To Portal:

{
  type: string,  // Event type identifier (e.g., "widget.request.login")
  message?: string,  // Optional payload
  // Additional properties as needed for specific event types
}

Portal Send To Widget

The portal will actively send a message to the widget:

{
  type: "portal.send.[TYPE]",
  message: string | object
}

Portal Responses

The portal will send standardized responses to your widget:

{
  type: "portal.response.ok" | "portal.response.error",
  message: string  // Success confirmation or error details
}

Error Handle

Error responses use the portal.response.error type with descriptive messages. Always handle these errors gracefully in your widget implementation.

---

Events From Iframe

When embedding the Portal via <iframe>, implement cross-origin messaging using the Web API window.postMessage. The host page (parent) can dispatch structured messages, now we support below message:

redirect

This event allows the portal redirect to the specified page.

Example:

iframe.contentWindow.postMessage({
  type: 'redirect',
  url: 'https://yourdomain.com/checkout'
}, '*');

Events To Widget

portal.send.access_token

This message is sent by the portal to the widget when the user's login status changes and an access token becomes available (e.g., upon successful login). This token can be used by the widget to authenticate requests to backend services.

The message body structure is as follows:

{
    "type": "portal.send.access_token",
    "message": "sometoken" //string
}

• Trigger: User login status changes, and an access token is issued.

---

portal.send.remove_token

This message is sent by the portal to the widget when the user's login status changes and an existing access token is removed or becomes invalid (e.g., upon logout or token expiry). Widgets should clear any stored tokens upon receiving this message.

The message body structure is as follows:

{
    "type": "portal.send.remove_token",
    "message": "" //always ""
}

• Trigger: User login status changes, and the access token is removed or invalidated.

---

portal.send.app_info

This message is sent by the portal to the widget after the widget sends the WIDGET_READY message. It contains essential information about the application or environment the widget is running in.

The message body structure you can refer here: Get Portal Info

• Trigger: Sent after the widget sends WIDGET_READY

---

portal.send.source_link_id

This message is sent by the portal to inform the widget about the specific link from which it was loaded. This is particularly relevant when the widget is accessed via a short link or any other specific link generated by the portal.

• Trigger: Sent after the widget sends WIDGET_READY, when the widget is loaded via a portal-generated link (e.g., a short link).

• Purpose: To provide the unique identifier of the source link. This message contains both the source_link_id and the link_detail. The source_link_id identifies the source link, and the link_detail object contains the detailed information about that link.

Message Structure (portal.send.source_link_id):

{
    "type": "portal.send.source_link_id",
    "message": {
        "source_link_id": string // The unique identifier of the link that loaded the widget.
        "link_detail": object // An object containing the detailed information about the link.
    }
}

---

portal.send.link_message

When accessing a widget using our short link service, the portal will send a message to the widget based on the parameters defined in the short link. This action occurs after the widget sends the WIDGET_READY message to the portal.

The message body structure is as follows:

{
    "type": "portal.send.link_message",
    "message": string //eg: some message
}

The message is a string with a maximum length of 2048 characters. If you need to transmit JSON data, it is recommended to use Base64 encoding.

portal.send.credit_top_up_success

When a user successfully tops up their credit, the portal sends a credit_top_up_success message to the widget. This message is triggered after the top-up success event occurs on the portal.

The message body structure is as follows:

{
    "type": "portal.send.credit_top_up_success",
    "message": {
        "amount": number // Int, e.g., 2000
    }
}

The message field now directly contains a JSON object with an amount property. This amount represents the credit amount that was successfully topped up.

---

portal.send.subscribed_detail

This is the primary message used by the portal to inform the widget about the user's subscription status and provide the unique identifier required for per-user configuration.

• Trigger: This message is sent by the portal in two scenarios:

  1. When a user opens the management interface specifically for this widget.

  2. When any user loads and initializes the widget in the main frontend portal view.

• Purpose: The message contains a type field identifying the message and a message field whose value is an object containing detailed information about the user's subscription to this specific widget instance. This includes subscription status information, configuration fields, and a unique identifier (subscription_id field) that is unique for each user's subscription instance for this specific widget. This unique subscription_id serves as the key you should use on your backend to store and retrieve per-user configuration settings.

Message Structure (protal.send.subscribed_detail):

The message body structure is as follows:

{
    "type": "protal.send.subscribed_detail",
    "message": { // Detailed information about the subscription
        "created_at": string, // Timestamp when the subscription was created (ISO 8601 format)
        "expired_at": string | null, // Timestamp when the subscription expires, or null if no expirytype
        "private_config": object | null, // Configuration data intended for private use (e.g., backend settings)
        "public_config": object | null, // Configuration data intended for public/frontend use
        "started_at": string | null, // Timestamp when the subscription started, or null
        "updated_at": string, // Timestamp when the subscription was last updated (ISO 8601 format)
        "subscription_id": string, // The unique identifier for this user's subscription instance for this widget, used as the key for per-user configuration storage on your backend.
        "widget_tag": string // The tag or identifier of the widget
    }
}

• Important Note: Based on the structure and discussion, the subscription_id field within the nested message object should be treated as the unique identifier for retrieving and saving per-user configuration settings. Please use this field as the key for your backend configuration storage.

---

Events From Widget

widget.request.login

To request user authentication:

window.parent.postMessage({
  type: "widget.request.login"
}, "*");

Responses:

• Success: { type: "portal.response.ok", message: "" }

• Error: { type: "portal.response.error", message: "user already login" }

---

widget.request.to_profile

To request navigation to the user's profile page:

window.parent.postMessage({
  type: "widget.request.to_profile"
}, "*");

Responses:

• Success: { type: "portal.response.ok", message: "" }

• Error: { type: "portal.response.error", message: "user not login" }

widget.request.send_token

To request a send token pop-up

window.parent.postMessage({
  type: "widget.request.send_token"
}, "*");

Responses:

• Success: { type: "portal.response.ok", message: "" }

• Error: { type: "portal.response.error", message: "user not login" }

widget.request.top_up

To request a top up pop-up so user can top-up USDC

window.parent.postMessage({
  type: "widget.request.top_up"
}, "*");

Responses:

• Success: { type: "portal.response.ok", message: "" }

• Error: { type: "portal.response.error", message: "user not login" }

widget.request.top_up_credit

To request a top up pop-up so user can top-up Credit

window.parent.postMessage({
  type: "widget.request.top_up_credit"
  message: {
    min_value: 500,
    quick_values: [1000, 2000, 5000]
    callback_url: https://someurl/top-up-callback
  }
}, "*");

Request:

• message.min_value: number, Optional. Specifies the minimum amount the user can top up. Example: 500.

• message.quick_values: number[] Optional. Provides a list of suggested, or "quick," values for the user to easily select for their top-up amount. Example: [1000, 2000, 5000].

• message.callback_url: number[] Optional. A URL to which the system will send a callback notification after the top-up transaction status is updated.

Responses:

• Success: { type: "portal.response.ok", message: "" }

• Error: { type: "portal.response.error", message: "user not login" }

widget.request.logout

To request user logout

window.parent.postMessage({
  type: "widget.request.logout"
}, "*");

Responses:

• Success: { type: "portal.response.ok", message: "" }

• Error: { type: "portal.response.error", message: "user not login" }