Habitica GAS Template

The Google Apps Script template for Habitica (Habitica GAS Template) is a broadly usable template to create scripts that use the Habitica API. It extends the capabilities of the Streamlined Event-Driven (Webhook) Script Template.

It provides users with a simple interface to install, update and deinstall their script - without the need to provide the Web App URL manually or to keep track of the installation status.
On the other hand, it provides various helper functions to script authors and takes care of the most common tasks around Webhooks. This also ensures reliable and consistent execution among all scripts using this template, since utility functions aren't implemented again and again, but updated on all scripts as soon a issue arises.

Features[]

For users:

simplified installation procedure
visual interface for script maintenance (installation, updating, deinstallation)

For script authors:

pre-written section for user options and customizations
pre-formed functions for option validation and installation of triggers / webhooks
ready-to-use functions for webhook and trigger processing
API functions handling caching, rate limiting and error detection
numerous utility functions for common actions
improved logging capabilities

Scripts using the template[]

One main advantage of the template is, that utility functions can be easily reused and behave the same throughout scripts using them. If you want to leverage those advantages for yourself, you can check out those scripts, that are using the template:


Script	Author
Counting Tasks	by Turac Ramotar
Notify Quest Latecomers	by Turac Ramotar

Ports of existing scripts[]

In addition ports of various scripts are available on GitHub alongside the template.
The list links to the original scripts, for which ports are available:


Script	Author	Original Script	Original Author
Quest Queue	by Turac Ramotar	Quest Queue	by Snefferdy
Launch Quests with Link	by Turac Ramotar	Launch Quests with Link	by Snefferdy
Faster Auto Accept	by Turac Ramotar	Faster Auto Accept Quests	by EugeneG
Quest Tracker	by Turac Ramotar	Quest Tracker	by bumbleshoot

Installation[]

The following installation instructions are valid for all scripts using the GAS Template.
If you prefer instructions with illustrations, please check out the Illustrated Installation Guide.

Getting a script[]

The first step is to get the source code of the script into your personal account:

Go to the site of the script you want to install on Google Apps Script.
The author will provide you with the corresponding link.
For the raw template the source is here.
If you're not already signed in to your Google Account, you will be asked to sign in.
In the main menu on the left, click on "Overview" (looks like an i in a circle).
On the upper right hand side, click on "Make a copy" (looks like two sheets of paper).
At the top of the following screen, click on the name of your script and remove "Copy of ..." in the dialog, that pops up. Confirm by pressing "Rename".
The order of files is somewhat important, but it is sometimes scrambled after copying the script. For the correct order, use the "Sort files alphabetically" button above the file list (has AZ written on it with an arrow above / below it).

Configuring a script[]

Congratulations, you made is this far. Next we configure your script:

Open the file setup.gs on the left of your script.
Go to the Site Data in your Habitica settings.
Copy your User ID and replace PasteYourUserIdHere in setup.gs with your User ID. It should now look something like this: const USER_ID = "12345678-90ab-cdef-1234-567890abcdef";.
Back on Site Data in your Habitica settings, reveal your API Token by clicking "Learn more" behind it.
Copy your personal API Token and replace PasteYourApiTokenHere in setup.gs with your API Token. It should now look something like this: const API_TOKEN = "12345678-90ab-cdef-1234-567890abcdef";.
Look at all the other customizations and options provided by the script author in setup.gs. Feel free to change them according to your needs. But take care, that you only edit in between = and ; and make sure to keep all quotations ".
In the toolbar on the top, click "Save project" (looks like a floppy disk) or simply hit Strg+S.

Deploying a script[]

Your script now has all the necessary code and options to fulfill your wishes. Now to the final step, deploying it:

In the upper right corner, click the blue "Deploy" button and select "New deployment".
Make sure, the type "Web App" is selected via the "Select type" (looks like a gear).
Check that "Execute as" is set to "Me" and "Anyone" is selected in "Who has access", then hit the "Deploy" button.
Next you will be asked to authorize access to your data for the Web App. Click "Authorize access" and follow the on-screen instructions. The following permissions are commonly asked for:
1. "Send email as you" - to send you error reports using your own mail address
2. "Connect to an external service" - to send requests to the Habitica API
3. "Allow this application to run when you are not present" - to react to triggers and Webhooks
4. "See and download all your Google Drive files" - to retrieve the name of your script
In the following screen, click the URL listed under "Web app". You should see your script interface.
Finally click on "Install" and wait for the action to finish.

If your script status shows as INSTALLED, you made it and your script is active!

Resolving errors in the configuration[]

You made it to the last step, but your script doesn't switch to INSTALLED?
Then maybe there was as mistake while editing the configuration, let's see:

Go back to your script code in Google Apps Script (the tab should still be open next to your script interface).
In the main menu on the left, click on "Executions" (looks like three lines with a play button).
Search for a line with function name "install" and click it. It should be within the first five lines.
You are now provided with the event log of your most recent installation attempt. Check for any errors or warnings and resolve them.
After resolving, follow the steps in Updating options, but click "Install" in the last step.

Assuming you resolved all mistakes, your script status should now be INSTALLED.
If not, repeat this step or ask for help as stated in in the next section.

Unsolved errors, questions or advice[]

You can't finish your script installation, have questions regarding the behavior of the script or want some simple advice? Then there are multiple options:

If the script has a corresponding GitHub page, you can open an Issue or a Discussion on your topic.
Contact the Aspiring Comrades on the official Discord channel of Habitica.
Write an ingame message to the author.

Updating options[]

If you want to modify some options of the script, it is a few easy steps:

Change the options to your liking in setup.gs. Take care, that you only edit in between = and ; and make sure to keep all quotations ".
In the toolbar on the top, click "Save project" (looks like a floppy disk) or simply hit Strg+S.
In the upper right corner, click the blue "Deploy" button and select "Manage deployments".
There should be only one active deployment under "Active". Select it and click the "Edit" button in the upper right corner (looks like a pen).
Select "New version" under "Version" and hit the "Deploy" button. This will update your existing installation with the new code.
Finally open the link under "Web app" and click on the "Update" button. This will recreate all webhooks and triggers (in case any option has an effect on those).

Your script will now run according to your new options!

Deinstallation[]

If you don't need the script anymore, follow those easy steps to remove it:

Go to your script on Google Apps Script.
In the upper right corner, click the blue "Deploy" button and select "Manage deployments".
There should be only one active deployment under "Active". Select it and open the link under "Web app".
You should now see your script interface. Click on "Uninstall" and wait for the action to finish.
Close the script interface and go back to the "Manage deployments" window (the tab should still be open).
Click the "Archive" button in the upper right corner (looks like an inbox tray) and confirm by clicking "Archive".

Your script is now inactive and will no longer be executed. For a complete removal from your account, also execute the following steps.

Close the "Manage deployments" window by clicking "Done" to get back to your script code.
In the main menu on the left, click on "Overview" (looks like an i in a circle).
On the upper right hand side, click on "Remove project" (looks like a waste bin).

Updating the script[]

In case the author of the script published a new version of the script and you want to update, the best way is to reinstall your script:

Go to your script on Google Apps Script and open setup.gs.
Copy all your options and customizations into a text file for later reference.
Follow all the instructions under Deinstallation for a complete removal.
Reinstall the script using the instructions under Installation.
During the configuration, you can take your options from step 2 as reference.

Source Code[]

The code of the template can be found on