URL Scheme Documentation

Due registers the due:// URL schema and provides two actions: /add and /search.

/add overview

Launches Due with the add reminder view. Optionally, prefill the new reminder using the information provided in the parameters described below. Once the reminder has been added, Due can send the user back to your app seamlessly using the x-callback-url protocol.

Reminder parameters

All optional, but you'd probably want to fill up at least title and duedate, else you'll be just creating a new empty reminder with nothing prefilled.

title string, optional

The title for the reminder. If provided, the title of the reminder is filled up automatically and the keyboard will not be shown automatically.

duedate double, optional

The due date of the new reminder, expressed in number of seconds from the first instant of 1 January 1970, GMT. Use to set an absolute due date for the reminder. The duedate is interpreted according to the optional timezone value. See also 'A note about dates'.

secslater double, optional

The due date of the new reminder, expressed in number of seconds from now. Use to set a relative due date for the reminder from now. Due would calculate a due date for the reminder based on this value. If duedate is filled, Due would ignore the secslater, minslater and hourslater parameters and set up the reminder's due date based on the duedate parameter only.

Note that reminders in Due only fire on the minute. This means that if you provide a value that is not completely divisible by 60, Due would round it up to the next minute. This can also be combined with minslater and hourslater.

minslater double, optional

The due date of the new reminder, expressed in number of minutes from now. Use to set a relative due date for the reminder from now. Due would calculate a due date for the reminder based on this value. If duedate is filled, Due would ignore the secslater, minslater and hourslater parameters and set up the reminder's due date based on the duedate parameter only.

This can also be combined with secslater and hourslater.

hourslater double, optional

The due date of the new reminder, expressed in number of hours from now. Use to set a relative due date for the reminder from now. Due would calculate a due date for the reminder based on this value. If duedate is filled, Due would ignore the secslater, minslater and hourslater parameters and set up the reminder's due date based on the duedate parameter only.

This can also be combined with secslater and minslater.

timezone string, optional

The timezone used to interpret the dates provided in duedate and recurfromdate parameters, expressed as a string for use with [NSTimeZone timeZoneWithName:] method.

If unspecified, dates provided in the duedate and recurfromdate parameters are interpreted as absolute GMT times or Universal times (see 'A note about dates').

For example, if the value 1306886400 (corresponding to 12 midnight on June 1st 2011 at GMT) is provided in the duedate parameter and no timezone is provided, Due will set the due date to the same exact instant in the world, although at different times of the day in different countries—8am on June 1st in Singapore (GMT+8) but 9pm on May 31st in Argentina (GMT-3).

To ensure that the duedate is set at a specific time regardless of the timezone that the user is in (eg. medical appointment at 8am on June 1st), you should provide a value for timezone that can be used to interpret the dates.

For example, specifying the value 1306915200 in duedate (corresponding to 8am on June 1st 2011 at GMT) and GMT in the timezone parameter will set the due date to 8am on June 1st 2011 no matter which time zone the user is in. You can also achieve the same results by specifying 1306944000 in duedate (corresponding to 8am June 1st 2011 at GMT+8) and Asia/Singapore (GMT+8) in the timezone parameter.

Note that the timezone value provided to Due here only affects how dates are interpreted at the point of setting up the reminder. Once created, reminders are always interpreted as wall times and will shift according to the time zone that the user is in to ensure that a reminder at 9am will always be at 9am whether in Tokyo or San Francisco.

Helpful tools: http://www.epochconverter.com/

autosnooze unsigned integer, optional, Due 3.2+

The interval in minutes at which Due will repeatedly notify the user of this reminder once it becomes due. Valid values are 1, 5, 10, 15, 30 and 60.

If unspecified, the reminder uses the default auto snooze interval as per the user's settings.

Recurrence parameters

All optional. Parameters to set up recurring reminders. For basic recurrences (eg. every N days/weeks/months), fill up recurunit, recurfreq and recurfromdate. Advanced monthly recurrences (eg. first Monday every 2 months; every week on Mon, Wed, Fri) are determined by the values in recurbyday and/or recurbysetpos.

recurunit unsigned integer, optional

The calendar interval (NSCalendarUnit) at which to repeat the reminder. Valid values are NSDayCalendarUnit (16), NSWeekCalendarUnit (256), NSMonthCalendarUnit (8) and NSYearCalendarUnit (4).

recurunit is the only required parameter needed to set up recurrence. If recurunit is blank while recurfreq and recurfromdate are filled, Due will not set up any recurrence for the reminder.

recurfreq unsigned integer, optional

The frequency at which the recurrence rule repeats over the unit of time indicated in recurunit. For example, a reminder with recurunit of NSWeekCalendarUnit (256) and recurfreq of 2 will repeat every 2 weeks. Valid values are 1-30. The default value is 1, ie. repeat every 1 of recurunit.

recurfromdate double, optional

The date to start recurrence from (eg. every 3 days from this date), expressed in number of seconds from the first instant of 1 January 1970, GMT. Usually the same as the duedate. If unspecified, the recurrence will be repeat-from-completion, eg. a yearly repeat-on-completion reminder will repeat again on June 1st, 2012 if the user completes it on June 1st, 2011, but will repeat on June 3rd, 2012 if the user only completes it on June 3rd, 2011.

Unless you're looking to create repeat-from-completion reminders, you should provide a value for recurfromdate.

recurbyday comma-separated unsigned integers, optional

A comma-separated list of days of the week. The day-of-week units corresponds to the integers 1 through 7 (where 1 is Sunday, 2 is Monday, 7 is Saturday) for weekly repeating reminders, but must be modified to the integers 8 through 42 to indicate the nth occurrence of the specific day-of-week within a monthly repeating reminder.

The values 1 through 7 indicate all days of this type within the recurunit, and is only valid for use with weekly reminders. For example, within a weekly recurunit, a value of 2,6 for recurbyday indicates all Mondays and Fridays every week.

Monthly recurunit reminders require you to specify the nth occurrence of the day-of-week within the month. To indicate the nth occurrence, you need to add n*7 to the day-of-week unit (where n=1 through 4 indicates 1st through 4th occurences, and n=5 indicates the last occurrence within the month).

For example, within a monthly recurunit, a value of 17 for recurbyday indicates the second Tuesday within the month (obtained from n*7+3, where n=2 for the second occurrence, and the day-of-week unit for Tuesday is 3), while a value of 38 for recurbyday indicates the last Tuesday within the Month (5*7+3).

Limitations: For monthly reminders, Due will only accept the first integer as specified in recurbyday and discards the rest.

recurbysetpos integer, optional

A single integer of value 1 or -1 that is used only in conjunction with a monthly recurunit along with a valid recurbydays to indicate either the nth occurrence of a day or weekday of the month.

For example, the last week day of the month can be indicated with a recurbysetpos of value -1, with a recurbydays of values 2,3,4,5,6.

The first day of the month can be indicated with a recurbysetpos of value 1, with a recurbydays of values 1,2,3,4,5,6,7.

Limitations: Due only accepts the values 1 and -1 to indicate the first or last day/weekday of the month. Weekdays are always Mondays-Fridays, and days must include all seven days of the week. recurbysetpos has no effect on any recurunit other than monthly repeating ones.

x-callback-url parameters

All optional. Fill up x-source and at least x-success or x-error if you want Due to send the user back to your app after the reminder has been added.

x-source string, optional

A friendly name for the app making the call. If both x-source and either a valid x-success or x-error parameter is provided, Due will ask the user if he wishes to return to the calling app upon adding (or cancelling the addition of) the new reminder.

x-success string, optional

The URL to use to return the user to the calling application if the reminder was added. If both x-source and a valid x-success parameter are provided, Due will ask the user if he wishes to return to the originating app using this link upon adding the new reminder.

If your app does not need to know whether or not the reminder has been added successfully, you can just provide the x-success parameter.

x-error string, optional

The URL to use to return the user to the calling application if the reminder was not added. If both x-source and a valid x-error parameter is provided, Due will ask the user if he wishes to return to the originating app using this link upon cancelling the addition of the new reminder.

If your app does not need to know whether or not the reminder has been added successfully, you can just provide the x-success parameter.

Usage examples

Title & Due Date

Sets up a reminder with the title 'Prank someone in UK' at 12 midnight April 1st, 2012 GMT (which is UK time). Since timezone is not specified, a user opening this link on a device that has its timezone set to Singapore time (GMT+8) would have the due date set to April 1st, 2012 at 8am.

Title, Due Date & Timezone

Sets up a reminder with the title 'Prank someone' at 12 midnight April 1st, 2012 in the timezone that the user is in.

Basic Recurring Reminder

Sets up a reminder with the title 'Pay rent' at 7pm of June 1st, 2011, where ever the user is in the world, recurring once every month from the same day and time as the due date (June 1st, 2011 7pm).

Complex Recurring Reminder

Sets up a weekly repeating reminder with the title 'Recycle trash' on Tuesdays and Fridays at 9.00 am, starting from May 31, 2011.

Due Date Relative To Now

Sets up a reminder with the title 'Call John' an hour from now, and asks Due to return the user to the calling app SuperCal using the URL supercal://x-callback-url/returnAction

A note about dates

Adapted from WWDC 2010. There are two kinds of times—Universal Time and Wall Time.

A Universal Time happens at the same instant no matter where the user is in the world. It is independent of timezones and happens at the same exact instant everywhere in the world, whether the user is in Tokyo or San Francisco (eg. a specific baseball match, Steve Job's keynote at WWDC 2011).

A Wall Time happens at a specific time within a timezone (eg. wake up daily at 7am, New Year's Day). It happens at a different instant depending on where the user is in the world. For example, although New Year's Day (January 1st 00:00) happens at 12 midnight of January 1st for people in both Pakistan and Singapore, it comes 3 hours later in Pakistan (GMT+5) than Singapore (GMT+8).

/search overview

Launches Due on the iOS device and searches for a query string in the specified section.

query string, optional

The string to search for when Due is launched.

section string, optional

The section to search in. Can either be 'Reminders', 'Timers' or 'Logbook'. If not provided, or if an invalid value is provided, the search will take place in Reminders.

Usage examples

Search for reminders containing #work

Launch Due, showing just reminders containing the word #work.

Search for timers containing #HIIT

Launch Due, showing just timers containing the word #HIIT.