Skip to content

Publisher Integration

PSI is designed to be embedded into existing broadcaster websites. There are several integration approaches, from simple script injection to full server-side rendering.

Integration Methods

1. Content Proxy (Quickest for Demos)

The content proxy rewrites a broadcaster's pages on-the-fly to inject PSI scripts. No changes to the broadcaster's actual site are needed.

sequenceDiagram
    participant Browser
    participant Proxy as Content Proxy<br/>(demo-proxy)
    participant Publisher as Publisher Site
    participant PSI as PSI System

    Browser->>Proxy: GET publisher-page (via proxy domain)
    Proxy->>Publisher: Fetch original page
    Publisher-->>Proxy: HTML response
    Proxy->>Proxy: Inject psi.js script tag
    Proxy-->>Browser: Modified HTML
    Browser->>PSI: psi.js loads sidebar + teasers
    PSI-->>Browser: Conversation UI via iframes

How to use:

  1. Find your publisher in the demo proxy config
  2. Replace the domain in an article URL with {silo-key}.talkb.org
  3. Add ?psiHost={your-psi-instance-url} to point to your deployment
  4. Press Ctrl+O to open the configuration sidebar

Example: 

Original:  https://www.rts.ch/info/article/example-28836835.html
Proxied:   https://rts.talkb.org/info/article/example-28836835.html?psiHost=https://dialogue-83198.web.app

2. Direct Script Integration (Production)

For production, add the psi.js script directly to your page template:

<script src="https://psi.newpublic.org/js/psi-sidebar.js"></script>

This script:

  • Creates the PSI sidebar (opened by a floating button)
  • Manages sidebar open/close state
  • Communicates with the PSI system via iframes

3. Server-Side Teasers (Advanced)

For richer integration, publishers can render PSI teasers server-side:

  1. Store the questionKey for linked conversations in your CMS
  2. Call the PSI API: GET /api/questions/getMetadata?questionKey={key}
  3. Render the teaser using your own components (title, featured comment, comment count)
  4. Link the teaser to the PSI sidebar

The Publisher Demo provides a complete Next.js 14 example of this approach.

Publisher Demo Application

The publisher-demo/ directory contains a working Next.js application demonstrating:

  • Fetching question metadata from the PSI API
  • Rendering teasers with server-side React components
  • Opening the PSI sidebar from teasers
  • Simple demo mode with embedded question keys

Running the Demo

cd publisher-demo/client
pnpm install
pnpm dev
# Opens on http://localhost:3000

Assumptions

The publisher demo assumes:

  • Server-side React rendering
  • Teasers are rendered by the publisher (not via PSI iframe)
  • Teasers link to questions (not topics)
  • Question keys are stored in the CMS or embedded as content tags

Integration Architecture

graph TD
    subgraph "Broadcaster Site"
        PAGE[Article Page]
        TEASER[PSI Teaser Component]
        SIDEBAR[PSI Sidebar iframe]
        PSI_JS[psi.js / psi-sidebar.js]
    end

    subgraph "PSI System"
        FRONTEND[PSI Frontend]
        BACKEND[PSI Backend]
    end

    PAGE --> TEASER
    PAGE --> PSI_JS
    PSI_JS --> SIDEBAR
    SIDEBAR --> FRONTEND
    TEASER -->|"Click"| SIDEBAR
    TEASER -->|"Fetch metadata"| BACKEND

Possible Extensions

Beyond the basic integration, publishers can:

  • Add video teaser overlays at specific timestamps
  • Show teasers for topics in addition to questions
  • Pass a JWT to the sidebar for automatic SSO login
  • Use A/B testing to evaluate different teaser placements
  • Create custom modules for publisher-specific features

Further Reading