3. Building a Web Signal
After the Web Signal has been registered and RIM has
provided the information needed to deliver content to devices, it’s
time to build the system to manage push subscriptions. The push
application needs a database and a processing system to manage
any interaction with subscribers and to manage delivery of the content
to subscribers through the RIM Push Infrastructure. When it comes to
pushing the content to subscribers, any sort of scheduled or triggered
process works; the option selected depends on the nature of the service
being provided and how often new data is available.
The database is used to maintain a table of
subscriber information. At a minimum, each subscriber needs to have a
unique ID assigned to them by the push application; through this ID,
RIM can identify a push recipient for the Web Signal. An application
can create its own IDs for subscribers, but it’s probably easiest to
just use the subscriber’s email address because they’re already unique
by their very nature.
The database can store additional information, such
as the subscriber’s preferences for the service and any other
information needed to manage delivery of content to the subscriber. If
subscribers are being charged for the service, this is also probably
where the application would maintain information about the subscriber’s
subscription expiration, renewal date, and so on.
3.1 Web Signal Domains
Throughout the remainder of the Web Signals
discussion, the examples reference the Web Signals domain to use in the
URLs the push application should use to interact with the system. The
push application should use the appropriate domain, based on the
location where the push is being performed. RIM has implemented
regional Network Operations Centers worldwide, and through these
regional centers, pushed content is processed. Because of this
regionalization, the push application should use the correct domain
information when submitting any request. RIM currently supports three
regions; Table 3 describes the scope of each region and lists the appropriate domain to use for each.
Table 3. Web Signals Production Domain Regions
| Region | Scope | Web Signals Domain |
|---|
| na | North America, Latin America, South America, and Africa | push.na.blackberry.com |
| eu | Europe | push.eu.blackberry.com |
| ap | Asia-Pacific | push.ap.blackberry.com |
RIM allows developers to use a test domain when
building and debugging their push applications. The application needs
to transition to one of the production domains when ready to roll out a
version of the service to subscribers. The domain information for the test domains is provided when partners are approved for the service.
3.2 Web Signal Subscriber Registration
The first step in the process to create a Web Signal
is to implement the registration process required by RIM. There’s no
reason the push application can’t expand on the concepts explained
here, but at a minimum, the application must complete the steps
outlined in this section.
As previously shown, the Web Signals registration
process consists of several actions on the part of the subscriber. The
subscriber first requests access to the service, and then confirms
their acceptance of RIM’s terms and conditions for Web Signals before
they can participate.
The starting point for this is typically a link from
a web page or even a registration form located on a website. On the
push application’s Web Signal’s registration form, the application
should gather whatever information is needed regarding the user—it
could be as much as their contact information or as little as nothing.
If the application will assign a unique Push User ID (PUID) to every
subscriber, there might not be any information that needs to be
collected. The email address is a useful value to collect from a
subscriber. It’s useful because it’s a unique identifier that can be
used to identify the subscriber, but also because it provides a
reliable way to communicate with the subscriber outside of the Web
Signal push process. For the AccuWeather service, the PUID is assigned
automatically in the URL used to register for the service.
The subscriber can begin the registration process
from a desktop browser, but it must be completed from the device
browser, so the Web Signals infrastructure can obtain the information
it needs to be able to correctly identify the subscriber’s device. If a
push application allows subscribers to register for the service using a
desktop browser, the subscriber is sent a link they can activate from
their BlackBerry browser on the device to complete the process.
The link that completes the process is the link to
the End User Web Signals Service Agreement. The application does this
by redirecting them to a special URL in the following format:
https://[push-domain]/mss/PM_subReg?puid=[puid-value]&
sid=[sid-value]
The values in brackets refer to values that need to
be replaced with the specific options for the particular request, as
defined in Table 4.
Table 4. Web Signals Registration URL Components
| Parameter | Value |
|---|
| Push-Domain | The regional domain that the push recipient resides in. Refer to Table 3 for the possible values for this parameter. |
| PUID-Value | A
unique Push User ID (PUID) that you have assigned to this subscriber.
RIM uses this identifier to identify this subscriber for all subsequent
activities related to the Web Signal. |
| SID-Value | The Service ID (SID) assigned to this Web Signal by RIM. |
For example, if an application with a SID of
MyWebSignal was registering a North American subscriber and assigned a
Push User ID (PUID) of someuser@somedomain.com, the registration URL would look like this:
https://push.na.blackberry.com/mss/PM_subReg?
puid=someuser@somecompany.com&sid=mywebsignal
At this point, the mobile user is presented with the page shown in Figure 4. If the subscriber accepts the agreement, the Success URL provided during registration (described in Table 1)
is triggered with the PUID appended to the end of the URL. For example,
if, during registration, an organization provided a success URL of
https://ws1.someserver.com/s_registration
at the conclusion of a successful registration for
the Web Signal, the following URL would be triggered by the RIM Push
Infrastructure:
https://ws1.someserver.com/s_registration?
puid=someuser@somecompany.com
If the subscriber does not accept the agreement, the Failure URL provided during registration (described in Table 1)
is triggered with the PUID appended to the end of the URL. For example,
if during registration an organization provided a failure URL of
https://ws1.someserver.com/f_registration
at the conclusion of a failed registration for the
Web Signal, the following URL would be triggered by the RIM Push
Infrastructure:
https://ws1.someserver.com/f_registration?
puid=someuser@somecompany.com&rc=[response-code]
The options for response-code are defined in Table 5.
When the registration process fails, it is the responsibility of the
push application to process the response code and display a useful page
for subscribers so they can tell what to do next.
Table 5. Web Signals Registration Response Codes
| Response Code | Description |
|---|
| 0100 | A SID was not provided in the registration URL. |
| 0101 | The subscriber did not accept the terms of RIM’s end user agreement. |
| 0102 | The PUID was not provided in the registration URL. |
| 0103 | The specified PUID has already been registered for the Web Signal associated with the SID. |
| 0104 | The SID included in the request has expired or is not valid. |
| 0105 | The PUID included in the request is not valid (contains invalid characters, is too long, and so on). |
| 1000 | The Web Signals service is currently not available. |
