Cisco BBSM 5.3 SDK Developer Web Page Guide
4 - Creating Custom PDA Page Sets
Downloads: This chapterpdf (PDF - 205.0KB) The complete bookPDF (PDF - 1.78MB) | Feedback

Creating Custom PDA Page Sets

Table Of Contents

Creating Custom PDA Page Sets

PDA Page Set Overview

Using ASP Files in PDA Page Sets

BBSM PDA Template Page Sets

MinuteICS/MinuteICSClear

RADIUSUBand/RADIUSUBandClear

Testing Your PDA Page Set


Creating Custom PDA Page Sets


This chapter describes PDA page sets and how to create custom page sets for a PDA. Because BBSM already works on wireless laptops, this chapter provides the sample ASP files that allow BBSM to differentiate between wireless devices—laptops and PDAs. These files allow either wireless device to begin initiating a session through BBSM. The new logic can distinguish between wireless devices and redirect the end user to the relevant web pages.

If you are creating a custom PDA page set, we recommend that you read this entire guide, especially "Creating Custom Page Sets." The principles for creating PDA page sets are the same as those for creating other page sets, and the same assumptions are made regarding the developer's familiarity with technologies.

You must also download the PDA page set templates from the BBSM download web site. They do not ship with BBSM. Refer to the "Using ASP Files in PDA Page Sets" section.

You also need a PDA to test your page set. Although the sample pages that follow were developed for iPAQ PDAs with Pocket PC, they can be modified for other types of PDAs.

PDA Page Set Overview

Four sample PDA page sets were developed and are described in this section:

RADIUSUBand

RADIUSUBandClear

MinuteICS

MinuteICSClear

All of the ASP files to be used with PDAs have a prefix of SM_ followed by the standard naming procedure that BBSM uses.

When developing your PDA page set, we recommend that you follow the flow used for the standard page sets to maintain a look and feel that is similar to the other page sets. This similarity will maintain a consistent end-user experience.

Certain limitations exist when developing page sets for the PDA and BBSM:

The most obvious limitation is that the viewable display on a PDA is 240 by 320 pixels, which means that the standard graphics must be reduced and text length must be kept in mind.

Also, the PDA does not support multiple browser windows, such as BBSM's pop-up toolbar window that allows the end user to disconnect and end their session. Therefore, the sample page sets do not support WebPrint or BandwidthBoost.


Note The end user must be informed that to deactivate the session, the PDA must be turned off or the wireless NIC must be removed. BBSM accomplishes this with a pop-up dialog box.


Using ASP Files in PDA Page Sets

The PDA Template download contains the ASP files to be used with PDAs. The PDA templates are contained in a ZIP file that is available for download from the following URL:

http://www.cisco.com/cgi-bin/tablebuild.pl/bbsm53

To use these ASP files, you must copy them into the c:\atcom\ekgnkm\ folder, or the folder that you will be using for your custom page sets.

The SDK provides the following PDA ASP files:

The Package, Start, and Post ASP files for the sample page sets discussed in the "BBSM PDA Template Page Sets" section.

The following ASP files (discussed below) that contain methods to make the PDA page sets function properly and are specific to PDAs. These files are mandatory to ensure proper functioning and must be placed in your PDA page set folder:

SM_CommonSubroutines.asp

SM_detectDevice.asp

The following sample ASP files (discussed below) that are created for PDAs

SM_default.asp

SM_iporterror.asp

SM_searching.asp

SM_unavailable.asp

The SM_disconnect page that is reserved for future use.

Although you can use any of the non-PDA ASP files for PDAs, you need to create a PDA version of the non-PDA ASP file that contains modified graphics to fit the PDA screen so the graphics will display properly on the PDA. To name your PDA ASP file, you can use the SM_xxx.asp format, where xxx is the name of the non-PDA ASP file.

After you create your PDA ASP file, you must add two lines of code at the top of the corresponding non-PDA ASP file after the existing <%@ LANGUAGE="JSCRIPT" %> line of code, as follows:

Existing line:

<%@ LANGUAGE="JSCRIPT" %>

Add these two lines:

<% var strSMPortal="SM_xxx.asp" %>

 

<!-- #INCLUDE File="SM_detectDevice.asp" -->


You will also need to modify the c:\atcom\ekgnkm\preconnect2.asp file as follows:

Existing code:

<%@ LANGUAGE="JSCRIPT" %>
<%
Response.ExpiresAbsolute = "1/1/1980";
obj = Server.CreateObject ("NotifyBilling.NotifyBilling.1");
Response.Redirect (obj.PreConnect (
"http://%iport%/ekgnkm/searching.asp",
"http://%iport%/ekgnkm/iporterror.asp",
"http://%iport%/ekgnkm/unavailable.asp",
"http://%iport%/ekgnkm/maxcapacity.asp",
"http://%iport%/ekgnkm/PortmapOnTheFly%site%/PrePortmapOnTheFly.asp",
"http://%iport%/ekgnkm/deactivated.asp"));
%>
<% // BBSM ProductVersion 5.3.0 %>


New code:

<%@ LANGUAGE="JSCRIPT" %>
<%
Response.ExpiresAbsolute = "1/1/1980";
obj = Server.CreateObject ("NotifyBilling.NotifyBilling.1");
strAgent = Request.ServerVariables("HTTP_USER_AGENT");
strCheckPDA = new RegExp("CE");
bIsPDA = strCheckPDA.test(strAgent);

if (bIsPDA)
{
Response.Redirect (obj.PreConnect (
"http://%iport%/ekgnkm/SM_searching.asp",
"http://%iport%/ekgnkm/SM_iporterror.asp",
"http://%iport%/ekgnkm/SM_unavailable.asp",
"http://%iport%/ekgnkm/maxcapacity.asp",
"http://%iport%/ekgnkm/PortmapOnTheFly%site%/PrePortmapOnTheFly.asp",
"http://%iport%/ekgnkm/deactivated.asp"));
}
else
{
Response.Redirect (obj.PreConnect (
"http://%iport%/ekgnkm/searching.asp",
"http://%iport%/ekgnkm/iporterror.asp",
"http://%iport%/ekgnkm/unavailable.asp",
"http://%iport%/ekgnkm/maxcapacity.asp",
"http://%iport%/ekgnkm/PortmapOnTheFly%site%/PrePortmapOnTheFly.asp",
"http://%iport%/ekgnkm/deactivated.asp"));
}
%>
<% // BBSM ProductVersion 5.3.0 %>


SM_CommonSubroutines.asp

The SM_CommonSubroutines page offers end users the option of using radio buttons to make selections instead of using the standard drop-down menus. Because of the PDA size limitation, a new method, GenerateCheckBoxes, was developed for this purpose. Use this method to generate HTML RADIO tags of bandwidth, price, and service packages.

SM_detectDevice.asp

The SM_detectDevice page allows for distinction between devices. Each time a program, called user agent, requests a page from a web server, it sets an environment variable called HTTP_USER_AGENT. This variable contains the user agent name, and, in some cases, additional information such as the operating system that the user agent runs under.

In the following example, the user agent string is being parsed for the CE OS tag that the PDA uses. If found, the end user is redirected to the PDA pages.

<%
strAgent = Request.ServerVariables("HTTP_USER_AGENT");
strCheck = new RegExp("CE");
bIsIn = strCheck.test(strAgent);
if (bIsIn)
{
Response.Redirect(strSMPortal);
}
%>


SM_default.asp

The SM_default.asp has the same functionality as the non-PDA default page located in the c:\atcom\ekgnm folder of the BBSM server and performs the same function. For a description of the default page, refer to the "System and Error Messages" section.

To use this file for your PDA page set, the following three lines of code must appear at the top of the default page. The first line already exists in the file. The next two lines must be added, as follows:

Existing line:

<%@ LANGUAGE="JSCRIPT" %>

Add these two lines:

<% var strSMPortal="SM_default.asp" %>

 

<!-- #INCLUDE File="SM_detectDevice.asp" -->


SM_iporterror.asp

The SM_iporterror.asp has the same functionality as the non-PDA iporterror page located in the c:\atcom\ekgnm folder of the BBSM server and performs the same function. For a description of the iporterror page, refer to the "System and Error Messages" section.

To use this file for your PDA page set, the following three lines of code must appear at the top of the iporterror page. The first line already exists in the file. The next two lines must be added, as follows:

Existing line:

<%@ LANGUAGE="JSCRIPT" %>

Add these two lines:

<% var strSMPortal="SM_iporterror.asp" %>

 

<!-- #INCLUDE File="SM_detectDevice.asp" -->


BBSM PDA Template Page Sets

The page set names are kept the same for both the standard pages and the PDA pages so that either device type can follow the path set for that page set without the need for any configuration changes. Table 4-1 shows the PDA page sets and the access and accounting policies that they use.

Table 4-1 BBSM PDA Page Sets and Associated Access and Accounting Policies

Page Set
Access
Policy
Accounting
Policy
See section and page

MinuteICS
MinuteICSClear

Minute

ICSCreditCard

MinuteICS/MinuteICSClear

RADIUSUBand
RADIUSBandClear

RADIUS

Null

RADIUSUBand/RADIUSUBandClear


MinuteICS/MinuteICSClear

The MinuteICS page set combines the Minute access policy with the ICSCreditCard accounting policy. The page set prompts the end user to enter credit card information to access the Internet on a per-minute basis. BBSM performs credit card authentication and billing through the CyberSource ICS billing server.

An alert pop-up dialog box has been added to the posting page to inform the end user on how to end the session. For this page set, the end user is told to turn off the device or remove the wireless NIC to end the session.

The MinuteICSClear page set is similar to the MinuteICS page set, but it does not use SSL to transmit information to the BBSM server. For additional information on SSL security, refer to the Cisco BBSM 5.3 SP1 Configuration Guide.

To use the MinuteICS or MinuteICSClear page set with PDAs, follow the steps below.


Step 1 In MinuteICSStart.asp, add the following line of code after the existing <%@ LANGUAGE="JSCRIPT" %> line of code, as follows:

Existing line:

<%@ LANGUAGE="JSCRIPT" %>

Add this line:

<!-- #INCLUDE File="SM_detectDevice.asp" -->


Step 2 In the MinuteICSPackage file, insert this line near the top of the file:

var strSMPortal = "SM_MinuteICSStart.asp";



SM_MinuteICSPackage.asp

The SM_MinuteICSPackage page, which the end user does not see, contains configuration information for the page set. The page contains the values for the options described in the Minute Access Policy section in the Cisco BBSM 5.3 Interface SDK Developer Guide. The default configuration for the MinuteICS page set appears below:

var strPageToCheck = "MinuteICS";
var dApprovalAmount = 10.00;


The package file also defines the price and bandwidth arrays. Each array provides the pricing options for the bandwidth packages that the page set uses to generate a combo box, which allows the end user to select a package when Bandwidth Manager is enabled. The default bandwidth packages for the MinuteICS page set appear below:

var PackagePriceArray = new Array
(
0.33, // package 1, 0.33
0.25, // package 2, 0.25
0.20, // package 3, 0.20
0.15, // package 4, 0.15
0.10 // package 5, 0.10
);

var PackageKbpsArray = new Array
(
0, // package 1, full speed
512, // package 2, 512 Kbits/sec
256, // package 3, 256 Kbits/sec
128, // package 4, 128 Kbits/sec
64 // package 5, 64 Kbits/sec
);


SM_MinuteICSStart.asp

The SM_MinuteICSStart page is the first one that the end user sees. It displays a different user interface depending on whether or not Bandwidth Manager is enabled. The page contains a form that prompts the end user to enter credit card information. If Bandwidth Manager is enabled, the page also displays a combo box of bandwidth packages along with the credit card form. The form contains the following information:

Text input:

Cardholder Name

Street Address

City

State/Province

Zip Code

Country

Phone Number

Credit Card Number

Select input:

Expiration Month

Expiration Year

Submit button: Submit Information

When the end user presses the Submit Information button, SM_MinuteICSStart.asp invokes SM_MinuteICSPost.asp.

SM_MinuteICSPost.asp

The SM_MinuteICSPost page processes the information submitted by SM_MinuteICSStart.asp and calls the Minute access policy's SendActivateSession method to activate the end user's session. The page specifies the ICSCreditCard accounting policy as the first parameter in SendActivateSession and strAccountingInfo as the accounting information parameter. The page builds strAccountingInfo from the parameters submitted by the end user.

strAccountingInfo =
<CCard>" +
<Name>" + strName + "</Name>" +
<Acct>" + strCC + "</Acct>" +
<ExpYr>" + strExpYear + "</ExpYr>" +
<ExpMo>" + strExpMonth + "</ExpMo>" +
<Addr>" + strAddress + "</Addr>" +
<City>" + strCity + "</City>" +
<St>" + strState + "</St>" +
<ZIP>" + strZipCode + "</ZIP>" +
"<Cntry>" + strCountry + "</Cntry>" +
"<Ph>" + strPhone + "</Ph>" +
"</CCard>";

strErrorURL = AccessPolicyMinute.SendActivateSession
(
"ICSCreditCard",
strAccountingInfo,
"SM_ICSError.asp",
"Error.asp ",
PackagePriceArray [intPackage - 1],
PackageKbpsArray [intPackage - 1],
dApprovalAmount
);


BBSM activates the session and performs an accounting authorization transaction in the background. After a slight delay, the page redirects the end user to the portal page. The delay gives AtDial enough time to receive and process the activate session message, and it gives the user interface a chance to display a "connecting..." page.

If the authorization transaction succeeds, BBSM allows the end user's session to continue.

If the authorization transaction fails, the server performs a forced redirect to SM_ICSError.asp.

If the credit card validation method fails, the server performs a forced redirect to SM_MinuteICSStart.asp and displays a validation error message.

SM_ICSError.asp

BBSM serves this page to the end user as the result of a forced redirect after an authorization failure. The SM_ICSError page displays to the end user a message indicating that the credit card authorization failed. The page displays a button that allows the end user to try again. If the end user clicks the button, BBSM serves the SM_MinuteICSStart page, which prompts the end user to enter credit card information again.


Note This page set allows the end user access to the Internet before BBSM knows the result of the authorization transaction. Because the credit card server response time varies, the end user may have access to the Internet for several minutes before BBSM receives a denial and performs a forced redirect to the SM_ICSError page.


RADIUSUBand/RADIUSUBandClear

The RADIUSUBand page set combines the RADIUS access policy with the Null accounting policy. The page set prompts the end user to enter a RADIUS username and password to access the Internet. It also permits the end user to select their desired bandwidth at a specified price. For more information on the RADIUSUBand page set, refer to the "RADIUSUBand and RADIUSUBandClear" section.

An alert pop-up dialog box has been added to the posting page to inform the end user on how to end the session. For this page set, the end user is told to turn off the device or remove the wireless NIC to end the session.

The RADIUSUBandClear page set is similar to the RADIUSUBand page set, but it does not use SSL to transmit information to the BBSM server. For additional information on SSL security, refer to the Cisco BBSM 5.3 SP1 Configuration Guide.

To use the RADIUSUBand or RADIUSUBandClear page set with PDAs, follow the steps below.


Step 1 In RADIUSUBandStart.asp, add the following line of code after the existing <%@ LANGUAGE="JSCRIPT" %> line of code, as follows:

Existing line:

<%@ LANGUAGE="JSCRIPT" %>

Add this line:

<!-- #INCLUDE File="SM_detectDevice.asp" -->


Step 2 In the RADIUSUBandPackage.asp file, insert this line near the top of the file:

var strSMPortal = "SM_RADIUSUBandStart.asp";



SM_RADIUSUBandPackage.asp

The SM_RADIUSUBandPackage page, which the end user does not see, contains configuration information for the page set. The page contains the values for the options described in the described in the RADIUS Access Policy section in the Cisco BBSM 5.3 Interface SDK Developer Guide.

The following is the default configuration for the SM_RADIUSUBand page set:

var strPageToCheck = "RADIUSUBand";


The package file also defines the price, bandwidth, and service type arrays. Each array provides the pricing options for the bandwidth packages for that service type that the page set uses to generate radio buttons. The following are the default bandwidth packages for the SM_RADIUSUBand page set.

var PackagePriceArray = new Array
(
.20, // package 1, .20 per minute
.10 // package 2, .10 per minute
);

var PackageKbpsArray = new Array
(
0, // package 1, full speed
64 // package 2, 64 Kbits/sec
);

var PackageServiceArray = new Array
(
"Platinum", // Premium package
"Gold" // Average package
);


SM_RADIUSUBandStart.asp

The SM_RADIUSBandStart page is the first page that the end user sees after redirection. It contains a form that prompts the end user for a RADIUS username, password, and package selection. The form contains the following:

Text input:

Username

Password

Radio button: Package

Submit button: Login

When the end user presses the Login button, SM_RADIUSUBandStart.asp invokes SM_RADIUSUBandPost.asp.

SM_RADIUSUBandPost.asp

The SM_RADIUSUBandPost page processes the information submitted by SM_RADIUSUBandStart.asp and calls the RADIUS access policy's SendActivateSession method to activate the end user's session. The page passes the username, password, and bandwidth price/kbps to the SendActivateSession method:

strErrorURL = AccessPolicyRADIUS.SendActivateSession
(
strUserName,
strPassword,
"SM_RADIUSUBandStart.asp?msg=ServerFail",
"SM_RADIUSUBandStart.asp?msg=Fail",
"SM_RADIUSUBandStart.asp?msg=Busy",
"iporterror.asp?msg=SendActivateSession+failed",
PackagePriceArray [intPackage - 1],
PackageKbpsArray [intPackage - 1]
);


If the SendActivateSession method succeeds (indicated by an empty string return value), BBSM activates the end user's session and, after a slight delay, redirects the end user to the portal page. The delay gives AtDial enough time to receive and process the activate session message, and it gives the user interface a chance to display a "connecting..." page.

If the RADIUS username or password is invalid, SM_RADIUSUBandPost.asp redirects the end user to SM_RADIUSUBandStart.asp and displays a fail error message.

If the site is configured to disallow duplicate RADIUS sessions and the username is being used by another session, SM_RADIUSUBandPost.asp redirects the end user to SM_RADIUSUBandStart.asp and displays a busy error message.

If the RADIUS server cannot be accessed at the time, SM_RADIUSUBandPost.asp redirects the end user to SM_RADIUSUBandStart.asp and displays a server fail error message.

Testing Your PDA Page Set

If your page set uses SSL, you must have a valid certificate installed on your server to test your pages. If you do not have a certificate installed, you will be unable to view the secure pages when you connect a client. You can make your BBSM a certificate authority and sign your own certificate to test secure page sets. For instructions on requesting and installing a test SSL certificate on a BBSM server, refer to the Cisco BBSM 5.3 Interface SDK Developer Guide.


Caution This procedure should only be used on a development server. It should never be used on a release server.

If you want to debug the ActiveX server components used in your pages, install the Microsoft development environment on your BBSM server and refer to the section that describes the standalone debugging components in the Cisco BBSM 5.3 Interface SDK Developer Guide.

Follow these steps to test your completed PDA page set.


Step 1 Configure your access point on the BBSM server.

Step 2 From the BBSM Dashboard on the server, click WEBconfig.

Step 3 In the NavBar, click Network Elements, and then click Access Points.

Step 4 Click Port Settings. The Port Settings window pops up.

Step 5 From the Page Set drop-down menu, select your page set. The Start Page text box automatically populates with the URL of your Start page.

Step 6 Click Save.

Step 7 Open the browser on the different wireless clients. The appropriate Start page for that device should be displayed.

Step 8 Emulate the end user's experience and test your pages.