affilinode for Discourse

Theme component for Discourse forums, for use with an affilinode account. Version 1.0.0 · License: MIT (see LICENSE) · Repository: https://git.valitype.com/affilinode/affilinode-discourse

Deutsch · English

What it does

• Insert product in the composer: a shopping-cart button in the composer toolbar. The dialog searches your affilinode catalogue (cards with image, title, brand, best price and number of offers), works with the keyboard (up/down, Enter, Ctrl+Enter) and shows a live preview of the box. Layouts: product box, compact, button, price comparison and comparison (2-6 products). A shortcode is inserted as its own paragraph.
• Preview in the composer: shortcodes and product links appear as placeholders ("Product box: Nordwave X5") – real boxes only show in the published post, nothing is counted while you write.
• Links become product boxes: supported product links in posts (Amazon, eBay, Awin deep links and shop pages that affilinode knows as an offer) show a product box with a price comparison – using the affiliate links of your affilinode account.
• Matching the topic: once per topic a box shows products from your catalogue that match the topic (Publisher plan).
• Fits the forum: with theme = auto the boxes use the forum's colours and follow its light/dark colour scheme.
• Notices for the team instead of silent failures: if the key is missing, the domain is not allowed or a plan feature is missing, admins and moderators see a small dismissible notice with a link to the solution. Visitors see nothing.

It is a theme component, not a plugin: it installs without restarting the server, also on hosted forums. Discourse 3.4 or newer is required.

Setup in four steps

1. Create a key: in the affilinode dashboard open Integrations → Discourse, create an embed key and enter the domain of your forum (e.g. forum.example.com). (Equivalent: Websites → your website → Embedding → add domains → Create key.)
2. Install the component: in Discourse go to Admin → Customize → Themes → Install → From a Git repository and enter https://git.valitype.com/affilinode/affilinode-discourse. Alternatively download affilinode-discourse-<version>.zip from the repository's releases and upload it under Install → From your computer. Then add the component to the themes your forum uses.
3. Enter the key: in the component settings enter your embed key (affilinode_key) and save. Without a key the component loads nothing – admins see a notice until then.
4. Test it: write a post with an Amazon link on its own line, e.g. https://www.amazon.de/dp/<ASIN of a product in your catalogue>. The published post shows the product box. Or click the shopping cart in the composer, search a product and insert it. If a notice says requests from your domain are refused, the domain is missing on the key (step 1).

Help: https://affilinode.com/hilfe/discourse

Settings

The order matches the view in Discourse; every description starts with its group.

Setting	Default	Effect
affilinode_key	empty	Start: embed key from the affilinode dashboard
links_mode	box	Links: box = product box, compact = single line, off = leave links alone
links_max_per_post	3	Links: maximum number of boxes created from links per post
min_trust_level_for_links	0	Links: only convert links from this trust level on (spam protection); staff always
shortcodes	on	Shortcodes: show shortcodes as boxes (required for "Insert product")
min_trust_level_for_shortcodes	0	Shortcodes: only convert shortcodes from this trust level on; staff always
composer_button	toolbar	Composer: toolbar = button in the toolbar, menu = in the gear menu, off = hidden
context_enabled	off	Matching products: once per topic
context_after_post	1	Matching products: after which post (shorter topics: after the last post)
context_limit	3	Matching products: number of products
context_title	empty	Matching products: own heading; empty = "Matching this topic"
theme	auto	Look: auto = forum colours (follows light/dark), light, dark = affilinode's own look
accent	empty	Look: accent colour; empty = forum accent colour (auto) or affilinode default
price_age	relative	Prices: "Price updated 2 hr. ago" per offer – relative, datetime or off
price_max_age	24	Prices: hide older prices (hours; Amazon never above 24, eBay 6); per box max_age=
excluded_categories	empty	Exclusions: categories without boxes and matching products, subcategories included
staff_notices	on	Staff: notices for admins/moderators when affilinode cannot show anything
api_base	https://api.affilinode.com	Advanced: address of the API – only change on request of support
extend_content_security_policy	script_src/connect_src for the API	Advanced: see below

Never converted: private messages, hidden and deleted posts and – according to the affilinode embed – links in quotes, code and signatures. If a link is alone in its paragraph (bare URL, onebox preview) the box replaces the paragraph; otherwise the box follows the paragraph and the link stays.

Links and shortcodes have their own trust level; posts by staff are always converted. Custom labels in shortcodes (text, title, button, badge) only apply in staff posts – everywhere else the box shows its standard texts, so nobody can put a "free download" button on an affiliate link.

Content Security Policy: since version 3.3 (strict-dynamic) Discourse allows scripts that a theme component loads without further entries. The preset script_src entry is only meant for forums that switched strict-dynamic off. If you change api_base, enter the same address there.

Shortcodes

Layout in the dialog	Shortcode
Product box	[affilinode_product id=…]
Compact	[affilinode_product id=… template=compact]
Button	[affilinode_button id=…]
Price comparison	[affilinode_offers id=… packs=tabs]
Comparison (2-6)	[affilinode_compare ids=a,b,c]

Under "More boxes …" all other box types of the embed are available. Depending on the box, the dialog searches a product or asks for details (product type, field, system, list or advisor ID):

Layout in the dialog	Shortcode
Product card	[affilinode_product id=… template=card]
Several products (1-6)	[affilinode_products ids=a,b]
"A vs B" (2-3)	[affilinode_versus ids=a,b]
Spare parts	[affilinode_spare_parts id=…]
Accessories	[affilinode_accessories id=…]
Compare picker	[affilinode_compare_picker type=smartphone]
Deals	[affilinode_deals type=smartphone min=15]
Price history	[affilinode_price_history id=… days=180]
Device + tariffs	[affilinode_tariffs id=…]
Pack sizes	[affilinode_packs id=… sort=unit]
Test rating	[affilinode_rating id=…]
At a glance	[affilinode_glance id=…]
Running costs	[affilinode_energy id=… years=10]
Alternatives	[affilinode_alternatives id=… kinds=cheaper]
Text link (in a sentence)	[affilinode_link id=… text="cheap at Amazon" price=1]
Single value (in a sentence)	[affilinode_field id=… field=price]
Best-of list	[affilinode_list id=<list ID>]
Product search	[affilinode_search type=smartphone]
Product advisor	[affilinode_advisor id=<advisor ID>]
Compatibility check	[affilinode_compat system=hub:zigbee2mqtt product=…]
Best in category	[affilinode_top type=smartphone by=value]
Price-performance chart	[affilinode_scatter type=smartphone field=battery_capacity]
Vouchers	[affilinode_coupons merchant=Gartenhaus kind=code]
"Back in stock"	[affilinode_stock_alert id=…]

Vouchers below a product box or card: choose "Vouchers of the merchants below" (coupons=1, up to three vouchers from merchants that have an offer for the product). The voucher box itself needs no details (all current vouchers); with a product only the merchants that offer it.

"Back in stock": while the product is unavailable at every shop except Amazon, readers enter their email address and receive one email as soon as it is available again (double opt-in, unsubscribe link in every email). As its own box or below a product box or card (stock_alert=1). Off by default: the feature must be switched on for the website in the affilinode dashboard; with an Amazon shop in the account it stays off.

The dialog inserts a text link and a single value at the cursor inside a sentence, everything else as its own paragraph. More attributes can be added by hand; the affilinode dashboard ("Integrations" → "Insert product", tab "Discourse") builds the finished shortcode with all options and a preview.

The component writes values without quotation marks – Discourse would otherwise turn " into typographic quotes (the embed understands those as well).

"A vs B": two or three products side by side – a verdict per area (battery, display, performance …) based only on data-sheet values, the values next to each other with the better one highlighted, "Who should buy which", prices and frequently asked questions (faq=0 hides them). In posts, [affilinode_versus a=… b=…] works too.

Changelog

• 1.0.0 – First public release. MIT license, installation also via ZIP file, guide in German and English. Features as in 0.9.0.
• 0.9.0 – Security: own setting min_trust_level_for_shortcodes (default 0) – below it the embed does not convert shortcodes in a post (no placeholders in the composer preview either). Custom labels (text, title, button, badge) only from staff posts. Needs the current embed.
• 0.8.0 – Price freshness: settings price_age ("Price updated … ago" per offer: relative, date or off) and price_max_age (hide older prices, button "Check current price"); shortcodes understand max_age= and price_age=. Needs the current embed.
• 0.7.0 – "A vs B": box under "More boxes …" with two or three products ([affilinode_versus ids=a,b]), "Frequently asked questions" option, placeholders in the composer preview also for a=… b=… c=….
• 0.6.0 – "Back in stock": box under "More boxes …" ([affilinode_stock_alert id=…]) and notification below product box and card (stock_alert=1). Setting of the website, off by default.
• 0.5.0 – Vouchers: box under "More boxes …" ([affilinode_coupons]) and vouchers below product box and card (coupons=1); placeholders in the composer preview.
• 0.4.0 – Pack sizes: new box (cheapest offer per size with price per piece and saving) and the "Pack sizes" option for the price comparison.
• 0.3.0 – "Insert product" with all box types of the embed ("More boxes …"), with details per box and live preview; placeholders in the composer preview for all of them.
• 0.2.0 – Insert product with live preview, placeholders in the composer preview, forum colours, notices for the team.

Privacy

• The boxes are loaded in the visitors' browsers – from api.affilinode.com, without cookies (credentials: omit). As with any embedded resource the server sees the IP address and the address of the forum (referrer).
• Links: only the addresses of the links in a post are sent, not the text.
• Matching the topic: title, category, tags and the beginning of the first posts (at most 2,000 characters) and the address of the topic without parameters are sent – no user names, no visitor data.
• Insert product: only the search term is sent. The preview in the composer loads nothing from affilinode.
• affilinode stores neither links nor texts; results are cached for ten minutes.
• "Back in stock" (only if switched on): the email address a reader enters is stored by affilinode on your behalf (data processing) together with product, language, country and page – until the one notification or unsubscribing, then at most 30 days; unconfirmed entries expire after 7 days. Add this to your privacy policy.
• Mention affilinode in your privacy policy as a service that provides product data.

Advertising disclosure

The boxes label themselves ("Ad") and carry the affiliate notice. In addition, point out in your forum (e.g. in the FAQ or guidelines) that product links can turn into affiliate links.

Limits

• The boxes are created in the browser. Search engines and email notifications only see the original post with the link or shortcode text.
• Short links (e.g. amzn.to) are not resolved.
• The live preview in the "Insert product" dialog is a real box and counts towards the API quota like an ad.
• "Matching the topic" is included in the Publisher plan; in other plans the box stays empty (admins see a notice).
• Every request counts towards the API quota of your plan.

Development

• Logic without Discourse (settings → options, filters, search dialog, shortcodes, notices): npm test (node --test, Node 22 or newer).
• Theme tests (QUnit) in test/: in a Discourse development setup in the browser under /theme-qunit or with rake "themes:qunit[name,affilinode]".
• Converting links and shortcodes and drawing the boxes is done by affilinode's embed.js; the component only calls its JavaScript API (window.affilinode.scan(element), window.affilinode.context(element, options), window.affilinode.refresh()) and listens for the affilinode:error event.
• Layout: javascripts/discourse/api-initializers/affilinode.js (posts, composer preview, button), components/modal/affilinode-product-search.gjs (search dialog), components/affilinode-staff-notice.gjs (staff notice), lib/ (pure logic and the embed.js loader).

Build a release ZIP

sh build-zip.sh (from the repository root) writes dist/affilinode-discourse-<version>.zip with the folder affilinode-discourse/ – without tests and hidden files. Raise the version in about.json and package.json first.