indie-config

This article is a stub. You can help the IndieWeb wiki by expanding it.

indie-config is a way to setup your IndieWeb site to make itself available to your web browser to recognize webactions like reply & like buttons on other sites, and then delegate handling of those actions to your site. indie-config implements this functionality using protocol handlers and postmessage.

Distinguishing indie-config and indie-action:

indie-config is something you setup on your home page, so you can click webaction buttons on other sites and have that action handled by your personal site.
<indie-action> is the markup you use for reply, like, and other buttons on your post permalinks, so other folks can click them and have their site handle them.

indie-config was introduced, discussed, prototyped, and demonstrated at IndieWebCampUK 2014

As of 2019, web+action polyfill via iframe doesn't quite work, further experiments are welcomed.

Why

By setting up indie-config on your personal site, you can then click on web action links or buttons on others sites (e.g. "Reply", "Favorite" etc.) and have those actions automatically activate your site's posting interface to.

By adding loading indie-config to your post permalinks (and anywhere else you have webactions), you empower indieweb users that have indie-config setup on their sites to quickly like, repost, and reply to your posts using their own site!

Indie-config is the first working prototype of how a browser can be aware of the tools you want to use to perform actions on the web. As use-cases gets proven and flows mature it hopefully gets superseded by better suited methods built right into the browsers themselves.

Browser support

Bug 1196151 in Firefox was preventing indie-config from working -- fixed in version 78
Works fine in Chrome/ium -- as of 2019-12-22, doesn't work due to CSP violations preventing loading of iframe

How to publish

How to setup indie-config on your personal site:

Create the configuration page

Create a page on your site that only you will need to access. This might be a page such as "config.html". This page should contain the following Javascript:

<script>
(function() {
  if (window.parent !== window) {
    window.parent.postMessage(JSON.stringify({
      // The endpoint you use to write replies
      reply: 'https://aaronparecki.com/note.php?reply_to={url}'
    }), '*');
  }
}());
</script>

Replace the URL above with the URL to your own posting interface.

Register the web action protocol

On your home page, find somewhere to add this code to be displayed only to you when you are signed in to your own site.

<script>
window.navigator.registerProtocolHandler('web+action', 'https://aaronparecki.com/config.html?handler=%s', 'Aaron Parecki');
</script>

Note that you will want to replace the URLs (https://aaronparecki.com/config.html) and my name ('Aaron Parecki') with your own information. You should replace the URL with the page you made in the previous step. The text you add as the third parameter will be shown in the browser prompt, so it makes sense to use your name or possibly the name of your site's software.

Turn it on

Now when you visit your home page, you will see a prompt asking whether your site should be allowed to handle "web+action://" links.

Click "Add Application" (or the equivalent for your browser) and your website is now registered in your browser or operating system.

In Chrome, the prompt is less obvious. At the right of the address bar there will be a small diamond-shape icon. Clicking on that will prompt "Allow [example.com] to open all web+action links" with buttons to "Allow," "Deny," or "Ignore."

Example

Video: http://aaronparecki.com/notes/2014/09/10/1/webactions

How to consume

You need an indie-config loader, like indieconfig.js, and a webactions shim, like webaction.js.

You then load them both in the head of your site:

<script type="text/javascript" src="/path/to/indieconfig.js"></script>
<script type="text/javascript" src="/path/to/webaction.js"></script>

And then everything is done! You might want to add some styling on the .indieconfig-loading class to indicate that a webaction is waiting for the indie-config to load.

The example scripts linked to above, from Pelle's blog http://voxpelli.com/, loads the indie-config on the first webactions interaction after the page has loaded and uses a 3 second timeout before it gives up and fallbacks to redirecting to the href of the first <a> found within the webactions tag. The timeout means that those not using indie-config will get redirected after that amount of time. Pelle replaces the icon used in his webaction presentation with an animation to communicate this to the user.

FAQ

Ok to registerProtocol handler every time

Q: Is it ok to run that register protocol thing every time I load my home page?

A: Yes it is ok. If you run the registerProtocolHandler() on the same page that's already registered nothing will happen – it will know that everything is registered as it should.

Using custom handler for replies instead of configuration

Q: Why does the custom handler send back configuration information instead of just handling replies directly? (i.e., web+action://permalink would be handled by with http://example.com/reply?u=permalink)

A: This does not provide a fallback if there is no handler registered. There would be a <a href="web+action://permalink">Reply</a> link on the page that would go nowhere

isProtocolHandlerRegistered

Q: Couldn't you use isProtocolHandlerRegistered to check if a handler is registered, and only use the custom protocol if it is?

A: That function doesn't exist! And it would be a potential privacy leak, e.g., allowing sites to see which apps you have installed on your phone by checking facebook:, twitter:, etc..

IndieWeb Examples

Pelle Wessman

Pelle publishes JavaScript on http://voxpelli.com that queries a user's registered web+action handler the first time an indie-action is clicked. If an appropriate action handler is found, his "Reply" and "Post" links will use it instead of the default.

~~Uses the X-Tags library to configure <indie-action> tags through the use of a simple proof-of-concept web component.~~

Pelle also built a public localstorage based tool during IndieWebCamp Nürnberg 2016 which people can use to set up indie-config for themselves.

Barnaby Walters

Collaborated with Pelle at IndieWebCamp UK 2014 where they demonstrated links on voxpelli.com directing to a reply link on waterpigs.co.uk. Barnaby has a static page on his site for registering a web+action handler: https://waterpigs.co.uk/indie-config.html

Kyle Mahan

Registers indie-config handlers for reply, repost, favorite, and like actions using https://kylewm.com/test/indieconfig.html.

2014-02-05. added voxpelli's indieconfig.js and webaction.js, so "Reply" and "Like" links should work for anyone who has indie-config handlers.

Malcolm Blaney

dobrado no longer supports a web+action handler registered in the user's browser. It instead looks for a rel="webaction" endpoint when a user provides their url. The returned config is then stored in local storage.

Extended indie-config to look for a status option and performs a request using CORS if found. (See Brainstorming)

Brainstorming

Return Route

It would be nice to have an extra argument for a URL to return to after the action has been completed. This way we can complete everything in one window. No pop-up required.

Status Option

Malcolm added a status option to his implementation on 2015-10-22.

The idea is that indie-config can perform a request back to the user's site via CORS, which will return the state of the target. It should provide the state of all actions known to the user's site for that user and target url combination. It should provide the state as JSON, ie { "like": true, "follow": true } or some other combination. It can omit false values as that is implied.

When the calling site receives this information, it can mark up the display of each action however it likes. This could just be adding a class name like "highlight" to the action, or changing the text of a link from "follow" to "following".

In general I think this is an interesting approach. It could be a bit more in your face if one asks for a status before the user has done any action on the site, as then the user might be asked questions about allowing the site access before it has even interacted with the site --Kodfabrik.se 00:52, 22 October 2015 (PDT)
It would be good to allow eg. { "follow-status": "http://example.com/follow-status" } for each standard indie-config value, either instead of or in addition to, as at least follow status might be something only an indie-reader knows whereas the like status might be something the indie-reader knows nothing about --Kodfabrik.se 00:52, 22 October 2015 (PDT)
It might perhaps be useful to allow querying the status for multiple URL:s at once, that way one can show the status of all webactions in a feed by just making a few calls --Kodfabrik.se 01:41, 22 October 2015 (PDT)
I've added support for "action-status" (ie "follow-status", "like-status" etc.) but I only use the generic fallback option "status" myself. I also allow multiple urls to be queried using the format url[]=target1&url[]=target2...etc. The JSON response should now be returned as: { "target1": { "like": true }, "target2": { "reply": true } } for example. Targets with no status information can be omitted, as well as actions where the state is false. --Malcolm 27 October 2015

Why