This document is for BeOS developers who want to use the Kagi registration service for their products. The most recent version is 1.3 and requires the BeOS R4 to run. For accompanying information, see my Kagi on BeOS web site.
In case you haven't been to either the Kagi or my web site, here's a short summary of the process: You go to the Kagi web site to sign up as an author, after which you will be assigned an author code. You customize the Register application using the KagiAuthor application, entering your product code and other appropriate information. Somewhere in your product's documentation or "readme" file you give some short instructions on opening the Register application to register the product. Then you bundle up your product and the Register application and watch the money roll in!
Getting Started
The author package comes as a zip file, which extracts to the Kagi Author folder. It contains this .html file, a revision history, the Register and KagiAuthor applications.
The KagiAuthor app must be in the same folder as the Register app when you open it. A window will open titled Author Customization and there should be an Example Product showing in the Product Entry popup menu. The controls and fields are described below.
It will look for the file with the name "Register" so you must leave it with that name while you are customizing it. However, you can name it anything you want when you go to ship it.
Product Entry
The popup menu in this part of the window contains a list of the products which will be presented to the user in the Selection page. By default, there is only one called "Example Product." You can use the buttons to add, delete, or rename the products in the menu. If you have only one product to offer, you can simply click the Rename button and you will see a dialog prompting you to call it what you like. Similarly, adding a product to the list is done by clicking on the Add button, and giving it a name.
Entry Details
This area of the window lets you enter information about your product. Changes for a particular product are saved in memory when selecting a different product from the Product Entry menu, or clicking Rename or Add. Changes are not saved to the Register application's resources until you click the OK button at the bottom of the window. Clicking Cancel discards any changes you have made to any of the products.
Author
The name which you have registered with Kagi should be entered here. It will be included in any output when the user chooses to register via E-Mail so that Kagi can identify you as the author of a product the first time it is registered (barcode info is used for printed output).
Comment
Any information you want passed back to you when a product is registered can be placed here. For example, you can put "Version 1.0" or "Uploaded to Be web site" or anything else you want. When Kagi receives a registration, it will forward the information to you from this Comment field.
Single User
Type in the number of US dollars you are charging for a single user license for your product. You can also specify different prices for a range of quantities. The syntax is as follows:
You can specify more than one, separated by commas. For example, the string "1-2/25,3-8/20,9-100/18" means that you are charging $25 for one or two licenses, $20 for three to eight licenses, and $18 for nine or more licenses.[start]-[end]/priceSite
Type in the number of US dollars you are charging for a site license. If you type in nothing, the checkbox for Site License will be disabled when the user selects a product.
World
Type in the number of US dollars you are charging for a world-wide license. If you type in nothing, the checkbox for World Wide License will be disabled when the user selects a product.
Code
Type in the keyword identifying the program. This should be a two or three letter identifier assigned to you by Kagi when you signed up with them, followed by two or one character(s), respectively you want to use to identify your product. This is what Kagi uses to identify you via the barcodes on a form printed by the user.
Any Response
Click this box so it is on if you need information from the user about how you can contact them. The Register app will make sure the user has provied either an E-Mail address, or a Postal address so you can get in touch with them.
E-Mail Response
Click this box so it is on if you need an E-Mail address from the user to contact them. If the Postal Response check box is not checked, the postal page in the Register app will indicate that entry of the user's postal address is optional. Don't require this unless you really want to do your business via e-mail, since the user may not have an e-mail address.
Postal Response
Click this box so it is on if you need a postal address from the user to contact them. For example, if you need to send them a printed manual. The page in the Register app will indicate to the user that their postal address is required for the product they have selected.It will also require the postal address if they request a receipt, or if one of the other options which requires you to respond to the user has been checked, and they haven't entered an e-mail address.
Registration Code
Click this box so it is on if the product requires a registration code be sent to the user. You will be notified by Kagi when a user has registered for this product, and then you must send the user their registration code (for activating features, disabling a splash screen, etc.)
Setting this flag means that the Register app will make sure it gets either an EMail or Postal address from the user.
Required Keyword
Click this box if your product uses a registration scheme which requires the user to get some keyword from the product and send it in with the registration, so you can use it to generate the registration code to send back to them to complete the registration.
For example, you can have a program generate a keyword based on a random number or time of day or whatever, and tell the user they must enter it in the Register app when prompted for it. When you receive the registration information, you use whatever algorithm you've chosen to generate a matching registration code and send it to the user.
To complete the registration process, the user types in that registration code in some dialog and the program uses the combination of the keyword and the registration code to "unlock," or otherwise complete the registration process. Your program can use whatever means appropriate to secure the pair such that other users cannot simply grab them and use it to unlock their copy.
As far as the Register app is concerned, this option is the same as the Registration Code check box, requiring some means to respond to the user, but it also enables a part of the Register app's interface to prompt the user for keywords.
Oh, to make it convenient for the user, the Register app uses a standard BTextView field for the keywords, which accepts a drag and drop. The user is less likely to make a mistake typing in a keyword if you provide a place to drag it from in your product.
Export/Import
If the Register app is not behaving the way you expect, it may be that the information you have provided is incorrect. The Export button lets you save a text file which you can send to jbm@kagi.com and explain what it is you want it to do. When you get a fixed version of the file back, you can Import it and things should be fine. Importing can be done either by clicking on the Import button, or by dropping the text file on the KagiAuthor icon in the Tracker.
OK/Cancel
Once you have described all of your products, click the OK button and it will save the appropriate resoures out to the Register app. Then run your Register app and see if your product information is represented properly. If not, Quit the Register app and open the KagiAuthor app again to tweak it.
Admin
Clicking this button brings up a text window which is used to customize various aspects of the Register app. It is basically a string resource editor for Register. You will probably never need to adjust these, but if you do, the following descriptions tell you what the strings affect.
Cash Exchange Rates
These describe the various cash exchange rates used to convert from US dollars, if the user is going to pay with cash. Each line has the following format:
where [menuitem] is what will show up in the popup menu the user can select from if they are using the cash payment method, [conversion] is the exchange rate to get to the foreign currency from US dollars by multiplying, [minpaper1] and [minpaper2] are the two smallest denominations of paper currency for that country, because Kagi only accepts paper currency, and [abbrev] is the abbreviation for the country, used by Kagi in its automation of the payment processing.[menuitem]; ([conversion] [minpaper1] [minpaper2]) [abbreviation]Kagi Shareware Contact
The address, phone, FAX, and e-mail contact for Kagi, which is displayed in the payment information so the user knows where to send their payment.
XXX Header
These are various strings which are placed into the payment information when appropriate, based on the method of payment the user has selected.
Single User String
When the user clicks on a product in the Selection page of the Register app, it brings up a window prompting for license selection. This string is appended to the number of licenses the user has selected using the up/down arrows. So you can change it to something like "source code license." or whatever you want, depending on the nature of your product.
Kagi Shareware Address
This is the E-Mail address the Register app uses to generate a BMailMessage object to send E-Mail via the BeOS mail system. It is used when the user selects Connect from the Transmission page.