Android Pomodoro Integration

= Integrating an Android Pomodoro Timer with Habitica = Note: This guide is an update to and expansion of Bink2007's guide. Special thanks go to Bink2007, LadyAlys, their commenters, and goldfindr for their work.

With some effort, it's possible to use Tasker and Habitica's Application Programming Interface to automatically record finished and interrupted Pomodori as Habitica Tasks. This process will require Tasker, a paid Android app, and Clockwork Tomato, which is available without payment. It will also require you to store your API Token in Tasker, and to configure Tasker and Clockwork Tomato to work together and to communicate with Habitica. Users who aren't sure they want to invest the money or time should review the steps and consider.

Create Habitica Habits
The first step is to create Habitica Habits that will be triggered by the completion or interruption of a Pomodoro. This guide assumes that you want two habits:
 * "Pomodoro" - a basic habit that will be incremented on the completion of a normal Pomodoro or decremented if you interrupt or stop a Pomodoro without completion; and
 * "Pomodoro Set" - a habit to record the completion of the final Pomodoro in a set.

If so, create two Habits as pictured in this section.

If you use the Habitica web client as well as the Android client, I recommend that you create these tasks by installing the Habitica Chrome Extension, choosing Options in the extension, and enabling "Tomato.es Integration" and "Pomodoro Tracker Integration." This will create two Pomodoro habits in your task list. Once created, you can rename the tasks as desired and/or disable the Chrome Extension integrations, but this way, the Chrome extension and the Tasker integration will use the same habits to record Pomodori.

In order to avoid skewing your results, I also recommend that you set both Pomodoro habits to trivial difficulty. Feel free to name the Habits anything you like - later, you will be using an internal TaskID to match the habits with events on your Android device.

Install Android Apps
Using the Google Play Store, install Tasker and Clockwork Tomato on your Android device. Note: it is also possible to configure Pomodroido or any other Tasker-compatible Android Pomodoro timer to work with this method, although some of the steps required in the sections below will change. For more information on using Pomodroido instead of Clockwork Tomato, please see Bink2007's guide.

Configure Tasker
Tasker is an extremely powerful Android utility that executes user defined tasks based on changes to the phone or its applications. For this project, we will be (1) configuring Tasker to communicate with the Habitica API, and (2) configuring a set of "tasks" for Tasker to execute when a Pomodoro starts or stops. First, enable external access to allow Clockwork Tomato to communicate with Tasker. In the Tasker app, select the three dot menu on the upper right, then select "Preferences," then the "Mist" tab, then make sure "Allow External Access" is checked.

Install JavaScript Functions
Tasker-habitrpg is a set of JavaScript functions and example scripts created by goldfindr and designed to allow Tasker to communicate with the Habitica server. For more information on this step and on importing the "Score a task" script below, see the README file on the project's GitHub page.

For this step:

a. Download the HabitRPGfns.js file to a text file of the same name and extension in your phone's Tasker/JavaScript directory. You will probably need to create a JavaScript folder in your Tasker directory, which should be located either at the main level of your phone's storage or in an /sdcard/ directory.

b. Configure the script by opening it with a text editor and uncommenting and including your data the following lines:

Replace: // // Only need to be set once; they are Global variables, and survive reboots // setGlobal('HabitrpgUserid', '########-####-####-####-############'); // setGlobal('HabitrpgApiToken', '########-####-####-####-############'); // setGlobal('HabitrpgCDS', '0'); // Custom Day Start value, 0 if not set

with:

// // Only need to be set once; they are Global variables, and survive reboots setGlobal('HabitrpgUserid', ' '); setGlobal('HabitrpgApiToken', ''); setGlobal('HabitrpgCDS', '0'); // Custom Day Start value, 0 if not set

Make sure the values for HabitrpgUserid, HabitrpgAPIToken match your values from your API Page. The last Global Variable - HabitrpgCDS - is not necessary for the functions we will be using in this guide, but you can reset the '0' to your Custom Day Start value if you think you may be using some of the other functions in the JavaScript code. After the first time you execute this integration successfully, you can remove these values from the text file, but be aware that Tasker will continue to store your API Token internally.

Create Tasks
For this step, we will create a series of "Tasks" that Tasker will execute under appropriate conditions.

Score a task
This task sets variables to instruct the JavaScript routines to adjust a task by hitting its positive or negative check-mark. The task accepts two parameters: (1) the "Task ID" of the task to be adjusted and (2) the direction (up or down) to adjust the task. To import this task,
 * Copy the XML information from score_a_task.tsk.xml to a text file with the same name somewhere you can find it on your Android device, like a /Tasker/Tasks directory.


 * Import that file into a new task by opening Tasker, then tapping the Tasks tab and selecting Import. After Score a task steps.pngting Import, browse to the folder where you stored the "score_a_task.tsk.xml" file and click to select it. If successful, you should have a new task labeled "Score a task". This task accepts two arguments, TaskID and direction (up or down) and then uses the Habitica API to check either the up or down button on the identified task.

Note that the fifth step in this task is to display the result of that API call, which will be the new Task Value of the identified task. Once you are satisfied that the integration is working correctly, you may want to delete that step to reduce clutter.

Tomatostart
This task does some housekeeping whenever Clockwork Tomato starts a new Pomodoro. (1) If it is the first Pomodoro of the day, it resets the Pomorodo count to 0 and records the new date; (2) it sets a timer to check if a stopped Pomodoro was completed or interrupted.
 * Copy or download the code from the Tomatostart.tsk.xml file in this GitHub directory to a text file of the same name in the tasks folder on your Android device.
 * Import that task to Tasker.
 * Find the Task IDs of your two Pomodoro tasks by logging in to the Habitica Data Display Tool, selecting "Task Overview" and then selecting "Toggle Developer Data." (If you would like to record all Pomodoro events in a single habit, just use the Task ID for that habit for both %Pomoid and %Bigpomoid below).EditTomatoStart.png
 * In Tasker, select the "Tomatostart" task, and edit the following variables:
 * Set the variable %Pomoid to be the Task ID (including dashes) for your individual Pomodoro habit;
 * Set the variable %Bigpomoid to be the Task ID (including dashes) for your Pomodoro Set habit;
 * If you have a Pomodoro set size other than 4, set %Pomodorosetsize to that number; and
 * If you do not want status updates appearing on your device, set %Pomoverbose to any value other than yes.

Tomatostop
This task (1) checks to see if the Pomodoro was completed or interrupted by comparing the elapsed time since start with the goal time. (2) if completed, it increments the Pomodoro count by one and upscores either the base Pododoro habit or the combo habit by one check as appropriate. (3) if interrupted, it downscores the base Pomodoro habit by one check. Similar to the previous two tasks:
 * Copy or download the code from Tomatostart.tsk.xml in this GitHub directory to a text file of the same name in the tasks folder on your Android device.
 * Import that task to Tasker.

Configure Clockwork Tomato
The final step is to configure Clockwork Tomato to activate the Tomatostart and Tomatostop tasks when a Pomodoro is started and stopped, respectively.
 * In the Clockwork Tomato app, choose the gear menu in the top right and select "Tasker"
 * Make sure the check box for "Call Tasker Tasks" is enabled
 * Associate "When a pomodoro starts" with "Tomatostart"
 * Associate "When a pomodoro stops" with "Tomatostop"

Expected Behavior
If configured successfully, this integration will (1) increment your Pomodoro Set habit for the completion of each set of Pomodori, (2) increment your basic Pomodoro habit for the completion of each Pomodoro that is not the last one in a set, and (3) decrement your basic Pomodoro habit for any Pomodoro that was stopped prior to completion. If you prefer different behavior, you can adjust the Tasker code to your preference.

Feedback
If you have any questions or any ideas how to improve this walkthrough or the Tasker code, please let me know by posting on my message wall. I'd love to hear from you!