Publishing Options

Whether you are working with a classic site, a block-based theme, or a headless setup, BrightTally provides multiple publishing paths. Choose the method that matches your workflow.

1. WordPress Shortcode

The shortcode works everywhere WordPress renders content: posts, pages, reusable blocks, and even widget areas that support shortcodes.

[bright_tally id="your-poll-slug"]

Optional attributes

2. Block Editor (Gutenberg)

1. Open the block inserter and search for BrightTally Poll.
2. Paste the poll slug (or ID) into the block inspector.
3. Toggle Show results or Dark theme without leaving the editor.

Coming soon: Forms will appear inside the same block with an option to switch between poll and form modes as soon as your workspace receives forms access.

3. Legacy Widget Areas

If your theme exposes widget areas, add a Custom HTML widget and drop in the shortcode. The plugin automatically queues the required JavaScript for the front-end.

Tips for Editors

• Use the Get Shortcode button inside BrightTally → Polls to copy a pre-configured shortcode.
• Pair polls with call-to-action buttons by wrapping the shortcode in a .wp-block-group to apply background colors or padding.
• Need to feature multiple polls? Each shortcode outputs an isolated iframe, so you can stack them safely on a single page.

Managing Forms (Beta)

Forms share the same shortcode syntax. When forms are enabled for your plan, each form receives a slug that you can embed just like polls:

[bright_tally id="contact-form-2025"]

You can mix forms and polls on the same page. Forms still respect the width attribute; use % values for responsive layouts.

Keeping Content in Sync

• Automatic refresh: The plugin fetches the freshest data whenever an editor opens the Polls screen.
• Manual refresh: Click Refresh inside the Polls dashboard to pull the latest titles, descriptions, and status labels.
• Caching on the front-end: BrightTally caches embed payloads for a few minutes to protect your site from spikes. Updates usually show up in seconds, but allow up to 2 minutes for high-traffic sites.

Troubleshooting Embeds

Common Issues

Poll Not Displaying

Problem: Poll doesn't appear on the page after embedding the shortcode.

Solutions:

1. Verify the poll is in Published or Live status inside BrightTally (not Draft or Closed).
2. Check the poll slug/ID is correct in the shortcode: [bright_tally id="correct-slug"]
3. Clear any page caching plugin (WP Super Cache, W3 Total Cache, etc.) and refresh the page.
4. Check browser console for JavaScript errors (F12 → Console tab).
5. Ensure your WordPress theme supports shortcodes in the content area.

Voting Not Working

Problem: Poll displays correctly, but votes don't register when users click vote buttons.

Solutions:

1. Check Browser Console

   • Open browser Developer Tools (F12)
   • Go to the Console tab
   • Look for errors prefixed with [Embed] - these indicate embedding issues
   • Look for 419 errors (CSRF token expired) or 403 errors (permission denied)

2. Check Network Tab

   • Open browser Developer Tools (F12)
   • Go to the Network tab
   • Click a vote button and look for a POST request to /livewire/update
   • Check the request status:
     • 200: Request succeeded (check response for errors)
     • 419: CSRF token issue (session cookies not working)
     • 403: Permission issue
     • 500: Server error (check BrightTally logs)

3. Session Cookie Issues (Most Common)

   Embedded polls require session cookies to function properly. If voting isn't working:

   • Check Cookie Settings:

     • Open Developer Tools (F12) → Application tab → Cookies
     • Look for a cookie named brighttally_session (or your session cookie name)
     • Verify it has:
       • SameSite=None (required for cross-origin iframes)
       • Secure=true (for HTTPS sites) or Secure=false (for localhost)

   • Browser Third-Party Cookie Settings:

     • Some browsers block third-party cookies by default
     • Chrome: Settings → Privacy → Third-party cookies → Allow all cookies (or add exception)
     • Firefox: Settings → Privacy → Cookies → Accept cookies from sites
     • Safari: Safari → Preferences → Privacy → Uncheck "Prevent cross-site tracking"

   • Test Direct URL:

     • Visit the poll directly: https://brighttally.com/poll/your-poll-slug
     • If voting works there but not when embedded, it's a cookie/session issue

   • Clear Cookies and Try Again:

     • Clear all cookies for the BrightTally domain
     • Refresh the embedded poll page
     • Try voting again

4. HTTPS Requirement

   • Embedded polls require HTTPS on both WordPress site and BrightTally (except localhost)
   • Ensure your WordPress site uses HTTPS
   • If testing locally, ensure BrightTally uses http:// (not https://) for local development

5. Content Security Policy (CSP)

   • Check if your WordPress site or hosting provider has strict CSP headers
   • Ensure frame-ancestors allows embedding
   • Allow https://brighttally.com in your CSP policy

6. Plugin Conflicts

   • Temporarily disable other WordPress plugins to test for conflicts
   • Common culprits: security plugins, caching plugins, ad blockers

7. Check Livewire Request

   • In Network tab, find the /livewire/update request
   • Check Request Headers:
     • X-CSRF-TOKEN should be present
     • X-Requested-With: XMLHttpRequest should be present
     • Cookie header should include session cookie
   • Check Response:
     • Should return JSON with updated component data
     • Look for effects.updates array (indicates successful update)

Stale Responses

Problem: Vote counts or poll results don't update after voting.

Solutions:

• Clear any page caching plugin and click Refresh on the Polls screen in WordPress admin.
• BrightTally caches embed payloads for a few minutes. Updates usually show up within seconds, but allow up to 2 minutes for high-traffic sites.
• Refresh the WordPress page to see updated results.
• Check if poll results are set to show immediately (some polls hide results until after voting).

Permission Errors

Problem: Editor can't embed polls or sees permission errors.

Solutions:

• Editors need at least a Contributor role in BrightTally to embed polls. Review Roles, plans & access levels for specifics.
• Ensure the WordPress user is connected to the correct BrightTally account.
• Check BrightTally team permissions - user must have access to the poll's team.

419 "Page Expired" Error

Problem: Users see a "419 Page Expired" error when voting.

Solutions:

• This indicates CSRF token expiration or session cookie issues.
• Follow the "Session Cookie Issues" troubleshooting steps above.
• Ensure both WordPress and BrightTally sites are on HTTPS (or both on HTTP for localhost).
• Check browser third-party cookie settings (see above).

Iframe Not Loading

Problem: Poll area is blank or shows "Content blocked" message.

Solutions:

• Check browser console for iframe loading errors.
• Verify Content Security Policy allows iframes from brighttally.com.
• Check WordPress site's .htaccess for iframe restrictions.
• Some WordPress security plugins block iframes - check plugin settings.

Getting Help

If none of these solutions work:

1. Collect Debug Information:

   • Browser console errors (F12 → Console)
   • Network request details (F12 → Network → find /livewire/update request)
   • Cookie settings (F12 → Application → Cookies)
   • WordPress plugin list (to check for conflicts)

2. Contact Support:

   • Email: hello@brighttally.com
   • Include the debug information above
   • Mention you're embedding in WordPress

3. Test Direct URL:

   • Always test the poll directly at https://brighttally.com/poll/your-slug
   • If it works there but not when embedded, include this information in your support request