內容簡介
The Canary Events Display 外掛專為希望在網站上顯示 The Canary Events 活動的用戶設計。它能夠同步活動資訊至 WordPress，並透過響應式短碼或選擇性的本地活動頁面進行呈現。
【主要功能】
• 測試 API 連接並同步活動資訊
• 支援手動或定時每 4、8、12 或 24 小時同步
• 下載活動海報至 WordPress 媒體庫
• 使用 [canary_events] 短碼顯示活動
• 選擇性顯示本地活動頁面或原始活動頁面
• 自動依據使用者語言顯示管理介面
外掛標籤
開發者團隊
原文外掛簡介
The Canary Events Display is made for websites that want to display events from The Canary Events. It synchronizes event information into WordPress and renders it with responsive shortcodes or optional local event pages.
After an administrator configures an account email and API secret, the plugin can:
Test the authenticated API connection.
Synchronize new, updated, and removed events.
Store all available English, Spanish, German, and French event translations locally in WordPress.
Automatically display the translation matching the current page language, with a configurable default-language fallback.
Optionally include events liked or saved by the connected account.
Run manual, full, or scheduled synchronization every 4, 8, 12, or 24 hours.
Synchronize ordered event image galleries to the WordPress Media Library, with SHA-256 verification and reuse/deduplication when the API supplies hashes.
Display synchronized events with [canary_events] in a Gutenberg Shortcode block or other shortcode-compatible area.
Open event cards on The Canary Events by default, or optionally use local synchronized event pages.
Display all synchronized attendance dates and times in HH:MM format.
Filter shortcode output by island, category, upcoming/past status, layout, columns, and other display options.
Optionally show a The Canary Events attribution as text, image, or text + image. Attribution is disabled by default.
The legacy [canary_artist_events] shortcode remains supported for existing sites.
External service
This plugin relies on the external The Canary Events service to retrieve event data. The service is operated by The Canary Events, the plugin author.
Service: The Canary Events
The plugin does not contact The Canary Events merely because it is activated. A site administrator must configure credentials and then test/synchronize the connection, or explicitly enable automatic synchronization.
When a connection test or synchronization runs, the plugin sends the following to https://thecanaryevents.com/json/canary-events/v1/events over HTTPS:
The configured account email in the X-CEM-User HTTP header.
The configured API secret in the X-CEM-Secret HTTP header.
The configured default event language (en, es, de, or fr) as the backward-compatible lang parameter. The API response still includes all available EN/ES/DE/FR event translations.
Synchronization options such as liked=1, full=1, or event_id when the corresponding feature is used.
A custom User-Agent containing the plugin name and version. It does not include the WordPress site URL.
The API returns event information that the plugin stores in private WordPress records. When the API supplies an ordered images manifest, each entry may be a legacy HTTPS URL string or an object containing url and sha256. The plugin may make separate HTTPS requests from the WordPress server to those image hosts to download files into the Media Library. Supplied SHA-256 values are verified against the exact downloaded bytes before the synchronized gallery is replaced. Those remote hosts can receive standard request information such as the server IP address and HTTP headers.
Service policies:
The Canary Events Privacy Policy
The Canary Events Terms & Conditions
Shortcode
Basic event grid:
[canary_events]
Four events in two columns:
[canary_events limit="4" columns="2"]
Compact list without images:
[canary_events layout="compact" show_image="no"]
Tenerife events only:
[canary_events island="tenerife"]
Past events only:
[canary_events show_only_past="yes" order="desc"]
Detailed cards:
[canary_events limit="8" columns="4" show_description="yes" description_length="120"]
Force one supported event language when needed:
[canary_events language="fr"]
Supported attributes include limit, columns, layout, show_past, show_only_past, show_image, show_category, show_location, show_date, show_time, show_price, show_description, description_length, button_text, order, island, category, language, lang, and class. By default, language="auto" detects the current page language.
When show_date="yes", all synchronized dates returned for the event are displayed. show_only_past="yes" takes precedence over show_past.
Multilingual event display
The Canary Events API returns event content in English (en), Spanish (es), German (de), and French (fr). The plugin stores all available translations locally during synchronization, including localized event titles, descriptions, event URLs, translated slugs, and per-occurrence URLs.
On the front end, the plugin detects the language of the current page. If the page uses en, es, de, or fr, the matching local event translation is displayed. If the page uses another language, such as Dutch (nl), the plugin displays the language configured under The Canary Events > Settings > Default Event Language.
If an individual event does not contain the requested translation, the same configured default language is used. If that translation is also unavailable, the plugin uses the first available locally stored translation and finally the legacy synchronized fields as a last fallback.
Changing the Default Event Language does not require downloading separate language feeds because all supported translations are stored locally. After upgrading from a version earlier than 1.0.20, run Full Synchronization once to populate translations for events that were already imported.
Ordered image synchronization
The plugin supports both legacy image arrays containing URL strings and the preferred ordered image manifest containing objects with url and a lowercase 64-character sha256. The array order is authoritative and the first synchronized image becomes the featured image.
When hashes are present, existing local media is matched by SHA-256 before source URL, so a changed source URL does not force a redownload when the bytes are unchanged. Legacy URL-only entries continue to work; after a successful download the plugin calculates and stores the local SHA-256 for later deduplication.
If the API omits the images field, the current synchronized images are preserved. An explicit images: [] removes the synchronized image set. A supplied non-empty array is treated as a complete ordered replacement. New files are downloaded and validated first, and the event gallery is switched only after every required download succeeds. Replaced plugin-managed media is deleted only when it is no longer referenced by another synchronized event. Manually selected media is not deleted.
The Events screen and synchronization log report image states including Preserved, Unchanged, Reordered, Queued/Downloading, Complete, and Error, together with reused and newly downloaded counts.
Local event pages
By default, event buttons open the original event page on The Canary Events.
A local URL such as /events/2195/event-slug.html can be selected from The Canary Events > Settings > Event Links.
Local event pages and optional The Canary Events attribution are independent settings. The plugin does not require a public credit or external link in order to use local event pages.
A local page can display the synchronized poster, full description, all synchronized dates, times, location, price, organizer information, and event links.
If local event URLs return 404 after activation or migration, open Settings > Permalinks and click Save Changes once to refresh rewrite rules.
Optional attribution
Frontend attribution is disabled by default. An administrator can explicitly enable it under The Canary Events > Settings.
When enabled, the administrator can choose:
Text
Image
Text + image
and Left, Center, or Right alignment. If several event shortcodes appear on the same page, the plugin keeps only the final enabled attribution visible.
Privacy
The account email is stored in the WordPress Options API. The API secret is encrypted at rest using Sodium secretbox when available, with OpenSSL AES-256-GCM as a fallback, using keys derived from WordPress authentication salts.
The plugin does not expose the API secret in frontend HTML, JavaScript, REST responses, or synchronization logs. The WordPress Privacy Guide receives suggested disclosure text describing the external API and synchronized-image download and verification behavior.
The plugin itself does not add analytics, advertising, tracking pixels, or telemetry.
Security
Manual actions require the manage_options capability and WordPress nonces.
API credentials are transmitted only over HTTPS.
Remote API and synchronized-image requests use the WordPress safe HTTP API.
API responses and HTTP status codes are validated before processing.
Temporary HTTP 429 and 5xx responses use controlled retry behavior.
Synchronized image downloads are streamed to temporary files, limited to supported image MIME types and 8 MB each, and SHA-256 is checked before replacement when supplied by the API.
Synchronized events use external_id as the permanent upsert key when supplied, with legacy portal/event-ID lookup retained only for migration/backward compatibility.
A synchronization lock prevents overlapping synchronization runs.
Bundled assets
The bundled The Canary Events logo in assets/images/the-canary-events-logo.png is provided by The Canary Events and distributed with this plugin under GPLv2 or later.
