BlackBerry_Push_Service_SDK-Getting_Started_Guide--push-1.0.1.11-US by Odane P. Hamilton

BlackBerry Push Service SDK Version: 1.0.1.11 Getting Started Guide

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

Contents 1 About this guide................................................................................................................................................

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

4 4 4 5

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

6 6 6 7

4 Preparing the push server................................................................................................................................. Install and configure the JDK............................................................................................................................ Installing MySQL in Windows........................................................................................................................... Install and configure a MySQL database................................................................................................... Installing MySQL in Linux.................................................................................................................................. Install and configure a MySQL database................................................................................................... Download a JDBC driver for MySQL..................................................................................................................

8 8 8 8 11 11 12

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

13 13 13 14

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

7 Verifying that the push server is configured correctly...................................................................................... Verifying the Apache Tomcat installation in Windows..................................................................................... Verify the installation of Apache Tomcat.................................................................................................. Verifying the Apache Tomcat installation in Linux............................................................................................ Verify the Apache Tomcat installation...................................................................................................... Verify the installation of the sample Push Initiator and helper applications....................................................

16 16 16 16 16 17

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

18 18 18 19 19

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

21 21 21 22

10 Glossary............................................................................................................................................................

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

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

Getting Started Guide

About this guide

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

Overview

Getting Started Guide

Overview

Architecture: Framework for delivering content to BlackBerry devices using push technology The framework that uses push technology to deliver content to BlackBerry® devices uses a client/server model. With pull technology, a server waits for a device to request content. In contrast, push technology enables your server to initiate 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 use to deliver content to BlackBerry devices using push technology.

Component Push Initiator Push-enabled application Push Proxy Gateway (PPG)

Push Server Push Client PAP IPPP

Description software that submits content to the framework for delivery software that interprets and displays the content to the user 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 a proxy server hardware entity that hosts the Push Initiator hardware entity that hosts the push-enabled application protocol that the Push Initiator uses to submit the content and the push-related control information to the PPG protocol that the PPG uses to deliver the content to the BlackBerry devices (Push Clients)

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

Contents of the BlackBerry Push Service SDK

Getting Started Guide

libraries are designed to handle complex use cases and implement best practices, thereby removing the need for you to write boilerplate code. The APIs provide a consistent programming model that you can follow to develop your applications. You can use the server-side library to develop a Push Initiator to interact with the PPG at a higher level, so that you can focus on developing other features of your Push Initiator instead of spending time learning how to accomplish infrastructure-related tasks. The server-side library is separated into components. There are dependencies among the 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 performance optimization functionality. The client-side library can help ensure that your push-enabled application performs optimally on BlackBerry devices and you are able to save development time and effort that is usually spent in developing some of the standard application features. The client-side library is called the Push API and it is available in the net.rim.blackberry.api.push package of the BlackBerry JDE API 5.0 and later. For devices that are running software versions earlier than BlackBerry Device Software 5.0, you must build push-enabled applications without using the client-side library. You can configure the BlackBerry Push Service SDK for public mode or enterprise mode. In public mode, you can develop Push Initiators that use the BlackBerry速 Push Service in the BlackBerry速 Infrastructure to deliver content to any device user who subscribes to your service. You must register with Research In Motion to use the BlackBerry Push Service. In enterprise mode, you can develop Push Initiators that use the BlackBerry速 Enterprise Server to deliver content only to users who are activated with the BlackBerry Enterprise Server.

Contents of the BlackBerry Push Service SDK The BlackBerry Push Service SDK provides the following: Component Server-side library Helper applications

Sample applications

Description The server-side library provides the following components: Commons, PAP, Core, Acknowledgement, and Monitoring. The helper applications are a set of web applications or web application templates that demonstrate or can be modified to use the BlackBerry Push Service SDK server-side library. The following helper applications are included with the SDK: DebugPortal, PushSDK, and PAPNotify. The sample applications include the sample Push Initiator and a number of sample pushenabled applications. The sample Push Initiator demonstrates the use of the BlackBerry Push Service SDK. One of the sample push-enabled applications demonstrates the use of the Push API from the client-side library for devices running BlackBerry Device Software 5.0 and later. The other sample push-enabled applications demonstrate how to build push-enabled applications without using the Push API, and are intended for devices that are running software versions earlier than BlackBerry Device Software 5.0.

Getting Started Guide

Running the sample applications and the helper applications

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

Components necessary for running the sample applications and the helper applications Component Push server Database management system

Description Computer with a Windows® or Linux® OS Database management system such as MySQL®, Oracle®, or other thirdparty RDBMS Development environment for Java JDK® for your OS JDBC driver JDBC® driver for your database Servlet container JSP® servlet container (that implements the Java® Servlet Specification) PPG The BlackBerry® Infrastructure or the BlackBerry® Enterprise Server Push client BlackBerry device

Prerequisites: Using the default settings in the BlackBerry Push 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 and are 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. 6

System requirements: BlackBerry Push Service SDK setup application

Getting Started Guide

• • • •

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 setup application Item Hardware

Operating system

Requirement • 64 MB of free RAM • minimum of 8-bit color depth (256 colors) • minimum 640x480 screen resolution Any version of the following operating systems, as long as the operating system supports 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 not supported.

Getting Started Guide

Preparing the push server

Install and configure the JDK 1. 2. 3.

Download the setup application for JDK® 6 or later for your OS. Run the JDK setup application and complete the instructions on the screen. Set the JAVA_HOME environment variable to the installation folder of the JDK.

Installing MySQL in Windows Install and configure a MySQL database The 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. 2. 3. 4.

Download and run the latest Windows® MSI Installer Essentials for MySQL® Community Server 5.1 from www.mysql.com. In the setup wizard, click the Typical setup type and follow the instructions on the screen. Select the Configure MySQL Server now check box and click Finish. 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. If you plan on using the BlackBerry® Push Service SDK setup application on a computer other than the computer where you installed MySQL, perform the following actions: a. On the computer where you plan to run the setup application, download the Windows ZIP archive option for 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. 2.

Download and install the MySQL Workbench from www.mysql.com. On the Home screen for the MySQL® Workbench, in the Server Administration section, click New Server Instance.

Getting Started Guide

3. 4. 5.

Installing MySQL in Windows

In the Create New Server Instance Profile wizard, follow the instructions on the screen and use the default configuration settings except for the settings described in steps 4-6. To specify the host machine for the database server, select the localhost option and click Next. 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, and root). b. In the Password field, click Store In Vault and type the password that you specified when you installed and configured the MySQL database. c. Leave the Default Schema field blank. d. Click Next.

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.

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

Configure the server instance 1. 2. 3. 4. 5. 6. 7. 8. 9.

On the Home screen for the MySQL速 Workbench, in the Server Administration section, double-click the server instance you created. On the Configuration tab, click the Advanced tab. Select the SQL Mode check box. To have the database behave like a traditional SQL database management system, replace the existing content of the field with "TRADITIONAL". Click Apply twice. On the Startup tab, click Stop Server. When the Run As prompt appears, clear the Protect my computer and data from unauthorized program activity check box and click OK. After the server stops, click Start Server to allow the new configuration to take effect. When the Run As prompt appears, clear the Protect my computer and data from unauthorized program activity check box and click OK.

Create the database schema 1. 2. 3. 4.

On the Home screen for the MySQL速 Workbench, in the SQL Development section, double-click the database connection that you created when you created the server instance for the database. Right-click the Object Browser section, and click Create Schema. In the Name field, specify a schema name (for example, pushsdk). In the Collation drop-down list, select a default collation type.

Getting Started Guide

5. 6. 7.

Installing MySQL in Windows

If you use UTF-8, for a case sensitive collation type, specify utf8_bin. For a case-insensitive collation type, specify utf8_general_ci. Click Apply twice. Click Finish to apply the changes to the server instance. 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 through a Push Initiator. 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14.

On the Home screen for the MySQL速 Workbench, in the Server Administration section, double-click the server instance that you created. Click the Accounts tab and click Add Account. Click the Login tab and specify a login name and password for the user. In the Limit Connectivity to Hosts Matching field, type one or more names and host machines that the user can connect from (for example, localhost). Click Apply. On the Schema Privileges tab, in the Users column, click the user account you created. Click Add Entry. In the Host section, select the Selected host option. In the Selected Host drop-down list, click the host machine that you want to define the privileges for (for example, localhost). In the Schema section, select the Selected schema option. In the Selected schema list, click the database schema that you created and that you want to define the privileges for. Click OK. Click Select "ALL" to assign the user all privileges for this database schema. Click Save Changes.

Create a new connection to the database schema 1. 2.

On the Home screen for the MySQL Workbench, in the SQL Development section, click New Connection. In the Connection Name field, type a name for the connection.

In the Hostname field, type the name of the host machine that the server instance is installed on (for example, localhost). In the Port field, type 3306. In the Username field, type the username of the user that you created for the database schema. In the Password field, click Store In Vault. Type the password of the user that you created for the database schema.

4. 5. 6. 7. 10

Getting Started Guide

8. 9.

Installing MySQL in Linux

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

Installing MySQL in Linux Install and configure a MySQL database The following instructions are intended only for computers that are running Linux速. 1. 2. 3. 4.

5. 6. 7. 8.

Download MySQL速 Community Server 5.1 from www.mysql.com for your Linux distribution. Complete the MySQL installation following the instructions for your Linux distribution available from http:// dev.mysql.com/doc. 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. 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 stop the MySQL daemon. Copy my-medium.cnf from the MySQL installation folder to a location of you choice. Rename my-medium.cnf to my.cnf, in the destination location where you copied the file in the previous step. Configure the MYSQL_HOME environment variable to point to the location of my.cnf, to use my.cnf as your MySQL configuration file. 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 database management 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 add collation_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 MySQL console. 11. In the MySQL console, at the command prompt, type CREATE DATABASE pushsdk; to create a database for the BlackBerry速 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 with permissions to perform operations on the database you created in the previous step.

Getting Started Guide

Download a JDBC driver for MySQL

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 to this user to perform operations on the database.

Download a JDBC driver for MySQL 1. 2. 3.

Download a JDBC速 driver for MySQL速 (for example, the Connector/J driver from www.mysql.com). If the file that you downloaded is in an archive format (for example, .zip, .tar.gz, and so on), extract its contents. Copy the .jar file from the extracted contents to a location in your hard drive.

Getting Started Guide

Installing the BlackBerry Push Service SDK

Using the default settings in the setup application to get started To get started running the sample applications and the helper applications, you can use the default settings in the setup application when you install the BlackBerry® Push Service SDK. Before you can use the default settings in the BlackBerry 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 environment variable. A BlackBerry Push Service SDK installation using the default settings in the setup application carries out the following actions: • • • • • • •

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 applications The BlackBerry® Push Service SDK comes with graphical mode and console mode setup applications for the Windows® and Linux® operating systems. Filename bpss-x.x.x.x.exe

bpss-console-x.x.x.x.exe

bpss-x.x.x.x.bin

bpss-console-x.x.x.x.bin

Description graphical mode setup application for the Windows operating system, where the x.x.x.x in the file name corresponds to the BlackBerry Push Service SDK version console mode setup application for the Windows operating system, where the x.x.x.x in the file name corresponds to the BlackBerry Push Service SDK version graphical mode setup application for the Linux operating system, where the x.x.x.x in the file name corresponds to the BlackBerry Push Service SDK version console mode setup application of the Linux operating system, where the x.x.x.x in the file name corresponds to the BlackBerry Push Service SDK version

Getting Started Guide

Run the BlackBerry Push Service SDK setup application

Run the BlackBerry Push Service SDK setup application 1. 2. 3. 4. 5. 6. 7. 8.

Open the setup application for the BlackBerry® Push Service SDK. Accept the default options and complete the instructions on the screen. Specify the user name and password for the user with query, insert, and update permissions to the database. Specify the user name and password for the user with table creation permissions in the database. Specify the location of the JDBC® driver for MySQL®. Accept the default options and complete the instructions on the screen. Specify the ID, password, and device port number for the sample push-enabled application, using the information from the confirmation email that you receive after you register for the BlackBerry® Push Service. 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. Complete the instructions on the screen to finish the installation.

Getting Started Guide

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

Add a database record for the sample pushenabled application to the SDK database

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速 Push Service SDK database automatically in the background, when the web interface of the Push Initiator appears in the browser.

Getting Started Guide

Verifying that the push server is configured correctly

Before you configure your push client and start delivering content to the sample push-enabled application on the push client, you can verify that your push server is configured correctly. To verify that your push server is configured correctly, you must make sure that your servlet container, sample Push Initiator, and helper applications were installed 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 for Apache Tomcatâ&#x201E;˘ 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.

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

To stop Apache Tomcat, double-click shutdown.bat. Navigate to the logs folder in the Apache Tomcat installation folder and verify that the log files do not contain any 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 for Apache Tomcatâ&#x201E;˘ 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.

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. Navigate to the logs folder in the Apache Tomcat installation folder and verify that the log files do not contain any errors.

Getting Started Guide

Verify the installation of the sample Push Initiator and helper applications

Verify the installation of the sample Push Initiator and helper applications 1.

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 Push Initiator. b. Verify that accessing https://localhost:8443/sample-push-initiator/subscribe returns an rc=10002 error.

To verify the installation of the DebugPortal helper application, in the address field of a browser, type a URL for the 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.

To verify the installation of the PushSDK helper application, in the address field of a browser, type a URL for the PushSDK 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

Configuring the push client

Prerequisites: Installing the sample push-enabled application 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-enabled application to the computer that you are using.

Install the sample push-enabled application on a device The sample push-enabled applications are designed to receive content only from Push Initiators that use the BlackBerry® Infrastructure as the PPG. There are no samples available for BlackBerry devices running a version of the 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 with the version of the BlackBerry Device Software that is running on the device. You can find the .alx and .cod files of the samples 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. 2. 3. 4. 5. 6. 7.

Connect a device to a computer by using a USB cable. Start the BlackBerry® Desktop Manager. If the device requires a password, specify the password and click OK. In the BlackBerry Desktop Manager, click Application Loader. In the Add/Remove Applications section, click Start. Click Browse. 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.

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

Configure the sample push-enabled application

Getting Started Guide

Configure the sample push-enabled application Before you begin: Install the sample push-enabled application on a BlackBerry® device. 1. 2. 3. 4. 5. 6. 7. 8.

On the Home screen of the device that you installed the sample push-enabled application on, click Sample Push Enabled Application. Press the Menu key. Click Settings. Specify the configuration settings for the sample push-enabled application according to your BlackBerry® Push Service SDK installation. Press Back and save the changes. Press the Menu key. Click Register. 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 submit a push request message using the DebugPortal helper application.

Configuration settings for the sample push-enabled application Setting Port

Description

App ID

• •

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 you configure the sample Push Initiator using the BlackBerry® Push Service SDK setup application. 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 you specify when you configure the sample Push Initiator using the BlackBerry Push Service SDK setup application.

Configuration settings for the sample push-enabled application

Getting Started Guide

Setting BPAS URL

Description

Content Provider URL

•

App Acknowledgement

•

Specifies an HTTP version of the PPG base URL that you receive after you register the push-enabled application with RIM (for example, if you receive a PPG base URL of https://pushapi.eval.blackberry.com, the BPAS URL is http:// pushapi.eval.blackberry.com). Specifies the URL for the server-side application (the sample Push Initiator or the DebugPortal helper application) that receives the subscription request from the device. For example, specify https://<push_server_host_name>:8443/samplepush-initiator to receive subscription requests with the sample Push Initiator, or https://<push_server_host_name>:8443/debug-portal to receive subscription requests with the DebugPortal, where push_server_host_name is the host name of the computer where the Push Initiator or the DebugPortal is hosted. Note: The URL must be accessible from the Internet. Specifies whether the push-enabled application supports application-level reliability This setting must match the setting that you specify when you configure the sample Push 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 Push Initiator to use application-level reliability.

Getting Started Guide

Using the sample applications and the helper applications to submit messages

You can submit push request messages for testing purposes using either the sample Push Initiator or the DebugPortal helper application. If you use the sample Push Initiator, a unique text string for delivery through the push request message is submitted every 5 minutes until you terminate the operation or until 100 push request messages are submitted. You can change the settings that specify the total number of push request message submissions and the delay between the push request message submissions by editing the sample-push-initiator.properties file. If you use the DebugPortal helper application, you can type any text or attach any file to deliver to the sample push-enabled application, 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 Initiator does not include this functionality.

Submit a push request message using the DebugPortal helper application Note: There is an 8 KB size limit for each individual push request message. 1. 2. 3. 4. 5. 6. 7.

Browse to https://localhost:8443/debug-portal to access the main page of the DebugPortal helper application. On the Push Management menu, click Push. 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. In the Push Application drop-down list, click the push-enabled application that you want to deliver content to. In the Addresses field, specify the user name that you created when you configured the push-enabled application. Specify a file or type some text for delivery to the push-enabled application. Click Push.

Submit push request messages using the sample Push Initiator 1. 2. 3. 4.

Browse to https://localhost:8443/sample-push-initiator to access the main page of the sample Push Initiator. Verify that the Application Id field contains the correct ID for your push-enabled application. Click Start General Push. To stop submitting push request messages, click Stop.

Getting Started Guide

Query the status of push request messages

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

In the DebugPortal helper application, on the Push Management menu, click Status Query. 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 minutes before the status of the query changes from "PENDING" to "DELIVERED". This time period is needed to deliver the push request message to the sample push-enabled application and to receive the result-notification request message from the BlackBerry速 Infrastructure.

Getting Started Guide

Glossary

API application programming interface HTTP Hypertext Transfer Protocol HTTPS Hypertext Transfer Protocol over Secure Sockets Layer IPPP Internet Protocol Proxy Protocol JDBC Java速 Database Connectivity JDK Java速 Development Kit JSP JavaServer速 Pages PAP Push Access Protocol PPG Push Proxy Gateway UTF-8 8-bit UCS/Unicode Transformation Format

Getting Started Guide

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

Provide feedback

Getting Started Guide

Legal notice

息2011 Research In Motion Limited. All rights reserved. BlackBerry速, RIM速, Research In Motion速, and related trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S. and countries around the world. Apache Tomcat is a trademark of The Apache Software Foundation. Linux is a trademark of Linus Torvalds. MySQL is a trademark of MySQL AB in the United States, the European Union, and other countries. Java, JDBC, JDK, JSP and Oracle are trademarks of Oracle America, Inc. Red Hat is a trademark of Red Hat, Inc. Windows, Windows NT, Windows Server, and Windows Vista are trademarks of Microsoft Corporation. All other trademarks are the property of their respective owners. This documentation including all documentation incorporated by reference herein such as documentation provided or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. 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 this documentation to you in a timely manner or at all. This documentation might contain references to third-party sources of information, hardware or software, products or 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 Third Party 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. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM 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 OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

Getting Started Guide

Legal notice

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NONPERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF 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 OR UNFORESEEN, 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 OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY. THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE 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 BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) 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 ANY LIABILITY 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 ensure that your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry速 Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining 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 Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with RIM.

Getting Started Guide

Legal notice

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 applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION. Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom Published in Canada