BlackBerry Push Service SDKVersion: 1.0.1.11

Getting Started Guide

Published: 2011-01-27SWD-1457222-0127102804-001

Contents1 About this guide................................................................................................................................................ 3

2 Overview........................................................................................................................................................... 4Architecture: Framework for delivering content to BlackBerry devices using push technology...................... 4Overview of creating applications using the BlackBerry Push Service SDK...................................................... 4Contents of the BlackBerry Push Service SDK................................................................................................... 5

3 Running the sample applications and the helper applications......................................................................... 6Components necessary for running the sample applications and the helper applications.............................. 6Prerequisites: Using the default settings in the BlackBerry Push Service SDK setup application..................... 6System requirements: BlackBerry Push Service SDK setup application............................................................ 7

4 Preparing the push server................................................................................................................................. 8Install and configure the JDK............................................................................................................................ 8Installing MySQL in Windows........................................................................................................................... 8

Install and configure a MySQL database................................................................................................... 8Installing MySQL in Linux.................................................................................................................................. 11

Install and configure a MySQL database................................................................................................... 11Download a JDBC driver for MySQL.................................................................................................................. 12

5 Installing the BlackBerry Push Service SDK....................................................................................................... 13Using the default settings in the setup application to get started................................................................... 13BlackBerry Push Service SDK setup applications.............................................................................................. 13Run the BlackBerry Push Service SDK setup application................................................................................... 14

6 Add a database record for the sample push-enabled application to the SDK database.................................. 15

7 Verifying that the push server is configured correctly...................................................................................... 16Verifying the Apache Tomcat installation in Windows..................................................................................... 16

Verify the installation of Apache Tomcat.................................................................................................. 16Verifying the Apache Tomcat installation in Linux............................................................................................ 16

Verify the Apache Tomcat installation...................................................................................................... 16Verify the installation of the sample Push Initiator and helper applications.................................................... 17

8 Configuring the push client............................................................................................................................... 18Prerequisites: Installing the sample push-enabled application on a device..................................................... 18Install the sample push-enabled application on a device................................................................................. 18Configure the sample push-enabled application.............................................................................................. 19Configuration settings for the sample push-enabled application..................................................................... 19

9 Using the sample applications and the helper applications to submit messages............................................. 21Submit a push request message using the DebugPortal helper application.................................................... 21Submit push request messages using the sample Push Initiator...................................................................... 21Query the status of push request messages..................................................................................................... 22

10 Glossary............................................................................................................................................................ 23

11 Provide feedback.............................................................................................................................................. 24

12 Legal notice....................................................................................................................................................... 25

About this guide 1This guide is intended for users who are using the BlackBerry® Push Service SDK for the first time. The goal of thisguide is to help you successfully run the sample applications that are included in the SDK. You can install the SDK ona variety of operating systems with different configuration options and multiple service options. The instructions inthis guide are for users who want to use the SDK on the Windows® or Linux® operating systems and for users whowant to use the push technology of the BlackBerry® Internet Service. This guide is not intended for users who wantto use the push technology of the BlackBerry® Enterprise Server.

Getting Started Guide About this guide

3

Overview 2

Architecture: Framework for delivering content toBlackBerry devices using push technologyThe framework that uses push technology to deliver content to BlackBerry® devices uses a client/server model. Withpull technology, a server waits for a device to request content. In contrast, push technology enables your server toinitiate the content delivery to a device without receiving a request.

The framework includes the protocols, service interfaces, hardware entities, and software entities that you can useto deliver content to BlackBerry devices using push technology.

Component Description

Push Initiator software that submits content to the framework for deliveryPush-enabled application software that interprets and displays the content to the userPush Proxy Gateway (PPG) entity that works as the gateway to the wireless network for the content by acting

as an access point, delivering the content to its final destination, and work like aproxy server

Push Server hardware entity that hosts the Push InitiatorPush Client hardware entity that hosts the push-enabled applicationPAP protocol that the Push Initiator uses to submit the content and the push-related

control information to the PPGIPPP protocol that the PPG uses to deliver the content to the BlackBerry devices (Push

Clients)

Overview of creating applications using the BlackBerryPush Service SDKThe BlackBerry® Push Service SDK contains a set of Java® libraries that you can use to develop applications that usethe push technology of the BlackBerry® Application Platform. The BlackBerry Push Service SDK contains the server-side library, and the BlackBerry® Java® Development Environment 5.0 and later contains the client-side library. The

Getting Started Guide Overview

4

libraries are designed to handle complex use cases and implement best practices, thereby removing the need foryou to write boilerplate code. The APIs provide a consistent programming model that you can follow to develop yourapplications.

You can use the server-side library to develop a Push Initiator to interact with the PPG at a higher level, so that youcan focus on developing other features of your Push Initiator instead of spending time learning how to accomplishinfrastructure-related tasks. The server-side library is separated into components. There are dependencies amongthe components, so if you choose one component, you might need to use one or more of the other components.You can use the components that provide low-level APIs or the components that provide high-level APIs.

You can use the client-side library to develop a push-enabled application for BlackBerry devices running BlackBerry®Device Software 5.0 and later. The client-side library provides connectivity management and application performanceoptimization functionality. The client-side library can help ensure that your push-enabled application performsoptimally on BlackBerry devices and you are able to save development time and effort that is usually spent indeveloping some of the standard application features. The client-side library is called the Push API and it is availablein the net.rim.blackberry.api.push package of the BlackBerry JDE API 5.0 and later. For devices that arerunning software versions earlier than BlackBerry Device Software 5.0, you must build push-enabled applicationswithout using the client-side library.

You can configure the BlackBerry Push Service SDK for public mode or enterprise mode. In public mode, you candevelop Push Initiators that use the BlackBerry® Push Service in the BlackBerry® Infrastructure to deliver content toany device user who subscribes to your service. You must register with Research In Motion to use the BlackBerryPush Service. In enterprise mode, you can develop Push Initiators that use the BlackBerry® Enterprise Server to delivercontent only to users who are activated with the BlackBerry Enterprise Server.

Contents of the BlackBerry Push Service SDKThe BlackBerry Push Service SDK provides the following:

Component Description

Server-side library The server-side library provides the following components: Commons, PAP, Core,Acknowledgement, and Monitoring.

Helper applications The helper applications are a set of web applications or web application templates thatdemonstrate or can be modified to use the BlackBerry Push Service SDK server-sidelibrary. The following helper applications are included with the SDK: DebugPortal,PushSDK, and PAPNotify.

Sample applications The sample applications include the sample Push Initiator and a number of sample push-enabled applications. The sample Push Initiator demonstrates the use of the BlackBerryPush Service SDK. One of the sample push-enabled applications demonstrates the useof the Push API from the client-side library for devices running BlackBerry DeviceSoftware 5.0 and later. The other sample push-enabled applications demonstrate howto build push-enabled applications without using the Push API, and are intended fordevices that are running software versions earlier than BlackBerry Device Software 5.0.

Getting Started Guide Contents of the BlackBerry Push Service SDK

5

Running the sample applications and thehelper applications

3

You can run the sample applications and the helper applications that are available with the BlackBerry® Push ServiceSDK to submit a test push request message. By receiving the content that you submit with the test push requestmessage using the sample push-enabled application on your BlackBerry device, you can better understand how theBlackBerry Push Service SDK works and ensure that your system is correctly set up for developing applications usingthe SDK.

Components necessary for running the sampleapplications and the helper applications

Component Description

Push server Computer with a Windows® or Linux® OSDatabase management system Database management system such as MySQL®, Oracle®, or other third-

party RDBMSDevelopment environment for Java JDK® for your OSJDBC driver JDBC® driver for your databaseServlet container JSP® servlet container (that implements the Java® Servlet Specification)PPG The BlackBerry® Infrastructure or the BlackBerry® Enterprise ServerPush client BlackBerry device

Prerequisites: Using the default settings in the BlackBerryPush Service SDK setup application• Register with Research In Motion to use the BlackBerry® Push Service.• Install and configure a MySQL® database management system.• Obtain a JDBC® driver for MySQL.• Install JDK® 6 or later.• Set the JAVA_HOME environment variable to the installation folder path of the JDK.• Verify that the port numbers 8080 and 8443, which Apache Tomcat™ uses as the HTTP port and HTTPS port, are

open for incoming requests on the server's firewall and are not already in use.• Verify that the IP address 230.0.0.1 and the port number 4446, which are used as the default multicast group

address and the multicast group port for distributed caching through multicasting, are open on the firewall andare not already in use.

Verify that you have the following configuration information available :• Login information for the user account(s) that you created when you installed and configured the database.• BlackBerry® Infrastructure address for use as the PPG base URL.

Getting Started Guide Running the sample applications and the helper applications

6

• Application ID of the sample push-enabled application.• Device port number where the PPG delivers content to and where the sample push-enabled application listens

for content.• Password for the sample push-enabled application.• URL suffix of the result notification URL, if you are using the Push Plus service level.

System requirements: BlackBerry Push Service SDK setupapplication

Item Requirement

Hardware • 64 MB of free RAM• minimum of 8-bit color depth (256 colors)• minimum 640x480 screen resolution

Operating system Any version of the following operating systems, as long as the operating systemsupports Java® 6 or later:

• Windows® XP and Windows Server® 2003 (32-bit and 64-bit x86, Intel®Itanium® 2, and AMD-64)

• Windows Server 2008 (32-bit and 64-bit)• Windows Vista® (32-bit and 64-bit x86)• Windows 2000 and Windows NT® (32-bit x86)• Red Hat® Enterprise Linux® 4 and 5 (x86, Intel Itanium 2, and AMD-64)• SUSE Linux 9 and 10 (x86 and PowerPC)• Linux on zSeries• Other Linux operating systems (POSIX-compliant shell required)Note: Beta and early access releases of these operating systems are notsupported.

Getting Started Guide System requirements: BlackBerry Push Service SDK setup application

7

Preparing the push server 4

Install and configure the JDK1. Download the setup application for JDK® 6 or later for your OS.

2. Run the JDK setup application and complete the instructions on the screen.

3. Set the JAVA_HOME environment variable to the installation folder of the JDK.

Installing MySQL in Windows

Install and configure a MySQL databaseThe following instructions are intended only for computers that are running Windows®.

Before you begin:

Download and install Microsoft® .NET Framework 3.5 or later from www.microsoft.com/downloads/.

1. Download and run the latest Windows® MSI Installer Essentials for MySQL® Community Server 5.1 fromwww.mysql.com.

2. In the setup wizard, click the Typical setup type and follow the instructions on the screen.

3. Select the Configure MySQL Server now check box and click Finish.

4. In the configuration wizard, follow the instructions on the screen and use the default configuration settings,except for the following settings:

a. For the approximate number of concurrent connections to the server, click Online Transaction Processing(OLTP).

b. For the default character set, click Best Support for Multilingualism.

c. For the Windows options, click the Include Bin Directory in Windows PATH check box.

5. If you plan on using the BlackBerry® Push Service SDK setup application on a computer other than the computerwhere you installed MySQL, perform the following actions:

a. On the computer where you plan to run the setup application, download the Windows ZIP archive optionfor MySQL Community Server 5.1 from www.mysql.com and extract the files.

b. In the location where you extracted the files, navigate to the bin folder and copy the filepath.

c. Append the filepath that you copied to the value for the PATH environment variable.

Create a server instance

1. Download and install the MySQL Workbench from www.mysql.com.

2. On the Home screen for the MySQL® Workbench, in the Server Administration section, click New ServerInstance.

Getting Started Guide Preparing the push server

8

3. In the Create New Server Instance Profile wizard, follow the instructions on the screen and use the defaultconfiguration settings except for the settings described in steps 4-6.

4. To specify the host machine for the database server, select the localhost option and click Next.

5. To create the database connection, in the parameters tab, perform the following actions:

a. Leave the values in the Hostname, Port, and Username field to the default values (localhost, 3306, androot).

b. In the Password field, click Store In Vault and type the password that you specified when you installed andconfigured the MySQL database.

c. Leave the Default Schema field blank.

d. Click Next.

6. To specify the operating system of the host machine, do the following:

a. Select Windows.

b. Select the Windows MySQL 5.1 Installer Package that's applicable to you.

7. On the Complete Setup screen, type pushsdk or any desired name for the server instance.

Configure the server instance

1. On the Home screen for the MySQL® Workbench, in the Server Administration section, double-click the serverinstance you created.

2. On the Configuration tab, click the Advanced tab.

3. Select the SQL Mode check box.

4. To have the database behave like a traditional SQL database management system, replace the existing contentof the field with "TRADITIONAL".

5. Click Apply twice.

6. On the Startup tab, click Stop Server.

7. When the Run As prompt appears, clear the Protect my computer and data from unauthorized program activitycheck box and click OK.

8. After the server stops, click Start Server to allow the new configuration to take effect.

9. When the Run As prompt appears, clear the Protect my computer and data from unauthorized program activitycheck box and click OK.

Create the database schema

1. On the Home screen for the MySQL® Workbench, in the SQL Development section, double-click the databaseconnection that you created when you created the server instance for the database.

2. Right-click the Object Browser section, and click Create Schema.

3. In the Name field, specify a schema name (for example, pushsdk).

4. In the Collation drop-down list, select a default collation type.

Getting Started Guide Installing MySQL in Windows

9

If you use UTF-8, for a case sensitive collation type, specify utf8_bin. For a case-insensitive collation type, specifyutf8_general_ci.

5. Click Apply twice.

6. Click Finish to apply the changes to the server instance.

7. To close the new_schema window, click Close.

Create a user account for the database schema

The user account that you set up in this task is the user account that you use to access the database tables througha Push Initiator.

1. On the Home screen for the MySQL® Workbench, in the Server Administration section, double-click the serverinstance that you created.

2. Click the Accounts tab and click Add Account.

3. Click the Login tab and specify a login name and password for the user.

4. In the Limit Connectivity to Hosts Matching field, type one or more names and host machines that the user canconnect from (for example, localhost).

5. Click Apply.

6. On the Schema Privileges tab, in the Users column, click the user account you created.

7. Click Add Entry.

8. In the Host section, select the Selected host option.

9. In the Selected Host drop-down list, click the host machine that you want to define the privileges for (for example,localhost).

10. In the Schema section, select the Selected schema option.

11. In the Selected schema list, click the database schema that you created and that you want to define the privilegesfor.

12. Click OK.

13. Click Select "ALL" to assign the user all privileges for this database schema.

14. Click Save Changes.

Create a new connection to the database schema

1. On the Home screen for the MySQL Workbench, in the SQL Development section, click New Connection.

2. In the Connection Name field, type a name for the connection.

3. In the Hostname field, type the name of the host machine that the server instance is installed on (for example,localhost).

4. In the Port field, type 3306.

5. In the Username field, type the username of the user that you created for the database schema.

6. In the Password field, click Store In Vault.

7. Type the password of the user that you created for the database schema.

Getting Started Guide Installing MySQL in Windows

10

8. In the Default Schema field, type the name of the database schema that you created.

9. Click OK.

Installing MySQL in Linux

Install and configure a MySQL databaseThe following instructions are intended only for computers that are running Linux®.

1. Download MySQL® Community Server 5.1 from www.mysql.com for your Linux distribution.

2. Complete the MySQL installation following the instructions for your Linux distribution available from http://dev.mysql.com/doc.

3. In the command prompt type mysqladmin -u root password "<your_root_password>", where<your_root_password> is the password you would like to specify for the database root user.

4. In the command prompt type mysqladmin shutdown -user=root -password=<your_root_password>, where<your_root_password> is the password you specified for the database root user in the previous step, to stopthe MySQL daemon.

5. Copy my-medium.cnf from the MySQL installation folder to a location of you choice.

6. Rename my-medium.cnf to my.cnf, in the destination location where you copied the file in the previous step.

7. Configure the MYSQL_HOME environment variable to point to the location of my.cnf, to use my.cnf as yourMySQL configuration file.

8. Open the my.cnf file with a text editor and in the [mysqld] section, do the following:

a. Add sql-mode="TRADITIONAL", to configure the database to behave like a traditional SQL databasemanagement system.

b. Add character_set_server=utf8, to use UTF-8 as the default character set.

c. Add collation_server=utf8_bin, to use a case-sensitive collation type, or addcollation_server=utf8_general_ci, to use a case-insensitive collation type.

d. Add skip-character-set-client-handshake, to enforce the use of a UTF-8 encoding in the database.

9. In the command prompt, type mysqld_safe &, to start the MySQL daemon.

10. In the command prompt, type mysql -user=root -password=<your_root_password>, where<your_root_password> is the password for the database root user you specified earlier, to start the MySQLconsole.

11. In the MySQL console, at the command prompt, type CREATE DATABASE pushsdk; to create a database for theBlackBerry® Push Service SDK.

12. In the MySQL console, at the command prompt, type CREATE USER '<username>' IDENTIFIED BY '<password>';where <username> and <password> is your desired username and password, to create a new user withpermissions to perform operations on the database you created in the previous step.

Getting Started Guide Installing MySQL in Linux

11

13. In the MySQL console, at the command prompt, type GRANT ALL ON pushsdk.* TO '<username>'; where<username> is the username for the database user you created in the previous step, to grant permissions tothis user to perform operations on the database.

Download a JDBC driver for MySQL1. Download a JDBC® driver for MySQL® (for example, the Connector/J driver from www.mysql.com).

2. If the file that you downloaded is in an archive format (for example, .zip, .tar.gz, and so on), extract its contents.

3. Copy the .jar file from the extracted contents to a location in your hard drive.

Getting Started Guide Download a JDBC driver for MySQL

12

Installing the BlackBerry Push Service SDK 5

Using the default settings in the setup application to getstartedTo get started running the sample applications and the helper applications, you can use the default settings in thesetup application when you install the BlackBerry® Push Service SDK. Before you can use the default settings in theBlackBerry Push Service SDK setup application, you must sign up to use the BlackBerry® Push Service, install a MySQL®database and the Java® SDK, download a JDBC® driver for MySQL, and configure the JAVA_HOME environmentvariable.

A BlackBerry Push Service SDK installation using the default settings in the setup application carries out the followingactions:

• Installs and configures Apache Tomcat™ as the servlet container• Extracts the distribution files containing the API, sample applications, helper applications, and configuration files• Creates the database tables in your MySQL database for use by the BlackBerry Push Service SDK• Configures the JDBC driver for MySQL to be used by the helper applications• Configures the BlackBerry Push Service SDK to use the BlackBerry® Infrastructure as the PPG• Configures the sample Push Initiator for the Push Plus or Push Essentials service level at the PPG• Configures the sample Push Initiator to not use application-level reliability for submitting push request messages

BlackBerry Push Service SDK setup applicationsThe BlackBerry® Push Service SDK comes with graphical mode and console mode setup applications for the Windows®and Linux® operating systems.

Filename Description

bpss-x.x.x.x.exe graphical mode setup application for the Windows operating system, wherethe x.x.x.x in the file name corresponds to the BlackBerry Push Service SDKversion

bpss-console-x.x.x.x.exe console mode setup application for the Windows operating system, wherethe x.x.x.x in the file name corresponds to the BlackBerry Push Service SDKversion

bpss-x.x.x.x.bin graphical mode setup application for the Linux operating system, where thex.x.x.x in the file name corresponds to the BlackBerry Push Service SDKversion

bpss-console-x.x.x.x.bin console mode setup application of the Linux operating system, where thex.x.x.x in the file name corresponds to the BlackBerry Push Service SDKversion

Getting Started Guide Installing the BlackBerry Push Service SDK

13

Run the BlackBerry Push Service SDK setup application1. Open the setup application for the BlackBerry® Push Service SDK.

2. Accept the default options and complete the instructions on the screen.

3. Specify the user name and password for the user with query, insert, and update permissions to the database.

4. Specify the user name and password for the user with table creation permissions in the database.

5. Specify the location of the JDBC® driver for MySQL®.

6. Accept the default options and complete the instructions on the screen.

7. Specify the ID, password, and device port number for the sample push-enabled application, using the informationfrom the confirmation email that you receive after you register for the BlackBerry® Push Service.

8. For the Service Class field, perform one of the following actions:• If you chose the Push Essentials service level when you registered for the BlackBerry Push Service, select the

Push Essentials option.• If you chose the Push Plus service level when you registered for the BlackBerry Push Service, leave the default

option selected.

9. Complete the instructions on the screen to finish the installation.

Getting Started Guide Run the BlackBerry Push Service SDK setup application

14

Add a database record for the sample push-enabled application to the SDK database

6

In the address field of a web browser, type https://localhost:8443/sample-push-initiator. Press ENTER.The web interface of the Push Initiator appears in the browser.

The sample push initiator adds the database record of the sample push-enabled application to the BlackBerry® PushService SDK database automatically in the background, when the web interface of the Push Initiator appears in thebrowser.

Getting Started Guide Add a database record for the sample push-enabled application to the SDK database

15

Verifying that the push server is configuredcorrectly

7

Before you configure your push client and start delivering content to the sample push-enabled application on thepush client, you can verify that your push server is configured correctly. To verify that your push server is configuredcorrectly, you must make sure that your servlet container, sample Push Initiator, and helper applications wereinstalled correctly.

Verifying the Apache Tomcat installation in Windows

Verify the installation of Apache Tomcat

1. Verify that the value of the CATALINA_HOME environment variable is the filepath for the installation folder forApache Tomcat™ by performing the following actions:

a. Right-click My Computer and click Properties.

b. On the Advanced tab, click Environment Variables.

c. In the System variables section, click CATALINA_HOME. Click Edit.

d. Verify that the variable value is the filepath for the Apache Tomcat installation folder.

2. Navigate to the bin folder in the Apache Tomcat installation folder and double-click startup.bat to start ApacheTomcat.

To stop Apache Tomcat, double-click shutdown.bat.

3. Navigate to the logs folder in the Apache Tomcat installation folder and verify that the log files do not containany errors.

Verifying the Apache Tomcat installation in Linux

Verify the Apache Tomcat installation

1. Verify that the value of the CATALINA_HOME environment variable is the filepath for the installation folder forApache Tomcat™ by performing the following actions:

a. In the command prompt type echo $CATALINA_HOME.

b. Verify that the variable value is the filepath for the Apache Tomcat installation folder.

2. Navigate to the bin folder in the Apache Tomcat installation folder and run startup.sh to start Apache Tomcat.

To stop Apache Tomcat, run shutdown.sh.

3. Navigate to the logs folder in the Apache Tomcat installation folder and verify that the log files do not containany errors.

Getting Started Guide Verifying that the push server is configured correctly

16

Verify the installation of the sample Push Initiator andhelper applications1. To verify the installation of the sample Push Initiator, in the address field of a browser, type a URL for the sample

Push Initiator. Press ENTER.

a. Verify that accessing https://localhost:8443/sample-push-initiator displays a web interface for the PushInitiator.

b. Verify that accessing https://localhost:8443/sample-push-initiator/subscribe returns an rc=10002 error.

2. To verify the installation of the DebugPortal helper application, in the address field of a browser, type a URL forthe DebugPortal helper application. Press ENTER.

a. Verify that accessing https://localhost:8443/debug-portal displays a web interface for the DebugPortal.

b. Verify that accessing https://localhost:8443/debug-portal/subscribe returns an rc=10002 error.

3. To verify the installation of the PushSDK helper application, in the address field of a browser, type a URL for thePushSDK helper application. Press ENTER.

a. Verify that accessing https://localhost:8443/pushsdk/subscribe returns an rc=10002 error.

b. Verify that accessing https://localhost:8443/debug-portal/notification returns an Internal Server Error.

Getting Started Guide Verify the installation of the sample Push Initiator and helper applications

17

Configuring the push client 8

Prerequisites: Installing the sample push-enabledapplication on a device• Verify that the BlackBerry® device that you want to install the sample push-enabled application on is

synchronized with the BlackBerry® Desktop Manager on the computer that you are using.• If you plan to install the sample push-enabled application by using a computer that is not the computer where

you installed the BlackBerry® Push Service SDK, copy the .cod and .alx files for the sample push-enabledapplication to the computer that you are using.

Install the sample push-enabled application on a deviceThe sample push-enabled applications are designed to receive content only from Push Initiators that use theBlackBerry® Infrastructure as the PPG. There are no samples available for BlackBerry devices running a version ofthe BlackBerry® Device Software earlier than 4.2.

When you install sample push-enabled application on a device, you must choose the sample that is compatible withthe version of the BlackBerry Device Software that is running on the device. You can find the .alx and .cod files of thesamples in the folder for the sample push-enabled application, at the location where you installed the BlackBerry®Push Service SDK.

Before you begin:

You need a computer with any version of BlackBerry® Desktop Software 4.6 to 5.0.1 to complete this task.

1. Connect a device to a computer by using a USB cable.

2. Start the BlackBerry® Desktop Manager.

3. If the device requires a password, specify the password and click OK.

4. In the BlackBerry Desktop Manager, click Application Loader.

5. In the Add/Remove Applications section, click Start.

6. Click Browse.

7. Navigate to the sample-push-enabled-app folder and perform one of the following actions:• If your device runs BlackBerry Device Software 5.0 or later, double-click the SamplePushEnabledApp5_0.alx

file.• If your device runs BlackBerry Device Software 4.6 or later but earlier than 5.0, double-click the

SamplePushEnabledApp4_6.alx file.• If your device runs BlackBerry Device Software 4.2 or later but earlier than 4.6, double-click the

SamplePushEnabledApp4_2.alx file.

8. Select the Sample Push Enabled Application check box. Click Next to complete the installation.

Getting Started Guide Configuring the push client

18

Configure the sample push-enabled applicationBefore you begin: Install the sample push-enabled application on a BlackBerry® device.

1. On the Home screen of the device that you installed the sample push-enabled application on, click Sample PushEnabled Application.

2. Press the Menu key.

3. Click Settings.

4. Specify the configuration settings for the sample push-enabled application according to your BlackBerry® PushService SDK installation.

5. Press Back and save the changes.

6. Press the Menu key.

7. Click Register.

8. Type a user name and password of your choice. Click OK.After a short delay to complete the registration process, the message "Request to register executed successfully"appears.Note: Remember the user name that you specify in this step. You need to use it as an address when you submita push request message using the DebugPortal helper application.

Configuration settings for the sample push-enabledapplication

Setting Description

Port • Specifies the port number on the BlackBerry® device where content is received• The value is contained in the confirmation email that you receive after you register

for the BlackBerry® Push Service.Note: This port number is the same as the port number that you specify when youconfigure the sample Push Initiator using the BlackBerry® Push Service SDK setupapplication.

App ID • Specifies the application ID for the push-enabled application• The value is contained in the confirmation email that you receive after you register

for the BlackBerry® Push Service.Note: This ID is the same as the sample push-enabled application ID that youspecify when you configure the sample Push Initiator using the BlackBerry PushService SDK setup application.

Getting Started Guide Configure the sample push-enabled application

19

Setting Description

BPAS URL • Specifies an HTTP version of the PPG base URL that you receive after you registerthe push-enabled application with RIM (for example, if you receive a PPG base URLof https://pushapi.eval.blackberry.com, the BPAS URL is http://pushapi.eval.blackberry.com).

Content Provider URL • Specifies the URL for the server-side application (the sample Push Initiator or theDebugPortal helper application) that receives the subscription request from thedevice. For example, specify https://<push_server_host_name>:8443/sample-push-initiator to receive subscription requests with the sample Push Initiator, orhttps://<push_server_host_name>:8443/debug-portal to receive subscriptionrequests with the DebugPortal, where push_server_host_name is the host nameof the computer where the Push Initiator or the DebugPortal is hosted.Note: The URL must be accessible from the Internet.

App Acknowledgement • Specifies whether the push-enabled application supports application-levelreliability

• This setting must match the setting that you specify when you configure the samplePush Initiator using the BlackBerry Push Service SDK setup application.Note: When you use the setup application to configure the sample Push Initiator,the default value set by the setup application does not configure the sample PushInitiator to use application-level reliability.

Getting Started Guide Configuration settings for the sample push-enabled application

20

Using the sample applications and the helperapplications to submit messages

9

You can submit push request messages for testing purposes using either the sample Push Initiator or the DebugPortalhelper application. If you use the sample Push Initiator, a unique text string for delivery through the push requestmessage is submitted every 5 minutes until you terminate the operation or until 100 push request messages aresubmitted. You can change the settings that specify the total number of push request message submissions and thedelay between the push request message submissions by editing the sample-push-initiator.properties file. If you usethe DebugPortal helper application, you can type any text or attach any file to deliver to the sample push-enabledapplication, as long as it is not more than 8 KB in size.

If you are using the Push Plus service level, you can query the status of the push request messages that you submitted.You can query the status of push request messages only using the DebugPortal because the sample Push Initiatordoes not include this functionality.

Submit a push request message using the DebugPortalhelper applicationNote: There is an 8 KB size limit for each individual push request message.

1. Browse to https://localhost:8443/debug-portal to access the main page of the DebugPortal helper application.

2. On the Push Management menu, click Push.

3. In the Push Id field, specify an ID for the push request.If you leave this field blank, the DebugPortal helper application generates a random ID.

4. In the Push Application drop-down list, click the push-enabled application that you want to deliver content to.

5. In the Addresses field, specify the user name that you created when you configured the push-enabledapplication.

6. Specify a file or type some text for delivery to the push-enabled application.

7. Click Push.

Submit push request messages using the sample PushInitiator1. Browse to https://localhost:8443/sample-push-initiator to access the main page of the sample Push Initiator.

2. Verify that the Application Id field contains the correct ID for your push-enabled application.

3. Click Start General Push.

4. To stop submitting push request messages, click Stop.

Getting Started Guide Using the sample applications and the helper applications to submit messages

21

Query the status of push request messagesYou can query the status of push request messages only if you submit the messages using the Push Plus service level.

1. In the DebugPortal helper application, on the Push Management menu, click Status Query.

2. Specify the parameters for the query. Click Query.

If the push request message submission is successful, the status of the query changes to "DELIVERED".Note: After a push request message submission is successful, there can be a time period of up to a few minutesbefore the status of the query changes from "PENDING" to "DELIVERED". This time period is needed to deliver thepush request message to the sample push-enabled application and to receive the result-notification request messagefrom the BlackBerry® Infrastructure.

Getting Started Guide Query the status of push request messages

22

Glossary 10API

application programming interface

HTTPHypertext Transfer Protocol

HTTPSHypertext Transfer Protocol over Secure Sockets Layer

IPPPInternet Protocol Proxy Protocol

JDBCJava® Database Connectivity

JDKJava® Development Kit

JSPJavaServer® Pages

PAPPush Access Protocol

PPGPush Proxy Gateway

UTF-88-bit UCS/Unicode Transformation Format

Getting Started Guide Glossary

23

Provide feedback 11To provide feedback, visit www.blackberry.com/docsfeedback.

Getting Started Guide Provide feedback

24

Legal notice 12©2011 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, and relatedtrademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in theU.S. and countries around the world.

Apache Tomcat is a trademark of The Apache Software Foundation. Linux is a trademark of Linus Torvalds. MySQLis a trademark of MySQL AB in the United States, the European Union, and other countries. Java, JDBC, JDK, JSP andOracle are trademarks of Oracle America, Inc. Red Hat is a trademark of Red Hat, Inc. Windows, Windows NT, WindowsServer, and Windows Vista are trademarks of Microsoft Corporation. All other trademarks are the property of theirrespective owners.

This documentation including all documentation incorporated by reference herein such as documentation providedor made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" andwithout condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limitedand its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or otherinaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidentialinformation and/or trade secrets, this documentation may describe some aspects of RIM technology in generalizedterms. RIM reserves the right to periodically change information that is contained in this documentation; however,RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to thisdocumentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, productsor services including components and content such as content protected by copyright and/or third-party web sites(collectively the "Third Party Products and Services"). RIM does not control, and is not responsible for, any ThirdParty Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility,performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. Theinclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement byRIM of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED,INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS ORWARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLEQUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM ORA COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCEOR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICESREFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE ORPROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES ANDCONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THEDOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, AREHEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEMTHAT IS THE SUBJECT OF THE CLAIM.

Getting Started Guide Legal notice

25

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BELIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICESREFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT,CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGESFOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSSOF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TOTRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITHRIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTIONTHEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES,COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN ORUNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHEROBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANYLIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THECAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT,NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACHOR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINEDHEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS(INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICEPROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE,AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANYLIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensurethat your airtime service provider has agreed to support all of their features. Some airtime service providers mightnot offer Internet browsing functionality with a subscription to the BlackBerry® Internet Service. Check with yourservice provider for availability, roaming arrangements, service plans and features. Installation or use of Third PartyProducts and Services with RIM's products and services may require one or more patent, trademark, copyright, orother licenses in order to avoid infringement or violation of third party rights. You are solely responsible fordetermining whether to use Third Party Products and Services and if any third party licenses are required to do so.If required you are responsible for acquiring them. You should not install or use Third Party Products and Servicesuntil all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM'sproducts and services are provided as a convenience to you and are provided "AS IS" with no express or impliedconditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liabilitywhatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject toyou agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, exceptto the extent expressly covered by a license or other agreement with RIM.

Getting Started Guide Legal notice

26

Certain features outlined in this documentation require a minimum version of BlackBerry® Enterprise Server,BlackBerry® Desktop Software, and/or BlackBerry® Device Software.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicablethereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS ORWARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THISDOCUMENTATION.

Research In Motion Limited295 Phillip StreetWaterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada

Getting Started Guide Legal notice

27