What are smart widgets?

Smart Widgets are interactive graphical components encapsulated as Nostr events, designed for seamless integration into applications. Each widget type serves a specific purpose, with well-defined structures and behaviors to support various use cases.

Smart widget event structure

{
    "id": <event-id>,
    "pubkey": <hex-pubkey>,
    "content": <string-widget-title>,
    "kind": 30033,
    "tags": [
        ["client",<client-name>,<client-31190-data>],
        ["d", <unique-identifier>],
        ["l", <widget-type>],
        ["icon", <widget-icon-url>], // only for action/tool widgets
        ["image",<widget-thumbnail-image-url>],
        ["input",<input-label>], // optional input field component
        ["button", <label>, <type>, <url>],
        ...
        ["button", <label>, <type>, <url>]
    ]
}

Widget Types

Basic Widget

• Description: A versatile widget comprising multiple UI components for flexible display and interaction.
• Components:
  • Images (mandatory, maximum of one).
  • Input Field (optional, maximum of one).
  • Buttons (optional, maximum of six).
• Use Case: Ideal for scenarios requiring a combination of visual elements and user inputs, such as forms or dashboards.

Action Widget

• Description: A streamlined widget designed to trigger an action by embedding a URL in an iframe.
• Components:
  • Image (single, for visual representation).
  • Button (single, type: app).
• Behavior:
  • Clicking the button opens the specified URL within an iframe.
  • The iframe does not return any data to the parent application.
• Use Case: Suitable for launching external applications or resources without expecting a response, such as opening a third-party tool.

Tool Widget

• Description: A widget that facilitates interaction with an external application via an iframe, with data exchange capabilities.
• Components:
  • Image (single, for visual representation).
  • Button (single, type: app).
• Behavior:
  • Clicking the button opens the specified URL within an iframe.
  • The iframe is configured to return data to the parent application upon interaction.
• Use Case: Perfect for scenarios requiring data retrieval or feedback from an external tool, such as a configuration interface or a data picker.

Technical Notes

• Nostr Event Structure: Each widget is represented as a Nostr event, ensuring compatibility with the Nostr protocol for decentralized communication.
• Iframe Integration: For Action and Tool widgets, the iframe must adhere to standard web security practices (e.g., sandboxing, CORS policies) to ensure safe URL embedding.
• Extensibility: Developers can customize widget appearance and behavior within the defined constraints (e.g., maximum button limits, single input field) to align with application requirements.

Why Use Smart Widgets (Action & Tool Types)?

Smart Widgets, built as Nostr events, enhance applications with interactive, interoperable components. Here’s why developers should leverage them:

1. Interactive Feed Embeds: Embed applications as dynamic widgets in user feeds, enabling seamless and interactive engagement.
2. Host App Communication: Tool Widgets enable data exchange via iframes, integrating tightly with the host application.
3. Launch with Metadata: Open apps with user metadata (e.g., public key) for streamlined onboarding.
4. Proxy Nostr Events: Allow the host to sign/publish events on users’ behalf, simplifying interactions.
5. Quick-Access Saving: Let users save widgets for one-tap access, boosting retention.
6. Boost Discoverability: Surface apps in search and social feeds via optimized widget metadata.