extralifehelper: A JavaScript repository from nicoletirado

Extra Life Helper v2.0

https://github.com/breadweb/extralifehelper

Distributed under the MIT license.

Date: 9/11/2017 11:24:17

Introduction

This is an application I created in 2013 for Extra Life. I wanted something to track the time until Extra Life, track my total time playing on game day, and show my fundraising information. The following year I made it available to the community and I was excited to see it adopted by so many participants.

Download

Right-click the following link and select "Save link as..."

ExtraLifeHelper.zip (312 KB)

Features

Counts down the days until Extra Life if there are three or more days left.
Counts down the hours until Extra Life if there are less than four days left.
Counts the total hours played if the start time has passed.
Shows total amount raised and updates in real-time.
Shows new donation alerts as they arrive in real-time.
Allows specifying custom sound effects for the donation alert.
Provides a hook to run custom JavaScript when a new donation arrives.
Occasionally shows the Extra Life and Children's Miracle Network Hospital logos.
Works in "participant" mode or "team" mode.
Supports four color themes and three border styles.
Works in XSplit, OBS Studio, and in any modern browser.
Runs locally without dependency on any remote service besides the Extra Life website.
Core functionality and appearance can be modified with little JavaScript exprience.

Counts down the days.

Counts down the hours.

Counts the hours you have played.

Shows new donations as they come in.

Occasionally shows the Extra Life logo.

Occasionally shows the CMNH logo.

Screenshots

To see how some Extra Life participants have used the Helper in their live stream presentations, check out the screenshot gallery:

http://github.com/breadweb/extralifehelper/blob/master/Examples.md

XSplit Instructions

Requirements:

Windows 10, XSplit 3.0

Instructions:

Extract the content of the zip file you downloaded to a folder on your computer.
Personalize the Helper using the instructions below.
Open up XSplit.
Select a scene.
In the scene sources section, click "Add" and then click "Webpage..."
Click the "Browse" button and select ExtraLifeHelper.html from the location you extracted the files.

OBS Studio Instructions

Requirements:

Windows 7/8/10, OBS Studio 20.0.1
OSX Sierra, OBS Studio 20.0.1

Instructions:

Extract the contents of the zip file you downloaded to a folder on your computer.
Personalize the Helper using the instructions below.
Open up OBS Studio.
Select a scene in the "Scenes" section.
Right-click in the "Sources" section, select "Add" and then select "BrowserSource".
Select "Create New", type in a name such as "Helper" and click OK.
In the Properties screen, check the box that says "Local file", click the "Browse" button and select ExtraLifeHelper.html from the files you extracted.
Set the Width and Height to whatever is specified in the HTML file. Delete everything in the CSS field. Click OK.

Personalizing the Helper

First, get your participant ID. It can be found in the URL for your fundraising page. Look for the "participantID" in the URL towards the end. For example:

http://www.extra-life.org/index.cfm?fuseaction=donorDrive.participant&participantID=101425

If you want to use the Helper in team mode, get your team ID. It can be found in the URL for your team's fundraising page. Look for the "teamID" in the URL towards the end. For example:

http://www.extra-life.org/index.cfm?fuseaction=donorDrive.team&teamID=16539

Open the ExtraLifeHelper.html file using a text editor such as Notepad and enter in your participant ID, start date, start time, etc.

// Extra Life Helper
// ============================================================================================
// For use details and use instructions, visit https://github.com/breadweb/extralifehelper
// For help or feature requests, visit http://bit.ly/helper-forum/
// 
var participantId = "265671";              // Set this to blank to run in team mode
var teamId = "";                           // Set this to blank to run in participant mode
var startDate = "11-04-2017";              // Set to your local Extra Life start date
var startTime = "10:00:00";                // Set to your local Extra Life start time
var helperTheme = "blue1";                 // Color theme: white1, gray1, blue1, or blue2
var helperBorder = "rounded";              // Border type: rounded, square, or none
var helperWidth = 264;                     // Width of the Helper, in pixels
var helperHeight = 110;                    // Height of the Helper, in pixels
var showDonationAlerts = "true";           // Set to "false" to suppress donation alerts
var showGoal = "true";                     // Set to "false" to only show amount raised on the
//                                         // main screen and not also your goal
var donationSounds = "cash.mp3,kids.mp3";  // Set this to your custom set of sounds, separated
//                                         // by commas. Or set to "" to have no sounds play
// ============================================================================================

// If you would like additional things to happen when a new donation is 
// received, put them in this function.
function onNewDonation(donorName, donationAmount, message, avatarImageURL, createdOn)
{
    // Your custom logic here.
}

Some special notes about editing this file:

The startTime value format is military time. 1:00 PM = 13:00, 2:00 PM = 14:00, etc.
If specifying multiple sound files for the donationSounds value, be sure to separate them with commas.
If you know JavaScript and have some smart devices in your house (such as programmable lights or displays) or a remote API you want to work with when you receive a new donation, you can add custom code in the onNewDonation function.

Resizing the Helper

The Helper is made with vector art so when stretched, it should always remain sharp no matter what size. The trick to making this work is to be sure that the width and height values for the Helper in XSplit or OBS match what is in the ExtraLifeHelper.html file. After you change the values in your streaming software, don't forget to update the html file!

For OBS Studio, avoid resizing the Helper by dragging it. Open the properties and specify the values there until the size is what you want. This is because resizing by dragging will not update the values in the properties and so you won't know what to set in the html file.

Color Themes, Borders and Sound

There are a few more options for customizing the Helper to suit your streaming setup.

Color Themes: There are four color themes available that respect the Extra Life brand guidelines.

The values that can be set are "blue1", "blue2", "white1", and "gray1".
Borders: By default, there is a border with rounded corners. You can change it to have square corners or remove it completely. The values are "rounded", "square", or "none".
Sounds:
- To use your own donation sounds, place your mp3, wav, or ogg files in the audio directory and update the donationSounds value in the ExtraLifeHelper.html file.
- You can mute the Helper by setting the donationSounds value to "".

These options can be changed in the ExtraLifeHelper.html file that you edited during the steps to personalize the Helper.

Example Video

The following video is a compilation of donations received during the Extra Life 2017 marathon. I use the donation hook to make a call to my light bridge and make my office lights flash.

Troubleshooting

You see a "CHECK CONFIG" message instead of your donation total.

There are two common reasons for this:

Your participant ID is not correct or you made an accidental typo.
You are trying to use the Helper in an unsupported way. Please review the instructions.

You see $0 for your donations received.

There are a few known reasons for this:

You haven't received any donations yet. Keep up the fundraising efforts!
You got your first donation, but it hasn't registered fully on the Extra Life site. Just give it a few minutes to show up.
The Extra Life website timed out when the Helper was trying to contact it. This can happen if the Extra Life website is under high load. Just be patient and the Helper will get the current total again when the Extra Life website responds.
You are trying to use the Helper in an unsupported way. Please review the instructions for proper use.

The Helper looks blurry.

This is usually because you have streched the Helper in your presentation but forgot to update the width and height values in the ExtraLifeHelper.html file to match.

Donations

It's been really rewarding to see the Helper being used by so many people who are raising money for a great cause. I do not expect anything in return, but if you are determined, you could always make a donation on my Extra Life page since this is all for the kids! Thank you!

Modifying and Contributing Back

Because the source is freely available here, you are welcome to modify the Helper however you see fit. Some modifications that have been done by other participants so far include:

Adding a third hour digit to the clock to support a 100+ hour long marathon
Changing the fonts or color themes to match a stream presentation
Adding a background image to match a steam presentation
Adding donation alerts while running in team mode

If you make a change that would benefit all users of the Helper, please make a pull request and I would be happy to review it. Thank you!

Contact

If you see any issues that are not covered in the troubleshooting section, please visit the Helper forum thread and I'll do my best to fix it quickly.

I'd also love to see the Helper being used on your stream. Let me know your broadcasting URL so I can watch and cheer you on during the marathon. Good luck with your fundraising for Extra Life!

Adam "Bread" Slesinger

Twitch: http://www.twitch.tv/bread_man
Extra Life: https://extra-life.org/participant/bread
Steam: https://steamcommunity.com/id/breadweb

nicoletirado/extralifehelper