Using HArvest

WordPress

Install the HArvest WordPress plugin, configure it with your HA URL, then use shortcodes to embed widgets on any page or post.

On this page
  1. Requirements
  2. Installation
  3. Plugin settings
  4. Shortcodes
  5. Content Security Policy
  6. Script loading

Requirements

RequirementVersion
WordPress5.0+
PHP7.4+ (8.0+ recommended)
EditorClassic Editor or any page builder that allows raw HTML

The plugin works with any WordPress theme. It enqueues the widget script in the page footer and injects the required Content-Security-Policy header automatically.

Installation

  1. 1

    Download the plugin

    Download the latest release zip from GitHub Releases. Inside the zip, find harvest.zip in the wordpress/ folder. This is the WordPress plugin.

  2. 2

    Upload to WordPress

    In your WordPress admin, go to Plugins > Add New > Upload Plugin. Select the ZIP file and click Install Now, then Activate Plugin.

  3. 3

    Configure the plugin

    Go to Settings > HArvest and enter your Home Assistant external URL. Save the settings.

Plugin settings

Found at Settings > HArvest in your WordPress admin.

SettingDescription
Home Assistant URL Required. Your HA external HTTPS URL. e.g. https://myhome.duckdns.org. Used to set the connect-src Content-Security-Policy directive automatically and as the default HA URL for shortcodes.
Widget JS source Two options:
  • HA-served (recommended, default) - the widget JS is fetched from your Home Assistant instance at {your-HA-URL}/harvest_assets/harvest.min.js. Updating HArvest via HACS automatically updates the widget on every WordPress page. Requires the Home Assistant URL field above to be set (the radio is disabled otherwise).
  • Custom URL - point at a self-hosted copy of harvest.min.js. For staging environments or your own CDN. Accepts full URLs (https://example.com/harvest.min.js), absolute paths (/harvest.min.js), and relative paths or bare filenames (harvest.min.js) for HTML files served alongside the script.

Live URL reachability check

As you type or change either URL field, the plugin probes the URL from the WordPress server and shows a small status indicator next to the field:

  • ✓ (green) - the URL responded with HTTP 2xx. Reachable.
  • ⚠ (amber) - the URL did not respond, or returned a 4xx/5xx. Doesn't necessarily mean the widget will fail for visitors: your visitors may be on a different network than your WordPress server (e.g. a LAN-hosted Home Assistant). Save anyway if you know the URL is correct from a visitor's perspective.
  • ⓘ (amber) - the URL is a relative path or bare filename. Cannot be probed from the server side because it only resolves against the visitor's embed page; you'll need to verify it manually.
  • ✗ (red) - the URL is malformed or uses a disallowed scheme (javascript:, data:, etc.). The plugin will refuse to enqueue it.

The check is informational only and never blocks save.

Shortcodes

[harvest] - single card

Embeds a single widget card for one entity.

[harvest token="hwt_..." entity="light.bedroom_main"]
ParameterRequiredDescription
tokenYesWidget token ID from the HArvest panel
entityYes*HA entity ID. e.g. light.bedroom_main
aliasYes*8-character alias instead of entity ID. Use entity OR alias, not both.
token-secretNoHMAC signing secret, required when the token has HMAC authentication enabled
Tip

The HArvest panel's Code section generates the exact shortcode for each entity - you don't need to type these manually. Just copy and paste.

[harvest_group] - multiple cards

Groups multiple [harvest] shortcodes together, sharing a token and HA URL. Equivalent to wrapping cards in an <hrv-group> element.

[harvest_group token="hwt_..."]
  [harvest entity="light.living_room"]
  [harvest entity="light.dining_room"]
  [harvest entity="switch.lamp"]
[/harvest_group]
ParameterRequiredDescription
tokenYesToken ID shared by all cards in the group
token-secretNoHMAC secret shared by all cards in the group

When using [harvest_group], child [harvest] shortcodes do not need token - they inherit it from the group.

Using aliases

For security by obscurity, use the alias format. Aliases are generated in the HArvest panel and stored with the token. The panel's Code section shows both formats.

[harvest token="hwt_..." alias="dJ5x3Apd"]

Rendered output

The shortcodes render as a <div class="hrv-mount"> element with the appropriate data-* attributes. The widget script mounts an <hrv-card> custom element inside each mount div at runtime. The script is enqueued in the page footer (once per page, regardless of how many shortcodes are on the page).

Content Security Policy

Browsers require a connect-src Content-Security-Policy directive to allow WebSocket connections from your WordPress page to your HA instance. The plugin injects this header automatically based on the HA URL you entered in the plugin settings.

The injected header looks like:

Content-Security-Policy: connect-src 'self' wss://myhome.duckdns.org

The plugin converts the https:// URL from settings to wss:// for the directive. You don't need to add this manually.

Existing CSP headers

If your WordPress host or another plugin already sets a Content-Security-Policy header, the HArvest plugin's header may be ignored or conflict. In that case, manually add wss://your-ha-host to your existing connect-src directive.

The plugin also allows JSON file uploads in the WordPress media library (admin users only) to make it easier to manage and import custom theme files.

Script loading

The widget script (harvest.min.js) is loaded in the page footer via WordPress's wp_footer action. It's only enqueued once per page even if multiple shortcodes are present.

The script handle is harvest-widget. If you need to reference it from another plugin or theme (e.g. to add a dependency), use this handle.