Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

Create a web signal registration application

by Retired ‎02-16-2010 03:29 PM - edited ‎09-16-2010 02:27 PM (1,395 Views)

Summary

 

This article applies to the following:

    • BlackBerry® smartphones based on Java® technology
    • BlackBerry® Device Software 4.2.1 and later

Details

 

BlackBerry smartphone users can subscribe to receive different web signals on their BlackBerry smartphones. These web signals allow content providers to push icons that launch content to the BlackBerry smartphones using the BlackBerry® Internet Service and BlackBerry Internet Service Browser.

 

A BlackBerry Application can be used to create a presence on the BlackBerry smartphone to easily enable the user to go to a predetermined web page to register for the web signal. Once the user is subscribed, a new web signal icon will be pushed to the user and the registration application can be easily removed.

 

This is very similar to a web icon (See here), except that the browser launch is initiated by the BlackBerry smartphone user from the application UI.

 

In order to create a web signal registration application, download the code sample and complete the following steps:

  1. Change the package name on all classes.

    Change the package name in all Java files in your project so that the code will be unique to your organization. It is common practice to begin the package name with com.[your organization’s name].[project name].

  2. Set the title of your application.

    Right-click the project, click Properties and then click the General tab. Here you can enter the title of the application, your vendor name, and an application description.

    Note: The title is what will show up on the home screen of the BlackBerry smartphone when the BlackBerry smartphone user scrolls over the icon.

  3. Add an application icon.

    This will be the icon that is displayed on the home screen of the BlackBerry smartphone. To add a custom icon, complete the following steps:

    1. Locate or create your own icon using any standard image editing tool. The image should be approximately 32x32 pixels in size.
    2. Right-click the project, select Add File to Project and navigate to your custom icon.
    3. Once the file is added, right-click on it, click Properties and select the Use as Application Icon check box.

    Note: For information on how to define an application icon, please see here.

  4. Set the values of the four variables in the main method of WebSignalsRegistrationApplication.java class to reflect your web signal.

    The main method contains the following four parameters that must be edited to the specifications of your web signal:

    • title - Name of the web signal that will be displayed in the application
    • url - Full URL path to the web signal registration page
    • instructions - Text string that is shown to the BlackBerry smartphone user explaining the web signal registration and application removal process
    •  bisError - Error message shown to BlackBerry smartphone users if the BlackBerry Internet Service is not available on the BlackBerry smartphone

     

     /*
    * Main method
    * The 4 parameters should be edited to
    * web signal title
    * web signal registration url
    * User Instructions
    * Error message to display if the BIS Browser
    * is not available
    *
    */
    public static void main(String[] args)
    {
    String title =
    "BlackBerry web signal Setup Application";
    String url =
    "http://na.blackberry.com/eng/services/websignals/";
    String instructions =
    "\n" +
    "This application can be used to setup a" +
    "BlackBerry web signal service. " +
    "\n\n" +
    "After you select the register button above, you'll "
    +
    "be taken to a web site to sign up. Upon
    completion, " +
    "a web signal icon will be sent to your device and " +
    "will begin notifying you of periodic updates. " +
    "\n\n" +
    "Once you have received this web signal icon, " +
    "you can remove this setup application " +
    "by selecting the Remove button." +
    "\n";
    String bisError =
    "Your device is not configured to access the " +
    "BlackBerry Internet Service.\n" +
    "Please go to Options > Advanced Options > " +
    "Host Routing Table, bring up the menu and " +
    "select the Register Now.\n" +
    "If you are still experiencing issues, please " +
    "contact your Wireless Service Provider to enable " +
    "the Internet Browser on your device. " +
    "Note: Not all carriers support the BlackBerry " +
    "Internet Service.";

    WebSignalsRegistrationApplication app =
    new WebSignalsRegistrationApplication(title, url, instructions, bisError);
    app.enterEventDispatcher();
    }
    }

     

     

    The following is full code for WebSignalsRegistrationApplication.java.

    // NOTE: You MUST change the package name to reflect your company name
    // package com.acme.blackberry.webicon;
    // NOTE: You MUST change the package name to reflect your
    company name
    // package com.acme.blackberry.websignalsregistrationlauncher;
    import net.rim.blackberry.api.browser.Browser;import net.rim.blackberry.api.browser.BrowserSession;
    import net.rim.device.api.system.Bitmap;
    import net.rim.device.api.system.CodeModuleManager;
    import net.rim.device.api.system.Application;
    import net.rim.device.api.system.ApplicationDescriptor;
    import net.rim.device.api.servicebook.ServiceBook;
    import net.rim.device.api.servicebook.ServiceRecord;
    import net.rim.device.api.io.ServiceBookNotFoundException;
    import net.rim.device.api.ui.UiApplication;
    import net.rim.device.api.ui.container.VerticalFieldManager;
    import net.rim.device.api.ui.component.BitmapField;
    import net.rim.device.api.ui.component.RichTextField;
    import net.rim.device.api.ui.component.ButtonField;
    import net.rim.device.api.ui.component.Dialog;
    import net.rim.device.api.ui.container.MainScreen;
    import net.rim.device.api.ui.Field;
    import net.rim.device.api.ui.FieldChangeListener;
    /*
    * WebSignalsRegistrationApplication.java
    *
    * This application source code creates a UI application that
    * provides functionality to allow a user to launch a browser
    * to a predetermined web signals registration web page. It
    * also provides a way for the user to easily delete the
    * application once Web signals registration has been
    * completed and a web signals icon has been pushed to
    * the user's device.
    * © <your company here>, 2003-2005
    * Confidential and proprietary.
    */
    class WebSignalsRegistrationApplication extends UiApplication
    {
    private String url;
    private String title;
    private String instructions;
    private String bisError;

    /**
    * WebSignalsRegistrationApplication constructor
    * @param title web signal title
    * @param url web signal resistration url
    * @param instructions Instructions
    * @param bisError Error message to display if the BIS
    * Browser is not available
    */
    public WebSignalsRegistrationApplication(String title, String url,
    String instructions, String bisError)
    {
    this.title = title;
    this.instructions = instructions;
    this.url = url;

    createMainScreen();
    }

    /**
    * Creates and lays out the screen elements for the
    * application
    */
    public void createMainScreen()
    {
    // Retrieve the application's icon
    Bitmap appIcon = ApplicationDescriptor.
    currentApplicationDescriptor().
    getIcon();

    // Create title area with given title and application //icon
    int padding = 10;
    TitledBitmapManager titledBitmapField =
    new TitledBitmapManager(title, appIcon, padding);
    // Create user instructions area
    RichTextField instructionsField =
    new RichTextField(instructions);
    // Create launchBrowser button and register button
    //click listener
    ButtonField launchButton = new ButtonField(
    "Register For web signal",
    ButtonField.CONSUME_CLICK |
    ButtonField.NEVER_DIRTY);
    launchButton.setChangeListener(new
    FieldChangeListener()
    {
    public void fieldChanged(Field field, int context) {
    launchBrowser();
    }
    });
    // Create remove button and register button click //listener
    ButtonField removeButton = new ButtonField(
    "I've Registered - Remove Now",
    ButtonField.CONSUME_CLICK | ButtonField.NEVER_DIRTY);
    removeButton.setChangeListener(new FieldChangeListener()
    {
    public void fieldChanged(Field field, int context) {
    removeApplication();
    }
    });

    // Layout screen elements
    int border = 8;
    VerticalFieldManager manager = new
    VerticalFieldManager();
    manager.add(titledBitmapField);
    manager.add(new CenteredFieldManager(launchButton ,border));
    manager.add(new CenteredFieldManager(removeButton, border));
    manager.add(instructionsField);

    // Push the screen
    MainScreen screen = new MainScreen();
    screen.add(manager);
    pushScreen(screen);
    }

    /*
    * Shows an error popup screen to the user if the BIS
    * Service Book is not found
    *
    **/
    private void displayError(String error)
    {
    Dialog.alert(error);
    }

    /*
    * Attempts to launch the given browser to the given url
    * using the BIS browser.
    * If launching this BIS browser cannot be launched then
    * an error is displayed to the user
    */
    public void launchBrowser()
    {
    UiApplication.getUiApplication().invokeLater(new Runnable()
    {
    public void run()
    {
    try
    {
    BrowserSession browserSession =
    createBISBrowserSession();
    browserSession.displayPage(url);
    browserSession.showBrowser();
    }
    catch (ServiceBookNotFoundException sbnfe)
    {
    displayError(bisError);
    }
    }
    });
    }
    /*
    * Attempts to create a browser session through the RIM-
    * hosted BIS gateway to access the Internet.
    * If the system is unable to create a BIS browser session a
    * ServiceBookNotFoundException is thrown.
    *
    * @return BrowserSession
    * @throws ServiceBookNotFoundException if the BIS Service
    * Book cannot be found
    */
    private BrowserSession createBISBrowserSession()
    throws ServiceBookNotFoundException
    // If there are browser services found - search for
    // the BIS Service Record
    {
    ServiceBook sb = ServiceBook.getSB();
    ServiceRecord[] records =
    sb.findRecordsByCid("BrowserConfig");
    String uid = null;
    int numRecords = records.length;
    for( int i = 0; i < numRecords; i++ )
    {
    ServiceRecord myRecord = records[i];
    ServiceRecordHelper myRecordHelper =
    new ServiceRecordHelper(myRecord);
    if( myRecord.isValid() &&
    !myRecord.isDisabled() &&
    myRecordHelper.getConfigType() ==
    ServiceRecordHelper.SERVICE_RECORD_CONFIG_TYPE_BIS )
    {
    uid = myRecord.getUid();
    break;
    }


    if (null == uid) throw new
    ServiceBookNotFoundException(
    "BIS Service Book is not present");
    return Browser.getSession(uid);
    }

    /*
    * Makes a call to remove the application from the device
    * and exits. Because the application is running while the
    * call to delete is made a reboot will be required.
    */
    public void removeApplication()
    {
    int moduleHandle = CodeModuleManager.
    getModuleHandleForObject((Object)this);
    int ret = CodeModuleManager.deleteModuleEx
    (moduleHandle,true);

    if (ret == CodeModuleManager.CMM_OK_MODULE_MARKED_FOR_DELETION)
    {
    CodeModuleManager.promptForResetIfRequired();
    }
    else
    {
    displayError("Unexpected return value " + ret);
    }

    System.exit(0);
    }

    /*
    * Main method
    * The 4 parameters should be edited to
    * web signal title
    * web signal resistration url
    * User Instructions
    * Error message to display if the BIS Browser is not
    * available
    *
    */
    public static void main(String[] args)
    {
    String title =
    "BlackBerry web signal Setup Application";
    String url =
    "http://na.blackberry.com/eng/services/
    websignals/";
    String instructions =
    "\n" +
    "This application can be used to set up a " +
    "BlackBerry web signal service. " +
    "\n\n" +
    "After you select the register button above,
    you'll " +
    "be taken to a web site to sign up. Upon
    completion, " +
    "a web signal icon will be sent to your device and " +
    "will begin notifying you of periodic updates. " +
    "\n\n" +
    "Once you have received this web signal icon, " +
    "you can remove this setup application " +
    "by selecting the Remove button." +
    "\n";
    String bisError =
    "Your device is not configured to access the " +
    "BlackBerry Internet Service.\n" +
    "Please go to Options > Advanced Options > " +
    "Host Routing Table, bring up the menu and " +
    "select the Register Now.\n" +
    "If you are still experiencing issues, please " +
    "contact your Wireless Service Provider to enable " +
    "the Internet Browser on your device. " +
    "Note: Not all carriers support the BlackBerry " +
    "Internet Service.";

    WebSignalsRegistrationApplication app =
    new WebSignalsRegistrationApplication(title, url,
    instructions,
    bisError);
    app.enterEventDispatcher();
    }
    }


    The above code makes use of the following three helper classes, which can be found in the .zip file located here.

    • ServiceRecordHelper.java - A utility class for parsing the data in the service books
    • CenteredFieldManager.java - A manager for centering a field on a single line
    • TitledBitmapManager.java - A manager for laying out a title and icon on a single line
Contributors
Users Online
Currently online: 19 members 2,187 guests
Please welcome our newest community members: