Widget Guide

Widget Guide

**Referenced Files in This Document** - [backend/src/routes/widget.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/widget.js) - [backend/src/services/badgeBuilder.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/badgeBuilder.js) - [frontend/src/widget/Widget.jsx](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/widget/Widget.jsx) - [frontend/src/widget/widget-entry.jsx](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/widget/widget-entry.jsx) - [frontend/src/widget/widget.css](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/widget/widget.css) - [frontend/src/components/TrustBadge.jsx](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/components/TrustBadge.jsx)

Table of Contents

1. Introduction
2. Widget Types
3. Embedding the Widget
4. Widget Configuration
5. Customization
6. API Integration
7. Examples

Introduction

AgentID provides embeddable trust widgets that can be integrated into any website. These widgets display real-time trust scores, verification status, and agent metadata in a visually appealing format.

Widget Types

HTML Widget

A complete, self-contained HTML page served via iframe:

<iframe 
  src="https://agentid.provenanceai.network/widget/{pubkey}"
  width="400"
  height="300"
  frameborder="0">
</iframe>

Features:

• Auto-refresh every 60 seconds
• Responsive design
• Status-based theming
• Capability tags

SVG Badge

A static SVG image for documentation and README files:

![Trust Badge](https://agentid.provenanceai.network/badge/{pubkey}/svg)

Features:

• Scalable vector graphics
• Status colors (green/amber/red)
• Score visualization
• Compact size

JSON Badge

Raw badge data for custom implementations:

const response = await fetch('https://agentid.provenanceai.network/badge/{pubkey}');
const badge = await response.json();

Embedding the Widget

Basic Iframe Embed

<div class="agentid-widget">
  <iframe 
    src="https://agentid.provenanceai.network/widget/AGENT_PUBKEY_HERE"
    width="100%"
    height="320"
    style="border: none; border-radius: 12px;"
    title="AgentID Trust Widget">
  </iframe>
</div>

Responsive Embed

<div class="widget-container" style="position: relative; padding-bottom: 80%; height: 0;">
  <iframe 
    src="https://agentid.provenanceai.network/widget/AGENT_PUBKEY_HERE"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"
    title="AgentID Trust Widget">
  </iframe>
</div>

JavaScript Embed (Dynamic)

function embedAgentIDWidget(containerId, pubkey) {
  const container = document.getElementById(containerId);
  const iframe = document.createElement('iframe');
  
  iframe.src = `https://agentid.provenanceai.network/widget/${pubkey}`;
  iframe.width = '100%';
  iframe.height = '320';
  iframe.style.border = 'none';
  iframe.style.borderRadius = '12px';
  
  container.appendChild(iframe);
}

// Usage
embedAgentIDWidget('widget-container', 'agent_pubkey_here');

Widget Configuration

Available Options

The widget supports these display modes:

Option	Description	Default
theme	Color theme (dark/light)	dark
compact	Compact mode (true/false)	false

Pass options via query parameters:

<iframe src="https://agentid.provenanceai.network/widget/{pubkey}?theme=light&compact=true">

Auto-Refresh

The widget automatically refreshes every 60 seconds to keep data current. This can be disabled:

<iframe src="https://agentid.provenanceai.network/widget/{pubkey}?refresh=false">

Customization

CSS Customization

When embedding via iframe, you can style the container:

.agentid-widget-container {
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  overflow: hidden;
}

.agentid-widget-container iframe {
  display: block;
}

Custom Implementation

Build your own widget using the JSON API:

async function renderCustomWidget(elementId, pubkey) {
  const response = await fetch(`https://agentid.provenanceai.network/badge/${pubkey}`);
  const data = await response.json();
  
  const widget = document.getElementById(elementId);
  widget.innerHTML = `
    <div class="trust-badge ${data.status}">
      <h3>${data.name}</h3>
      <div class="score">${data.score}/100</div>
      <div class="status">${data.label}</div>
      <div class="capabilities">
        ${data.capabilities.map(c => `<span>${c}</span>`).join('')}
      </div>
    </div>
  `;
}

API Integration

Badge JSON Endpoint

GET /badge/{pubkey}

Response:

{
  "pubkey": "agent_public_key",
  "name": "Agent Name",
  "status": "verified",
  "score": 85,
  "label": "HIGH",
  "capabilities": ["trading", "analytics"],
  "registeredAt": "2024-01-15T10:30:00Z",
  "totalActions": 150,
  "widgetUrl": "https://agentid.provenanceai.network/widget/agent_pubkey"
}

SVG Endpoint

GET /badge/{pubkey}/svg

Returns an SVG image with status-based theming.

Widget HTML Endpoint

GET /widget/{pubkey}

Returns a complete HTML page with the widget.

Examples

React Component

import React, { useEffect, useState } from 'react';

function AgentIDWidget({ pubkey }) {
  const [badge, setBadge] = useState(null);
  
  useEffect(() => {
    fetch(`https://agentid.provenanceai.network/badge/${pubkey}`)
      .then(r => r.json())
      .then(setBadge);
  }, [pubkey]);
  
  if (!badge) return <div>Loading...</div>;
  
  return (
    <div className={`trust-badge ${badge.status}`}>
      <h3>{badge.name}</h3>
      <div className="score">{badge.score}/100</div>
      <div className="label">{badge.label}</div>
    </div>
  );
}

Markdown Documentation

## Trust Verification

This agent is verified by AgentID:

[![Trust Score](https://agentid.provenanceai.network/badge/PUBKEY/svg)](https://agentid.provenanceai.network/agents/PUBKEY)

HTML Email

<table style="border: 1px solid #ddd; border-radius: 8px;">
  <tr>
    <td>
      <img src="https://agentid.provenanceai.network/badge/PUBKEY/svg"
           alt="Trust Badge" width="200">
    </td>
  </tr>
</table>