hippoUPDATE User Guide

Contents of this document

Welcome and Introduction
1 Guide to the Server
1.1 Settings in the ‘_config’ notecard
1.2 The server’s menu commands
2 Setting up your products
3 Configuring your products
4 Using the hippoUPDATE website
5 Advanced information for expert scripters

Welcome and Introduction

Thank you for choosing the hippoUPDATE Automatic Product Update Server, allowing you to easily keep your customers up to date with the latest version of your products. Amongst its key features:

  • Almost unlimited capacity; fill it with as many product updates as you like.

  • Powered by HippoTech Virtual Server technology and therefore not reliant on Second Life object keys. What does that mean? It means you can take your server into inventory and re-rez it without any problems.

  • Subversion support, allowing you to number your product versions x.y.z (e.g. 1.0.2) if you wish.

  • Fast, efficient and crash free, with most of the heavy lifting done outside of Second Life using industry-standard PHP/SQL technology.

  • Dual communications protocols mean more reliable communication between product and update server at times of high Second Life lag.

  • Monitor your servers and logs of who got updates and when, using the hippoUPDATE website.

This notecard contains the following sections:

1. Guide to the Server
A quick tour around the server and its various features and functions.

2. Setting up your products
How to load the hippoUPDATE server with your updates ready to send to customers.

3. Configuring your products
How to make your products work with your new hippoUPDATE server.

4. Using the hippoUPDATE website
Monitoring your servers, products and keeping track of your customers using logs.

5. Advanced information for expert scripters
More technical scripting information for script wizards.

1. Guide to the server

Using the server is very straightforward. On the front you will see two LCD-style displays that instantly inform you how many products it has within it and how many updates it has given. If you right-click the server to edit it and examine its contents (if you don't know how to this, consult the various Second Life help resources available) you will see two important notecards: "_config" and "_products". The former allows you to edit various important server options whilst the latter is where you list your various products. Once its configuration is loaded, you control the server using simple menu commands.

1.1 Settings in the ‘_config’ notecard

Options in the "_config" notecard consist of a command in capitals, then a colon, the the specific details. E.g. SERVER NAME: My First Server. There now follows a description of each command you can set.

e.g. SERVER NAME: Acme Industries Update Server
- Specify the name you wish to use to refer to your server (maximum 40 letters long). Choose your name carefully, as it will be used in your products to make contact with your server when they check for updates.
* Note: You cannot have two servers with the same name; so if you have other HippoTech Virtual Servers rezzed, be sure to choose a unique name.

PASSWORD: <text>
e.g. PASSWORD: topsecret
- The password helps to protect your server against false attempts to access your products. We recommend you use a combination of letters and numbers. The maximum length is 40 characters.

e.g. SHOW NAME: No
- Specify whether you wish the server's name to float above it in hovertext.

- Specify whether you wish the server's status to float above it.

- If you wish, the server will show in hovertext how many false attempts to get updates from it have been made.

- Sets the colour to use for hovertext; the server knows the colour names red, green, yellow, blue, pink, black, white.
* For Advanced Users: You can also use a colour vector instead, e.g. HOVERTEXT COLOUR: <0.4, 0.3, 0.2>.

e.g. VERBOSE: Yes
- If you turn verbose mode on, the server will read out in chat each product's details as it loads them (see section 2 below).

- Determine whether the server should automatically register itself and go online after it has loaded its configuration. If you say "no", then you will need to click it and choose the 'Register' option to take it online.

e.g. OTHER MANAGERS: Kermit Frog, Miss Piggy, Pathfinder Linden
- If you'd like other managers to be able to use the server's menu commands, list each name here, separated by a comma. Please note that if you wish your managers to be able to edit the "_config" and "_products" notecards, then this requires you to grant them modification rights in your Second Life Friends window.

Once you're done editing settings, save the "_config" notecard.

1.2 The server’s menu commands

To use the server menus, click the server and pick the command you want within 60 seconds (or the server stops listening to menus, to save lag). Each command is described below. First, we have the options available when the server is "Offline" (e.g. disconnected from the network and unable to give out updates).

- Connect the server to the network, registering it under the name in its "_config" notecard, and take it online. One of three things may happen:
(a) The server registers fine.
(b) You are told you appear to have renamed the server and asked if this is correct. Be careful renaming servers as you may confuse products that have the old name embedded in their scripts.
(c) Nothing. If the server has not got online after 60 seconds, try registering again, there may be an internet problem. This is very, very rare.

- Reload the server's "_config" notecard.

- Give this notecard.

Once the server is online, the menus change slightly.

- Take the server temporarily offline so it won't give out updates. Useful if you're updating all your products.

- Loads the "_products" notecard ready to give out updates.

- Allows you to see either all the products in your server (and details of how many of each have been given out) or every Virtual Server you have registered.

- Leads to a further set of menus. COUNTERS allows you to reset the products-given-out-counter and/or the false attempts counter. UNREGISTER takes the server offline *and* removes it from the HippoTech Virtual Server database. Since you can only rez six Update Servers at any one time (which should be fine, as one is all most people need), this is a quick way to "claim back" one of your six slots. If all this sounds a bit complex, don't worry --- 99% of people will never need to worry about or use this command!

- Reports your avatar key (you'll need to use this in the script you use in your products that chats with the update server).

- Reset the server, take it offline, and load its "_config" notecard afresh. Use this if you've edited the "_config" notecard and wish to apply your new settings.

- Give this notecard.

2. Setting up your products

Details of your products are listed in the "_products" notecard which you can edit. Please note that before doing so, you should ensure you have at least picked a name and password for your server (see above if you haven't). Here are some basic things to remember:

(a) Each product must be listed on its own line in the "_products" notecard.
(b) Each product cannot take up any more than 255 characters (that's for its name, notecard, object ... everything ... this is a Second Life limit. If you keep your objects named a sensible length and don't try and turn messages sent to customers into essays, you should be fine).
(c) The only limit to the number of the products is the size of a Second Life notecard ... so, in theory, you should have no problems using one server to update every item you sell.

A line in the "_products" notecard should be formatted like this:

<product name>; <version in server>; <inventory object to give out>; <notecard to give out>; <instant message text to send>

Note --- since the server uses semicolons (;) to separate items, please don't use a semicolon in your product names or instant message text.

Here is an example:

Electric Penguin; 2.1; Electric Penguin HUD v.2; Electric Penguin Release Notes; Here's your new Electric Penguin - please delete your old one.

A few brief notes on each item:

PRODUCT NAME: this bears no relation to inventory objects but is the name used to identify this particular product.
VERSION: Can be any whole (e.g. 1), decimal (e.g. 2.3) or subversion style number (e.g. 1.2.4).
INVENTORY OBJECT: The name of the object in the server's inventory to give out to customers.
NOTECARD: If you wish to also give a notecard out, then insert it's exact name, as in the server's inventory, here.
MESSAGE: The server can also send a short instant message along with the update.

Please note that the notecard and message fields can be left blank, so this will work:

Toaster; 1.2; Fully Working Toaster v1.2;

Or, if you wish to send no notecard but do want to send a message, you would do it like this:

Toaster; 1.2; Fully Working Toaster v1.2;; Here's the new toaster --- happy breakfasting!

Note the two ;; before the message --- effectively this tells the server "don't send a notecard to this person".

Once you have entered a new line for each of your products into the "_products" notecard, you can use the "Load" menu command (the server must be online) to read it in. *Before clicking 'Load' do make sure you've inserted each object and notecard you intend to give into the server, otherwise you'll get an error message. You can copy items into your server by CTRL dragging them from your inventory, or by opening the server's contents in the Edit tab of the build window. For more information on this, consult the various Second Life help resources available.

Once your "_products" notecard is successfully loaded, congratulations! Your update server is running and ready to give updates to your customers. All you need to do is modify your products slightly so they can talk to the server and you're done.

3. Configuring your products

** VERY VERY IMPORTANT - Before including the scripts we've provided in your own products, set permissions to NO TRANSFER and NO MODIFY. Otherwise your customers may pass them on to their friends and you'll end up giving free updates to the entire world! You'll find our scripts give you a warning when you activate them if you haven't done this properly.

If you're a capable scripter, you may wish to read section 4 below for information on how to more tightly integrate our technology into your product. Otherwise, read on for the easy way.

To make your product "update ready", you must insert one of two scripts into your products. Both are found in your HippoTech Updater Server folder:

- zht_OnRezUpdateCheck will check for updates when a product is rezzed (so is useful for attachments, e.g. HUD devices, which 'rez' when a user logs into SL wearing them).

- zht_TimedUpdateCheck will check for updates on a regular basis (the default is once per day).

Once you've added the script to your object's inventory:

- Make sure the script is running (open it, tick the check box at the bottom left of the window)

- Set its permissions to NO MODIFY and NO TRANSFER (or your customers can open it and find your server and password details, or pass it onto friends)

- Add your server name, password, product name, version and your key in the spaces provided in the script. Remember that the server name and password must match, exactly, those in your server's configuration notecard. The product name must match a product in your "_products" notecard. And the version is the *version of this current product*, not the version you'll be giving them. The server checks to see if the version number on the server is higher; if it is, the product is updated, if not, then the server does nothing as they're using the latest version.

- Save the script and check it saves happily with no errors.

Once you've done this, you are ready to sell your product with update technology built in! We would, of course, recommend testing the update works. (The on rez check can be tested by rezzing the product fresh from inventory; the timer can be tested by setting the time to a short interval, then saving the script. Once it works, edit the time back to something sensible).

If you're a competent scripter you could also easily modify one of the provided scripts to check for updates in different ways; for example, using an 'Update' button in a menu dialog.

4. Using the hippoUPDATE website

All Hippo Technologies Virtual Server products allow you to monitor (and in some cases interact) with them via the internet, when you're not able to get into Second Life, perhaps. To do this, you first need to register with us:

(a) Rez the "HippoTech Website Registration Pass" you'll find in your Update Server folder in your inventory.

(b) It will communicate with our website and give you a password (via Owner Say, although it appears in chat history), so nobody listening can hear it. You can later change it to something more memorable if you wish.

(c) Visit and enter your Second Life name and the password you were just given. If you don't like the provided password, you can change it to something more meaningful by visiting the "My Account" part of the website. **Do not, ever, under any circumstances, use the same password for our website as for Second Life. Instead, make up an entirely new password. We recommend a combination of letters and numbers that cannot be guessed!**

(d) You can now browse your registered servers and view the products within them. (If the 'hippoUPDATE icon is not lit on the home page, make sure you've rezzed and turned online at least one update server).

(e) You can delete a server via the website by clicking the red 'x' button to the right of it's name. Note, for safety, this does not delete it inworld --- it will however no longer give out updates.

(f) You can manually send an update to somebody by clicking the arrow icon to the far right of the product name, entering the recipient's name on the next page, then clicking the 'Deliver' button.

(g) You can view logs of who got what updates and when by clicking on the 'Logs' link (under the big 'hippoUPDATE' title at the top of the page). You'll see the time, date, product, version and who got it. Logs can be sorted in various ways (use the arrows at the top of columns), filtered (click the 'Filter' button and enter some criteria) and viewed with data grouped by date or product name (click the grouping links in the far right hand column to see how this works). You can also view data in CSV format, suitable for saving and loading into e.g. Microsoft Excel from here.

5. Advanced information for expert scripters

You'll see information above on how to format a llMessageLinked() call to trigger an update check. What we have not told you so far is that the two update scripts (both the ‘on rez’ and ‘timed’ varieties) transmit a linked message back to tell you the result of the update request. This linked message is transmitted with number -2948813, so is unlikely to clash with any of your linked message scripting. The text string passed is a code to tell you what happened:

If all is well, you'll get this message:

"SUCCESS" - an update was given to the customer. (You don't know whether the customer accepted the inventory, LSL can't detect that).

And if the update wasn't given, you'll get one of these messages:

"OFFLINE" - update server was offline, so no update given.
"SERVER" - no server with the specified name was found.
"PASSWORD" - the password did not match that in the server.
"PRODUCT" - no product of that name is known by the server.
"VERSION" - the version on the server is the same, or older, than the current one the customer has.
"MISSING" - the object that should be given was missing from the server's inventory
"TIMEOUT" - 60 seconds went by and no response was heard. (E.g. there may be internet communication problems).
"GIVENALREADY" — the update has already been given to the customer (in fact -<time in seconds since they got it> will be appended to the error message, e.g. "GIVENALREADY-34132". In the update script you can specify how many seconds must elapse before an update can be given to a customer again.

Technical note - some of these messages are passed back by XMLRPC which, at times of high lag, can be unreliable. If you write your script to take note of them, bear this in mind. (The update script sends update requests to the server via both XMLRPC and email, this duel-communications protocol enabling deliveries to succeed even when Second Life’s XMLRPC server is on the blink).