Skip to main content

Toplist Integration

This guide explains how to embed the Speakness toplist on your website. Toplists showcase the most engaging articles and comments from your publication based on reader votes. We offer two primary integration methods to suit your needs.

At a glance
  • Audience: Media teams and developers looking to highlight quality content.
  • Setup time: Minutes via script embed or WordPress plugin.
  • What you gain: Reader engagement showcase, content discovery, increased recirculation.

Overview​

The Speakness toplist enables you to:

  • Showcase reader-voted content across multiple quality dimensions
  • Display trending articles or comments based on configured criteria
  • Embed dynamically updating lists that refresh automatically
  • Highlight community engagement on your platform
  • Support multiple toplist types on the same site

Integration Methods​

MethodBest forHighlights
JavaScript EmbedCustom sites, headless CMS, static deploymentsDrop-in script, flexible placement, CMS-agnostic.
WordPress PluginWordPress-powered publicationsOne-click setup, per-post control, auto-embed option.

Understanding Toplist Types​

Speakness offers several toplist types based on different voting dimensions:

For News Articles​

  • Good Journalism: Articles voted as high-quality journalism
  • Good News: Articles voted as positive or uplifting news
  • Controversial News: Articles generating the most debate

For Opinion Articles & Comments​

  • Useful Opinions: Opinion pieces voted as insightful
  • Controversial Opinions: Opinions sparking debate
  • Useful Comments: Comments voted as valuable by readers
  • Controversial Comments: Comments generating discussion

How Reader Voting Works​

Readers can vote on articles and comments across three dimensions:

  1. Civil/Good Journalism: Is this content civil or well-reported?
  2. Useful/Good News: Is this content useful or positive?
  3. Agree: Do you agree with this perspective?

Your toplist displays ranked content based on these votes within your chosen timeframe and criteria.

Method 1: JavaScript Embed​

This method works with any website where you can add custom JavaScript code.

Step 1: Create a Toplist in Your Dashboard​

  1. Log in to your Speakness dashboard
  2. Navigate to your Media Dashboard
  3. Go to the Toplists section
  4. Click "Create New Toplist"
  5. Configure your toplist:
    • Type: Choose from Good Journalism, Good News, Controversial News, etc.
    • Items per list: How many items to display (e.g., 5, 10, 15)
    • Timeframe: Date range for ranking (e.g., last 7 days, last 30 days)
    • First item captivating: Whether to highlight the top item with special styling
    • Show article images: Display images with article entries
  6. Save your toplist and copy the unique key

This key identifies your specific toplist configuration and determines which content appears.

Step 2: Add the Embed Code to Your Website​

Add the following code to your website, replacing YOUR_UNIQUE_KEY with the key you copied from your dashboard:

<script src="https://www.speakness.com/embed-toplist-prod.js"></script>
<div id="toplist-embed" data-key="YOUR_UNIQUE_KEY"></div>

Example:

<script src="https://www.speakness.com/embed-toplist-prod.js"></script>
<div id="toplist-embed" data-key="abc123xyz456"></div>

Step 3: Choose Your Placement​

Place the embed code in your desired location:

Common Placements​

  • Sidebar widget area: Keeps top content always visible
  • Homepage sections: Feature trending articles prominently
  • Article pages: Show related popular content below the article
  • Footer areas: Engage readers at natural breakpoints
Best practices
  • Place above the fold on high-traffic pages for maximum visibility.
  • Create multiple toplists with different configurations (e.g., "Top Journalism" in sidebar, "Trending Comments" on homepage).
  • Test responsiveness on mobile devices where space is limited.

How It Works​

The JavaScript embed:

  1. Loads an iframe pointing to your toplist configuration
  2. Uses the data-key to fetch the correct toplist from Speakness
  3. Renders articles or comments based on your configuration
  4. Automatically adjusts iframe height to fit content
  5. Updates rankings in real-time as votes come in
  6. Tracks clicks for analytics in your dashboard

Method 2: WordPress Plugin​

For WordPress sites, we provide a dedicated plugin that makes integration seamless. The same plugin that handles comment sections also supports toplists.

Step 1: Download the Plugin​

  1. Log in to your Speakness dashboard
  2. Navigate to Settings > Integrations
  3. Click "Download WordPress Plugin"
  4. Save the .zip file to your computer

Step 2: Install the Plugin​

Option A: Upload via WordPress Admin​

  1. Log in to your WordPress admin panel
  2. Go to Plugins > Add New
  3. Click "Upload Plugin" at the top
  4. Click "Choose File" and select the Speakness plugin .zip file
  5. Click "Install Now"
  6. Click "Activate Plugin"

Option B: Upload via FTP​

  1. Extract the plugin .zip file
  2. Upload the extracted folder to /wp-content/plugins/
  3. Go to Plugins in WordPress admin
  4. Find "Speakness" and click "Activate"

Step 3: Configure the Plugin​

After activation:

  1. Go to Settings > Speakness
  2. Enter your Speakness API Key (found in your dashboard)
  3. Configure toplist settings:

General Settings​

  • Enable Toplists: Turn toplists on/off globally
  • Auto-embed: Automatically add toplists to posts
  • Placement: Choose where toplists appear (before/after content)

Manual Mode​

To add toplists to specific posts:

  1. Edit a post or page
  2. Scroll to the Speakness Toplist meta box
  3. Check "Enable Speakness Toplist"
  4. Select your desired toplist from the dropdown (configured in your Speakness dashboard)
  5. Publish or update the post

Step 4: Disable on Specific Posts​

To disable toplists on individual posts:

  1. Edit the post
  2. Find the Speakness Toplist meta box
  3. Uncheck "Enable Speakness Toplist"
  4. Update the post

Plugin Features​

The WordPress plugin provides:

  • One-click setup: No coding required
  • Automatic updates: Stay current with new features
  • Theme compatibility: Works with any WordPress theme
  • Per-post control: Enable/disable toplists per post or page
  • Auto-embed option: Automatically add to all posts or manual selection

Managing Toplist Configuration​

All toplist customization is done through your Speakness dashboard, not through embed code attributes. This centralized approach lets you:

  • Update configuration without changing code: Modify settings and the embedded toplist updates automatically
  • A/B test different configurations: Create multiple toplists and compare performance
  • Maintain consistency: Ensure all instances of a toplist display identically

Configurable Settings​

When creating or editing a toplist in your dashboard:

Toplist Type​

Choose what to rank:

  • Good Journalism
  • Good News
  • Controversial News
  • Useful Opinions
  • Controversial Opinions
  • Useful Comments
  • Controversial Comments

Display Settings​

  • Items per toplist: Number of entries to show (typically 5-20)
  • Timeframe: How far back to consider votes (e.g., 7 days, 30 days, all time)
  • First item captivating: Highlight the #1 item with larger styling
  • Show article images: Display thumbnail images for article entries

Multiple Toplists​

You can create multiple toplists for different purposes and embed them separately:

<!-- Sidebar: Top Journalism from last 7 days -->
<div id="toplist-embed" data-key="KEY_FOR_JOURNALISM_7D"></div>

<!-- Homepage: Trending comments from last 24 hours -->
<div id="toplist-embed" data-key="KEY_FOR_COMMENTS_24H"></div>

<!-- Footer: Controversial news from last 30 days -->
<div id="toplist-embed" data-key="KEY_FOR_CONTROVERSY_30D"></div>

Each toplist must have its own unique data-key from your dashboard configuration.

After Integration​

Verify the Embed​

Once you've added the toplist to your website:

  1. View your page: Visit the page where you embedded the toplist
  2. Check rendering: Confirm the toplist displays correctly
  3. Test clicks: Click on articles/comments to ensure links work
  4. Mobile check: View on mobile devices to verify responsive design
  5. Height adjustment: Confirm the iframe resizes properly for all content

Monitor Performance​

Track toplist engagement from your Speakness dashboard:

  • Click-through data: See which toplist items generate the most clicks
  • Top-performing content: Identify articles and comments that consistently rank
  • Engagement trends: Understand which toplist types resonate with readers
  • Vote patterns: Analyze voting behavior across dimensions

Content Strategy Insights​

Use toplist data to inform editorial decisions:

  • Identify quality markers: See what readers consider "Good Journalism"
  • Understand preferences: Learn which topics generate useful discussion
  • Guide coverage: Focus on content that earns reader trust
  • Reward engagement: Highlight top commenters and discussions
  • Promote positivity: Feature "Good News" to balance coverage

Troubleshooting​

Toplist Not Appearing​

  1. Verify your key: Ensure the data-key is copied correctly from your dashboard
  2. Check browser console: Look for JavaScript errors or network issues
    • Open Developer Tools (F12) and check the Console tab
    • Look for red error messages related to Speakness or the toplist
  3. Confirm element ID: The div must have id="toplist-embed"
  4. Validate script URL: Ensure the script tag is correct: https://www.speakness.com/embed-toplist-prod.js
  5. Check network requests: In DevTools Network tab, verify the iframe loads from Speakness

No Data / Empty Toplist​

  1. Insufficient votes: The toplist may be empty if articles haven't received enough votes yet
  2. Timeframe too narrow: If configured for "last 24 hours" but no recent activity, try a longer timeframe
  3. Wrong toplist type: Ensure articles match the type (e.g., News articles for "Good Journalism")
  4. Key mismatch: Verify the key matches an active toplist in your dashboard

Height Not Adjusting​

  1. postMessage blocked: Ensure your site allows iframe communication
  2. Content Security Policy (CSP): Check that CSP headers allow Speakness domain
    • Add frame-src https://www.speakness.com to your CSP policy
  3. JavaScript conflicts: Other scripts may interfere with message listeners
  4. Browser console errors: Check for postMessage-related errors

Styling Issues​

The toplist renders inside an iframe, which limits styling conflicts but also customization:

  1. Width issues: The iframe takes 100% width of its container - adjust the parent div
  2. Spacing problems: Add margins/padding to the #toplist-embed div, not the iframe
Fast debugging
  • Open browser DevTools Network tab to verify both script and iframe load successfully.
  • Check Console for CORS or mixed-content (HTTP/HTTPS) errors.
  • Test in an incognito window to rule out browser extensions.
  • Try the embed code on a simple HTML test page to isolate the issue.

Multiple Toplists Not Working​

When embedding multiple toplists:

  • Each must have a unique data-key
  • Each must have a unique id attribute on the div
  • The script only needs to be included once per page

WordPress Plugin Issues​

  1. Plugin won't activate: Check WordPress version compatibility (requires WordPress 5.0+)
  2. Toplist not appearing: Ensure the plugin is activated, API key is configured, and toplist is enabled in the post settings
  3. Meta box missing: Check that your user role has permissions to edit posts and that the meta box isn't hidden (check Screen Options at top of post editor)
  4. API key invalid: Copy the key directly from your Speakness dashboard settings
WordPress debugging
  • Temporarily disable other plugins to check for conflicts.
  • Clear WordPress cache after making changes.
  • Check that toplists are enabled globally in Settings > Speakness.
  • Verify the toplist configuration exists in your Speakness dashboard.

Best Practices​

Placement Strategy​

  • Homepage: Feature prominently above the fold to drive recirculation
  • Article pages: Place in sidebar or below article content
  • Multiple toplists: Create different configurations for different pages (e.g., "Top Journalism" on homepage, "Trending Comments" on article pages)
  • Mobile-first: Test on mobile devices where most readers access content

Content Quality​

High-quality toplists depend on quality engagement:

  • Moderate actively: Remove spam and bad-faith comments to keep votes meaningful
  • Encourage voting: Educate readers about the voting dimensions
  • Set clear guidelines: Publish community standards for commenting and voting
  • Engage authentically: Respond to top comments to encourage quality participation
  • Feature winners: Highlight top-ranked content in newsletters or social media

Technical Implementation​

  • Use HTTPS: Always serve your site over HTTPS
  • Configure CSP: Add frame-src https://www.speakness.com to Content Security Policy headers
  • Monitor performance: Check your dashboard regularly for engagement metrics
  • Secure keys: Never commit toplist keys to public repositories
  • WordPress users: Keep the Speakness plugin updated for the latest features and security patches

Voting Strategy​

Different toplist types serve different purposes:

  • Good Journalism: Builds trust by showcasing quality reporting
  • Good News: Provides balance and highlights positive coverage
  • Controversial: Surfaces important debates (use with strong moderation)
  • Useful Comments: Rewards thoughtful community participation
  • Agree/Disagree: Shows opinion distribution (be careful with polarization)

SEO Considerations​

  • Toplist content renders in an iframe and isn't crawled by search engines
  • Use toplists for engagement and recirculation, not SEO
  • The original article pages still provide full SEO value
  • Consider complementing toplists with server-rendered "Popular Articles" sections for SEO

Support​

Need help with toplist integration?

  • Documentation: Check this guide and other documentation
  • Email Support: support@speakness.com
  • Dashboard: Access help resources from your Speakness media dashboard

FAQ​

Can I style the toplist to match my site?​

The toplist renders in an iframe, which provides security and consistency but limits custom styling.

How often does the toplist update?​

Toplists update in real-time as votes come in. Rankings may shift within minutes of new voting activity.

What if I don't have enough votes yet?​

Start by using a longer timeframe (e.g., 30 days or all-time) to ensure sufficient data. As engagement grows, you can switch to shorter windows like 7 days or 24 hours.

Can I exclude specific articles or comments?​

Moderation actions in your dashboard affect toplist rankings. Hidden or removed content won't appear in toplists.

Do I need to update my embed code when I change settings?​

No! All configuration is managed through your dashboard. Changes take effect immediately without code updates.

Can I track which toplist drives the most clicks?​

Yes, your Speakness dashboard provides analytics on toplist performance, including click-through rates and engagement metrics.

Can I use different toplists on different WordPress posts?​

Yes! When editing a post, you can select which toplist configuration to display from the Speakness Toplist meta box dropdown. Create multiple toplist configurations in your Speakness dashboard, then choose the appropriate one for each post.

Can I automatically add toplists to all posts?​

Yes, enable the "Auto-embed" option in Settings > Speakness. You can still disable toplists on individual posts using the meta box if needed.