WAP Push Quick Start

WAP Push Quick Start

Follow this step-by-step guide to quickly setup and start using WAP Push. After completing these instructions, you will be able to push content to WAP 1.2.1 compatible phones using the Openwave WAP Push Library and Push Proxy Gateway. For an overview of the WAP Push Library, click here.
1. Download the Openwave WAP Push Library

DOWNLOAD the Openwave WAP Push Library (free of charge).
2. Install the WAP Push Library on Your PC

Install the WAP Push Library by executing the download file: Openwave_WAP_Push_Java_1.0.jar
3. Create a Subscriber on the Openwave Developer Mobile Access Gateway (MAG)

To receive pushed content, you need to create a subscriber account. Test subscribers provisioned on the Openwave Developer MAG receive pushed content via the same version of Openwave Push Proxy Gateway (PPG) deployed by network operators.

Visit the Mobile Access Gateway Provisioning section of the Openwave Developer web site for instructions on how to sign-up for a developer provisioning account. When you sign-up, a test subscriber is automatically created for you.

After you sign up, view your WAP subscriber and copy the Client ID (IP Address) and Subscriber ID values for future reference. You need the client ID to configure your phone simulator device settings (see step 5, below). You need the subscriber ID to specify the recipient of your pushed content (see step 8, below).


If you are using Openwave SDK 6.1 or 6.2, you will also need the Client ID in hexadecimal:

4. Download and Install Openwave SDK 5.1 or higher

Use Openwave Mobile Browser 5.0 (or higher) to test the full range of content supported by the Openwave WAP Push Library. The library and browser both implement the WAP 1.2 Push Access Protocol (PAP).

DOWNLOAD SDK 5.1 or higher

Install the SDK by executing the downloaded file
5. Configure the Phone Simulator Device Settings. If you are using SDK 5.1, follow steps 5a, b, and c. If you are using SDK 6.1, or 6.2, skip to step 5d.

Select Openwave SDK 5.1 -> Openwave SDK 5.1 from the Windows Programs menu to launch the SDK.

Select Simulator -> Device Settings from the SDK pull-down menu. The following dialog is displayed:

Configure the device settings as follows:
a. Clear the Homepage field so that it contains no value. The subscriber homepage is served automatically by the Mobile Access Gateway.
b. Click on the Proxy 2 radio button, and then enter the following field values to configure the simulator as a client device on Openwave’s Developer MAG:

Field	Value
Address	devgate2.openwave.com
Server Port	9203
Client ID Format	IP Address (IPv4 Packet Circuit)
Client ID	Your IP Address (see step 3, above)

c. Click the OK button to commit your changes. This results in the simulator connecting to the MAG and displaying the subscriber home page. If you are using SDK 6.1 or 6.2, skip to step 6.
d. Configure the Phone Simulator Device Settings for SDK 6.1 or 6.2 (If you are using SDK 5.1, skip to step 6). Make sure you downloaded and installed the WAP simulator plug-in for SDK 6.1 or 6.2. You need this add-on to the SDK 6.1 or 6.2 main package in order to connect to a WAP gateway.
e. The "Openwave SDK 6.2 (or 6.1) WAP" shortcut and menu item point to a .cmd batch file, which by default, is located at C:/Program Files/Openwave/SDK 6.2/program/wap/OSDK62wap.cmd.

f. Open up this file in your favorite editor:

You will need to set the –g and the -clientid flags. Te –g value is the address of the gateway where the subscriber was provisioned. The -clientid value should be set to the hexadecimal version (minus the first 4 digits) of the clientid you created for SDK6.2 (or 6.1). In the example below, which shows a sample subscriber profile on edevgate, the clientid should be set to 040A1040850000. Ensure that you use the correct client ID for your SDK. The command string should be set to:
start /b osdk62wap.exe -g edevgate.openwave.com -clientid 040A1040850000 -clearcache -secure -pho OPWV-SDK-62.pho -sethome http://developer.openwave.com/dhome5.cgi.
g. Save the cmd file and launch the SDK.

WAP Push Quick Start cont.

6. Launch the Push Initiator Tool (PushIT)

Select Openwave WAP Push Library Java 1.0 --> Push Initiator Tool from the Windows Programs menu to launch the PushIT tool. When the tool launches, a black console window appears before the GUI is displayed. You can minimize the console window since all data is entered via the GUI.

The PushIT tool GUI launches with the Push Submission screen displayed. The Push Submission screen provides everything you need to send a Push Submission with any payload type. For complete usage guidelines, refer to Chapter 8 of the WAP Push Library Developer's Guide [link to local document “developer_guide.pdf” ](.pdf).

To push an Service Indication (aka "Alert") to the simulator, complete the following steps:
7. Specify the PPG Address

Select View --> Options from the PushIT pull-down menu to display the Options dialog. Make sure the PPG address field value includes the correct domain of the Openwave Developer MAG (the default value) where you provisioned your subscriber, as shown here:

Click on the OK button to confirm.
8. Specify the Recipient / Subscriber

Click on the Select button on the Push Submission screen to display the Select Recipients dialog. Click on the New Recipient button to display the Add Recipient dialog.

Enter your Subscriber ID (see step 3, above) in the Recipient field. Click on the Subscriber id radio button to specify the client ID format. When you are done, the Add Recipient dialog should look like this:

Click on the OK button to confirm. Click on the ">" button to add the new recipient to the recipient list. When you are done, the Select Recipient dialog should look like this:

Click on the OK button to confirm.
9. Specify the Push Content Type

Click on the Add button on the Push Submission screen to display the first page of the Add Content Type wizard. Click on the Service Indication radio button as shown below:

NOTE: Openwave WAP Push Library supports four types of content, each which can be composed by clicking on the associated radio button: o Service Load -- Push a WML deck o Service Indication -- Push an alert that links to a WML deck o Cache Operation -- Push a WAP cache operation o Custom -- Carrier-defined custom content For more information on the above content types, refer to Chapter 3 of the WAP Push Library Developer's Guide (.pdf).

10. Specify the Alert Text and URL

Click on the Next button to display the next page in the Add Content Type wizard.

In the Alert text field, enter the text you want to display to the end user when the alert appears on the phone. This should be a short string that identifies the WAP service, e.g. "Openwave News Flash". For more information on how to create user-friendly alerts, refer to the WAP Push Application Style Guide [ link to local html file “WAP Push Application Style Guide.htm”].

In the Href field, enter a public URL that you know will return a valid WML deck. This could be your own WAP service home page or the Openwave corporate home page as shown below:

Click on the Finish button to confirm.
11. Send the Push Submission

Click on the Preview button on the Push Submission screen to display the Message Preview window. This window contains the actual XML content that will be posted to the PPG when you send the push submission.

Click on the Close button to dismiss the Message Preview dialog.

Select View --> PPG Response Window to display the PPG Response window. This window will display the response from the PPG after you send the push submission.

Click on the Send button on the Push Submission screen to send the push submission.

If the push submission is successful, the PPG Response window will display a successful response from the PPG. If the PPG does not respond, see the Appendix on troubleshooting.
12. View the Alert

Re-launch the SDK if it isn't already running. If the alert was successfully delivered by the PPG to the phone simulator, Mobile Browser displays the following message containing the alert text:

Note for this particular phone that is simulated, the blue light on the top right of the phone flashes, notifying the user that there is a new WAP Push message in the WAP Push inbox. If you select View, the browser fetches the alert URL (e.g. the Openwave home page).

If the alert does not appear, see the Appendix on troubleshooting. Otherwise, congratulations on successfully sending and receiving WAP Push content using Openwave SDK and WAP Push Library!

Appendix: Troubleshooting

This section provides troubleshooting tips for the most common problems encountered with the WAP Push development environment. If you still cannot resolve your problem after reading this section, visit the WAP Push FAQ and Discussion Area on the Openwave Developer Forum.

No response from the PPG

If the PPG does not respond, make sure that your PC is connected to the Internet and can access the PPG address. Try entering the PPG address using a conventional Web browser (Netscape or IE):
http://devgate2.openwave.com:9001/pap If you can access the URL, the web browser will display either a blank page or the error message:

Bad Request. Not understood due to malformed syntax. Error 0x3 : HTTP Syntax Error, Service only provides support for HTTP POST methods.
The above message is normal, since the PPG rejects anything other than a well-formed WAP push request.

If you get a 404 Not Found error, then you need to contact your network administrator and make sure that your firewall is configured to allow outgoing HTTP requests to port 9001.

Alert not delivered from the PPG to the phone simulator

If the alert does not appear on the phone simulator, first try restarting the simulator by selecting Simulator -> New Session from the SDK pull-down menu. If the alert does not immediately appear, click on the Status Query button in the PushIT tool icon menu to display the Status Query screen. Send a Status Query to the PPG using the same Push ID that was generated for the previous Push Submission. For instructions on how to interpret the Status Query response, refer to Chapter 7 of the WAP Push Library Developer's Guide (.pdf) under the section: Examining the PPG Response Message.