Subscribing to iCalendar feeds with QR codes

calendar, iCalendar, subscribe, android, iphone, qr code

Every day I receive emails containing invitations to events. Whether they are local community activities or international conferences, they share a common problem that is easily avoidable. Every recipient of the invitation has to manually copy and paste the event to their calendar.

If it is a recurring event then it can be even more challenging. If the participant sets up a recurring event in their own software and stops reading the emails then it will not always be obvious to them when one instance of the meeting is skipped or in an unusual venue.

iCalendar feeds provide a simple solution to all these problems. We've tried to use this solution in a few groups with mixed reults.

In one Toastmasters group, we put the webcal:// URL of the feed into a QR code on the form for new members and guests. Any time a guest came to the meeting we would suggest they scan the code to include future meetings in their calendar. For an event that operates around real-world meetings, having somebody follow the calendar appears to be even more critical than having somebody follow the email list.

We had mixed results with this. Everybody liked the idea and everybody was willing to scan the QR code. I think that almost everybody who attended one of the meetings already had an app for QR codes on their phone. However, after scanning the code, different phones behaved differently.

Some phones would try to send the URL to the web browser instead of the calendar. The browser would then make a one-off download of the calendar file and import the events to the calendar once. There would be no subscription to poll the URL and detect new events or changes to existing events.

Based on these experiences, I felt the best thing to do is create a landing page (download here) that can be embedded in the QR code. The landing page, served by a short PHP script, can look at the contents of the HTTP Accept header and determine if the page is being accessed from a browser or a real calendar app. In the former case, it will show people instructions and in the latter case, it serves the calendar feed contents.

Here are some examples of the Accept header, the script will serve the feed contents whenever it sees text/calendar:

Accept: text/calendar,text/plain;q=0.8,*/*;q=0.5
User-Agent: Mozilla/5.0 (X11; Linux) Gecko/Thunderbird Lightning

Accept: text/calendar, */*;q=0.9
User-Agent: ICSx5/2.0.2 (ical4j/ okhttp/ Android/)

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8

I had to contemplate the question of whether the QR code should include the webcals:// prefix or the https:// prefix. I decided to use the latter as it is more reliable. Nonetheless, a webcals:// URL is in the HTML page, if somebody clicks it and if they have suitable calendar software installed then there is a good chance they will be subscribed. Even though this takes two steps (scan the code, click the webcals:// URL), a higher percentage of users end up subscribed to the calendar.

The topic of landing pages is now available for discussion in the ICSx5 repository.

Here is a QR code for subscribing to the EPFL-UNIL Toastmasters club calendar, please test it and share feedback about any issues with the landing page:

EPFL-UNIL Toastmasters Club calendar feed

Download the landing page PHP source code

The source code is available on Gitlab, it is easily customizable for any iCalendar URL