Since your browser does not support JavaScript, you don't see any navigational toolbars above. For now, please use the navigational links offered at the bottom of each page. We are working on a better solution.

CF WML Tutorial: Sending Notifications

"Notifications" is a phone.com specific implementation of "content push", whereby content is sent to a client rather than leaving it to the client to come request the data. In some ways, it's like an extension to sending an email to a client.

This tutorial is very rough and is missing some information that will be needed for folks entirely new to this stuff. For now, it's offered to assist those who simply need to see the basic steps of getting notifications to work. More information is offered in the phone.com documentation, referenced at the bottom of this page.

The following example will work only with phones (or simulators) that implement the phone.com "up.browser". It presumes that you've installed the phone.com UP.SDK on your machine, or the machine running the ColdFusion code which you will execute below. If you can run the phone.com simulator, you've installed the SDK. If not, go to developer.phone.com to register (free) and get the excellent simulator and documentation. It's very easy to install, use and understand.

1) Get Your Subscriber ID

To make this work, you need to know your "subscriber" id at the phone.com gateway. The instructions for determining this are offered at the developer.phone.com site. Registered developers get a subscriber id automatically, and the site shows you how to display your current one. For instance, it might look like: 123456789-12345_devgate2.uplanet.com

1)b Get the Subscriber ID of a Visitor

If you want to send notification to some other user, you need to determine their subscriber id. You can learn that looking at the variable cgi.http_x_up_subno, which is one of the many variables available when a up-enabled browser visits your server. Following is a simple program that will report the subscriber id and up.link server of a browser executing it:

<CFCONTENT TYPE="text/vnd.wap.wml"><?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
 "http://www.phone.com/dtd/wml11.dtd" >
<wml>
<card>
  <p>
  <cfoutput>
  Your Subscriber ID<br/>#cgi.HTTP_X_UP_SUBNO#
  <br/>
  <cfif cgi.http_x_up_uplink is not "">
    Your server is:<br/>#cgi.HTTP_X_UP_UPLINK#
  <cfelse>
    Server cannot be determined.
  </cfif>
  </cfoutput>
  </p>
</card>
</wml>

You may need to specify that UP.Link Server Host value when sending an alert to a phone not provisioned on the up.link servers.

2) Configure your simulator

Then, to test it with your up.simulator, you need to change the simulator "settings>up.link settings" to "connect through uplink", which means it's communicating via the gateway rather than pure http. While most other testing of WML works in "http" mode, notifications will only be received by the simulator if it's in uplink mode.

The first time you connect via up.link mode, you'll be prompted to establish a key for secure communications. Continue.

3) Synchronize your simulator

On the simulator, you may also need to synchronize your simulator with the subscriber id. The phone.com developer page has a provisioning link that includes the link to do this.

4) Run the Sample Code

Then, run the sample code offered below substituting your subscriber-id and a url to send to the browser for it to link back to (for this kind of alert being demonstrated).

CFSCRIPT-based COM example

Here's an example with pure com calls (assumes you installed the up.link sdk on the server where the code is running, which installs the com objects). Note it's using CFSCRIPT only because most of the process of is just executing methods of the ntfn object (if you play with CFSCRIPT on your own, note that you must have a semi-colon at the end of every line).

<cfobject TYPE="COM" ACTION="CREATE" NAME="ntfn"
 CLASS="Ntfn3Client.Ntfn3Client.1">

<cfscript>
writeoutput('Setting host:' & ntfn.NtfnSetHost("yourserver"));
writeoutput('<p>Posting alert:' & 
ntfn.NtfnPostAlert('yourid','yourwebpage',0,'D---','test',4));
writeoutput('<p>Result:' & ntfn.NtfnGetLastResult());
if (ntfn.NtfnGetLastResult() is "204") {
	writeoutput('<p>Result was ok (204 is good)');
}
</cfscript>

Again, you'd need to substitute yourserver with your UP.link host, something like devgate2.uplanet.com, yourid with your subscriber-id, something like 123456789-12345_devgate2.uplanet.com, and yourwebpage with whatever page (complete url) you wanted the visitor to return to when they got the alert. The 0 indicates that you want the timeout period (of the message is nto delivered) to be set to the maximum allowed on the gateway. The 'D---' describes the kind of tone to generate on the phone. Finally, the title to be sent (which will show to the user) is indicated here as "test". The last parameter, 4, indicates the length of that title string. It shouldn't be required, but it appears to be.

Non-CFSCRIPT-based COM Example

Here's the example done without CFSCRIPT, for those still not comfortable with that:

<cfobject TYPE="COM" ACTION="CREATE" NAME="ntfn"
 CLASS="Ntfn3Client.Ntfn3Client.1">

<cfoutput>
Setting host: #ntfn.NtfnSetHost("yourserver")#
<p>
Timeout value: #ntfn.NtfnGetTimeout()#
<p>
Posting alert:
 #ntfn.NtfnPostAlert('yourid','yourwebpage',0,'D---','test',4)#
<p>
Result: #ntfn.NtfnGetLastResult()#
</cfoutput>
<p>
<cfif ntfn.NtfnGetLastResult() is "204">
	Result was ok (204 is good)
</cfif>

CF_Wireless example

If you download and install the CF_wireless custom tag, you can also achieve this result using:

<CF_Wireless
	action="SendAlert"
	subscriber="yourid"
	url="yourwebpage"
	alert_title="test"
	UPLINK_HOST=yourhost>

More info

The details about these calls, the data to be passed to them, and the results to expect are all documented in the phone.com sdk, tools and api reference, chapter 4.

WML Resources: