Bright Toolbox

Accept tips & donations, thank donors, give gifts, set targets, get stats, etc!

DESCRIPTION

The Bright Tip-Jar enables visitors to your venue to donate money towards its upkeep.

Just rez it, and it is ready to receive tips, thank donors, give them gifts, notify you of payments, and transfer them to your Linden dollar balance.

You can tell the tip-jar what thank you messages to send by typing them into a SETTINGS notecard, and (it you wish) name gifts to give. You may even define multiple messages and gifts, specifying minimum donations required to receive each. The tip-jar comes with a T-shirt gift ready to give out.

If you wish, you may set a target for donations, and a recurring donations period. The tip-jar will monitor progress against your target, and if you have specified a period, restart progress at the beginning of each day, week, month, quarter, or year.

The tip-jar displays information in floating text, switching between four displays: overall donations, all-time top donors, top donors in the current period (if there is one), and general "about us" text. You may type the text to be used in these displays into a notecard in the tip-jar.

You may also hear the same information in chat by running a report through the tip-jar's menu system. This menu system also lets you manually record donations (as if paid directly by other avatars), or clear them.

The tip-jar looks, well, like a tip-jar: a glass jar full of notes and coins, with a "tips" sign hanging from string. The menu system allows you to scale the jar to heights between 50cm and 5m, and change any of its textures though a series of options. You may also change the colours used to display floating text: up to three may be used at a time.

An simple API is provided to allow you to script other objects to react to donations. Each payment triggers a region-wide message which your own scripts can intercept.

Your venue's visitors wouldn't keep coming back if they didn't value it, and many are more than happy to contibute to help keep it open. Give them a chance to do so, and thank them in words and gifts, using the Bright Tip-jar!

INSTRUCTIONS

Drag the object "Bright Tip-Jar boxed" onto the ground to rez it. Right-click, select "Open" from the pop-up menu, and click the "Copy To Inventory" button at the bottom of the contents window. This will create a folder in your inventory, also called "Bright Tip-Jar boxed".

From this, drag the "Bright Tip-Jar" onto the ground.

You will see the tip-jar itself, with the following text floating over it:

       *** PLEASE DONATE! ***
    JUST CLICK BELOW - THANK YOU!

It is now live and ready to accept donatons: but to get the most out of it, you may wish to read through the rest of this manual, and learn how to use its menu system and "SETTINGS" notecard to configure it to suit your venue and visitors.

MENUS

Clicking the tip-jar will display a pop-up "pay" box to accept a donation.

To avoid this and display the main menu, right-click the tip-jar and select "Touch".

    MAIN MENU

    Period: NONE, Target: $0
    All-time total: 0 donations = $0
    Period total: 0 donations = $0
    Entry box: YES, Suggestions: 5, 10, 20, 50
    Notifications: ON

    (Memory: 7982b, Runtime: 0.12h)

    [PERIOD] [NO PERIOD] [TARGET]
    [ENTRY BOX] [SUGGESTIONS] [NOTIFY]
    [ADD] [CLEAR] [REPORT]
    [SIZE] [TEXTURES] [TEXT]

SETTING A PERIOD

Click [PERIOD] to enable donation periods.

    SET PERIOD

    Current period: NONE

    Please choose a new period.

    [DAY] [WEEK] [MONTH]
    [<BACK] [QUARTER] [YEAR]

Out of the box, the tip-jar does not track periods.

If you choose a period, the tip-jar will keep two running totals: the all-time total received, and the total received during the current period. It will also keep two "top donations" lists, again, one recording the all-time top five, the other the top five for the current period.

As each period ends, the period total will be reset to 0, and the period's "top donations" list cleared. (Days start at midnight UTC, weeks on Mondays, months on the first, quarters in January, April, July, and October, and years in January.)

The period total and top donations list will not be affected by changing periods. If you didn't previously have a period set, the tip-jar will assume that all the donations were received during the current period, so the period total and top donations list will be copied from the all-time data. If this isn't what you want, you may wish to use the option to clear the period donations documented below.

Click [<BACK] to return to the main menu.

SETTING NO PERIOD

If you set a period, and later decide to disable periods, click [NO PERIOD].

    SET NO PERIOD

    Please note: setting 'no period' will...

    1. Erase the current period total
    2. Erase the list of top donations this period

    The all-time total & donations list will be unaffected.

    [<BACK] [NO PERIOD!]

Click [NO PERIOD!] to confirm you wish to disable periods, or [<BACK] to return to the main menu.

SETTING A TARGET

Click [TARGET] to set or change a target for donations.

    SET TARGET

    Current target: 0

    Please enter a target for donations each
    period. (If the period is NONE, this is an
    indefinite target.)

    Enter 'NONE' if you do not wish to set a target.
    
    [                ]

    [Submit]

If you have selected a period, this target represents the amount you hope to receive during each peiod. Progress towards the target will be reset as each new period begins.

Click [Submit] without making an entry to return to the main menu.

ENABLING AND DISABLING THE ENTRY BOX

When someone clicks the tip-jar, they will be presented with a payment dialog. Click [ENTRY BOX] to determine whether or not this dialog will offer an entry box into which they may enter an the amount they wish to give.

Disabling the entry box will force them to choose one of the suggested payments (see below). For this reason, you will be unable to disable the manual entry box if you have defined no suggested payment amounts.

SETTING SUGGESTED PAYMENTS

Click [SUGGESTIONS] to set up to four amounts to be suggested to donors when they click the tip-jar.

    SET SUGGESTED PAYMENTS

    Current suggested payments: 10, 20, 50, 100

    Please enter up to four suggested donations.
    Enter 'NONE' to suppress suggestions.

    eg. '10 20 50'

    [                    ]

    [Submit]

If you enter "NONE" to disable suggested payments, donors will be forced to enter the amount they wish to donate manually. For this reason, you will be unable to disable suggested payments if you have already disabled the entry box (see above).

Click [Submit] without making an entry to return to the main menu.

ENABLING NOTIFICATIONS

If you wish, the tip-jar will send you an IM whenever someone makes a donation.

Click [NOTIFY] to switch this feature on or off.

ADDING A DONATION

Click [ADD] to have the tip-jar record a donation as if paid by another avatar.

    ADD DONATION

    Please enter the donor and amount.

    eg. To add $100 from Shan Bright, enter:
    Shan Bright 100

    [                    ]

    [Submit]

You may enter any name - it need not be the name of an existing avatar. So for instance, if you have been given $100 privately by someone who does not wish to see their name in the donor's display, but would like to record the donation itself, you can enter (say) "Anonymous 100".

Having added a donation, the entry box will be redisplayed to allow you to enter another. Click [Submit] without making an entry to return to the main menu.

CLEARING DONATIONS

Click [CLEAR] to erase some or all donations.

    CLEAR DONATIONS

    Which donations do you wish to clear?

    [CLEAR PRD] clears period donations
    [CLEAR PAST] clears donations before this period
    [CLEAR ALL] clears all donations

    [<BACK]
    [CLEAR PRD] [CLEAR PAST] [CLEAR ALL]

[CLEAR PRD] will erase the list of top donations this period, and reduce the period total to 0. The all-time list and total will be unaffected. It will also erase the last (most recent) donation.

[CLEAR PAST] will remove all donations made before the current period. The all-time total and list of top donations will be overwritten by the period total and list.

[CLEAR ALL] will remove all donations, reducing both period and all-time totals to 0, and clearing all top donation records, and the most recent donation.

[<BACK] will return you to the main menu.

PRODUCING A REPORT

Click [REPORT] to hear the data stored by the tip-jar in chat:

    Bright Tip-Jar: REPORT 2018-09-25 11:47
    (Memory: 27982b, Runtime: 0.12h)

    TARGET: $300
    Period: MONTH
    Shortfall: $190
    Days Left: 17

    Bright Tip-Jar: ALL-TIME DONATIONS

    TOTAL: $570 (22 donors)
    Philip Linden: $100
    Shan Bright: $50
    (...etc)

    Bright Tip-Jar: PERIOD DONATIONS

    TOTAL: $110 (7 donors)
    Shan Bright: $50
    Iggy Hyx: $20
    (...etc)

RESIZING THE TIP-JAR

Click [SIZE] to resize the tip-jar.

    SET SIZE

    Please choose the height of the tip-jar.

    [50cm] [75cm] [100cm]
    [150cm] [200cm] [250cm]
    [300cm] [350cm] [400cm]
    [<BACK] [450cm] [500cm]

Click the button corresponding to the height you would like the tip-jar to be. It will grow or shrink immediately, all its components scaling accordingly.

(Strictly speaking, the heights refer to the distance between the base prim and the rim prim. Their thickness, and the tilt of the handle, mean that the tip-jar is a little taller overall.)

Click [<BACK] to return to the main menu.

CHANGING TIP-JAR TEXTURES

Click [Textures] to display the textures menu.

    SET TEXTURES

    Please choose which texture to change.

    [SIGN] [STRING] [COINS]
    [NOTE1] [NOTE2] [NOTE3]
    [HANDLE] [HINGE] [RIM]
    [<BACK] [GLASS] [BASE]

Simply click any button to cycle through the textures available for the corresponding part of the tip-jar.

You will see the effect immediately. When the tip-jar looks as you you would like it to look, click [<BACK] to return to the main menu.

CONFIGURING THE FLOATING TEXT

Click [Text] to control how frequently the different floating text displays (donations summary, top donor names, and so forth) are swapped, and which colours they use.

    SET FLOATING TEXT

    Cycle time: 20 seconds
    Text colour 1: YELLOW
    Text colour 2: GREEN
    Text colour 3: WHITE

    [<BACK] [CYCLE]
    [COLOUR 1] [COLOUR 2] [COLOUR 3]

Click [CYCLE] to increase the cycle time by 10 seconds, until it reaches 60 seconds, after which it returns to 10.

The [COLOUR] Buttons will cycle through the available text colours: WHITE, GREY, BLACK, RED, GREEN, BLUE, CYAN, MAGENTA, YELLOW, PINK, and ORANGE.

The text will be redisplayed using the selected colours on each click. Once you have found a combination you like, click [<BACK] to return the main menu.

SETTINGS

Right-click the tip-jar, select "Open" to display its contents window, and double-click the "SETTINGS" notecard to open it.

Once you have finished edited its contents as explained below, click [Save] and choose the notecard's window.

THANK YOU MESSAGES

    THANKS: 1 = Thank you for your donation!
    THANKS: 100 = Thank you for your generous donation!
    THANKS: 1000 = Thank you for your VERY GENEROUS donation!

These lines define the messages of thanks sent to donors. The amount before the "=" sign specifies the minimum donation required to trigger a message.

You may set up as may messages as you wish, though they must have different minimum amounts, and these minimums must be in ascending order. The message with the highest minimum within the amount given will be sent.

You must define at least one thank you message with a minimum of 1 - the tip-jar will not accept donations if there is a risk the donor will not be thanked.

THANK YOU GIFTS

    GIFT: 1 = Thank You Gift

Each GIFT line works much like a THANKS line above, but instead of specifying a message to send, it names an item to be given as a gift.

Only one gift is defined to begin with. The item "Thank You Gift" is a T-shirt you'll see in the tip-jar's contents window. You may replace this, and add as many new gifts as you wish.

Drop items corresponding to each GIFT line into the tip-jar's content window. You must have copy and transfer permissions to an item to offer it as a gift: but you will probably wish to set its "Next Owner" permissions to disable further transfers, and encourage anyone else wanting the gift to make a donation of their own.

(We had to set the "Next Owner" permissions of the "Thank You Gift" T-shirt to allow copy and transfer to let you off it as a gift. If you plan to do so, remember to disable the transfer permission.)

Unlike THANKS lines, GIFT lines need not start from 1 dollar: if you wish, you may restrict even the first gift to donors giving a minimum amount.

If you do not wish to give gifts at all, simply delete this line.

FLOATING TEXT

    FLOATING TEXT:

    1 = *** PLEASE DONATE! ***
    2 = JUST CLICK BELOW - THANK YOU
    3 = ALL-TIME DONATIONS: $@AAT
    3 = DONATIONS THIS @PER: $@PAT
    2 = TARGET: $@TGA
    3 = STILL TO GO: $@TAR
    3 = TIME LEFT: @TTL
    2 = LAST DONATION: $@MRA
    3 = FROM: @MRD

The lines above define the "floating text" which will be displayed over the tip-jar.

The numbers before the "=" sign determine which of three colours (defined though the tip-jar's menu - see above) will be used for each line. Only the first 254 characters (less a few for line breaks) will be shown in each colour.

Bear in mind that if a line is too long, it will be broken over two lines, and this may overlap text displayed in another colour. There isn't a fixed limit - the maximum length of a line depends partly on the width of the letters - but the best advice is to keep the lines short.

The three letter codes prefixed by "@" symbols are tokens, and will be replaced by other information when the text is displayed. For instance, "@PAT" will be replaced by the total donated in the current period. If a line contains a token with no value - for instance, if no donations have been made this month and a line contains "@PAT" - the line will not be displayed.

The following tokens are available:

@AD1..5 - all-time donations donor 1..5
@AA1..5 - all-time donations amount 1..5
@AAT - all-time donations amount in total
@ACT - all-time donations count
@PER - period word: WEEK, MONTH, QUARTER, YEAR, or blank
@PD1..5 - period donations donor 1..5
@PA1..5 - period donations amount 1..5
@PAT - period donations amount in total
@PCT - period donations count
@MRD - most recent donor
@MRA - most recent amount
@TGA - target amount
@TAR - target amount remaining
@TTL - target time left

The tip-jar will cycle between the basic statistics above, and the top all-time donors, top period donors, and general information "about" text below.

    ALL-TIME DONORS TEXT:

    1 = ALL-TIME: $@AAT (@ACT donation(s))
    2 = TOP DONATIONS
    3 = @AD1: $@AA1
    3 = @AD2: $@AA2
    3 = @AD3: $@AA3
    3 = @AD4: $@AA4
    3 = @AD5: $@AA5

    PERIOD DONORS TEXT:

    1 = THIS @PER: $@PAT (@PCT donation(s))
    2 = TOP DONATIONS
    3 = @PD1: $@PA1
    3 = @PD2: $@PA2
    3 = @PD3: $@PA3
    3 = @PD4: $@PA4
    3 = @PD5: $@PA5

    ABOUT TEXT:

    1 = Welcome to our venue!
    2 = We hope you enjoy your stay.
    3 = -
    3 = Please consider donating
    3 = to help towards our costs.
    3 = -
    3 = No obligation, and no minimum,
    3 = but every little helps!

Lines left blanks in the notecards are ignored. If you wish to leave a blank line in any of the text displayed, just put a single dash ("-") on a line.

API

If you are a scripter, you may wish to program other objects to respond to donations.

You can do this by listening on channel -99. When a donation is made, the following message will be sent region-wide:

    DONATION, <donorname>, <donorid>, <amount>

So, for instance, if Shan Bright donated $100, any listeners on channel -99 would hear:

    DONATION, Shan Bright, 4b16ad11-0a56-4627-8eb6-4c88a9850fb5, 100

Note that the will be NULL_KEY if you added the donation through the [ADD] option on the main menu.

TIPS

* Offer gifts, and change the gifts you offer regularly! Donors naturally like to feel that their donations are appreciated, and while a thank you message is nice, a gift - even a modest one - has greater impact. Change the gifts often: regular donors will be bored by receiving the same item repeatedly.

* Don't disable manual entry! Suggested donations are great - sometimes people feel embarrassed about donating because they are unsure how much it is appropriate to give, and suggested payments are reassuring. But others will have a donation in mind, and may choose not donate at all if they cannot give that amount. Even if $1 is not a suggested donation, don't be sniffy about receiving it: those Lindens mount up. And if someone wishes to donate $1000, they may not have the patience to make twenty $50 payments.

* Log in to your account on the Second Life website at secondlife.com, display your transaction history, and filter the transactions by the name of your tip-jar. This will give you a detailed report of all the donations made (and not just the top 5), along with the date and time of each. If you have more than one tip-jar, give them unique names, but with some common text (like "Tip-Jar 1", "Tip-Jar 2", and so on), so that you can use the common text to filter all the tip-jars together, or an individual jar.

FOR MORE INFORMATION CONTACT...

Shan Bright
Chief Executive Officer