Social and connected

A Super App makes it easy for people to build relationships. The most frequently used applications can help people share their experiences, data, and media with others. For example, an application could help an insurance salesperson retrieve key account details for a client during a meeting, or take a picture of a new item to be added to a policy. In a personal context, an application could help someone coordinate a social event with friends, and share the memories from that event. When your app helps people interact, you make it easy for them to build relationships.

What are the benefits of a social and connected application?

  • Create personal and professional connections between users. When users use your app to share or enrich their experiences, your app helps them create meaningful connections and encourages them to continue to use your app in the future.
  • Share experiences as they happen. Life happens quickly, and your app can be there to help users capture and share the moments that matter the most.

Approaches to connecting

Approach

Examples

Deliver timely and relevant information through the BlackBerry® Push Service. In a corporate environment, you can send push messages through the BlackBerry® Enterprise Server.

  • An application that reports sports information can push scores and news from games as they become available.
  • A weather application can update weather information when it is published, so that the application always has the most current information.
  • The manager of an airport baggage system could receive updates about flight arrivals and departures through the airport's BlackBerry Enterprise Server.

Fetch additional information for a user from web sites and social networking services using the Communication API (BlackBerry® 6 and later), or the Network API (BlackBerry® Device Software 5.0 and later).

  • A weather application that receives the basic details of the forecast through a push message could download satellite images before the user views the forecast.
  • A social networking application could synchronize contact lists betweeen a BlackBerry device and the web service.

Send application data between BlackBerry devices using the BlackBerry® Messenger Social Platform SDK.

  • A personal health management application can collect and send information about the medications a patient takes.
  • A media player application can report the current song, image, or video that a user is enjoying.

Capture and share pictures, audio, and video.

  • An event management application can capture images and other media from an event, and automatically share that them through the BlackBerry® Messenger Social Platform, or another social network.

Enable people to discover information about their environment by scanning one-dimensional and two-dimensional bar codes.

  • An application could facilitate city-wide scavenger hunts where users had to find and scan QR codes to receive clues about where to go next.

The details

The following examples demonstrate some of the features of the BlackBerry® Application Platform that enable social features. By the end of the chapter, the Bookshelf app will communicate with the Bookshelf web service to send a notification of a book released to the community of application users, and retrieve information from the web service about books that have been released.

Releasing a book

To release a book for other users, Bookshelf communicates a book's identity and location to the Bookshelf web service. However, if the book is hidden in a public place, a person might not find it using the location information alone. Bookshelf should also allow the user who releases the book to add more information about the location of the book in the form of text, images, audio, or video.

To identify a specific copy of a book, a user generates a QR code for the book from the web service's web interface. The user could then print and attach the QR code to the book. Anyone who picks up the book in the future could scan the code to add the book to their list. Once the book is added to their list, the user could then retrieve the history of that copy of the book, and add their comments to the history of the book.

The following code samples demonstrate how to capture images, audio, or video, and open a network connection to send this information to the Bookshelf web service. For more information about retrieving the location of the BlackBerry® device, see the Highly contextualized chapter.

Capturing media

You can enable a user to capture audio, video, and images using the javax.microedition.media.Player class.

Capture audio

The following code sample demonstrates how to create a Thread to instantiate a Player object and specify audio recording parameters. You can invoke this thread from your user interface to start and stop the recording.

private class AudioRecorderThread extends Thread implements javax.microedition.media.PlayerListener
{
    private Player _player;
    private RecordControl _recordControl;

    AudioRecorderThread()
    {
    }

    public void run() 
    {
        try 
        {
            _player = javax.microedition.media.Manager.createPlayer
                                              ("capture://audio?encoding=audio/amr");

            _player.addPlayerListener(this);

            _player.realize();
            _recordControl = (RecordControl) _player.getControl( "RecordControl" );
            _recordControl.setRecordLocation
                                  ("file:///store/home/user/AudioRecordingTest.amr");
            _recordControl.startRecord(); 
            _player.start();
    
        }
        catch( IOException e ) 
        {
            Dialog.alert(e.toString());
        }
        catch( MediaException e ) 
        {
            Dialog.alert(e.toString());
        }
    }

    public void stop() 
    {
        if (_player != null) 
        {
            _player.close();
            _player = null;
        }

        if (_recordControl != null) 
        {
            _recordControl.stopRecord();
            try 
            {
                _recordControl.commit();
            } 
            catch (Exception e) 
            {
                Dialog.alert(e.toString());
            }
            _recordControl = null;
        } 

    public void playerUpdate(Player player, String event, Object eventData) 
    {
        Dialog.alert("Player " + player.hashCode() + " got event " 
                                                         + event + ": " + eventData);
    }
}

Find out more

For more information about recording audio, visit the following resources:

Capture video

The following code sample demonstrates how to create a Thread to instantiate a Player object and specify video recording parameters. You can invoke this thread from your user interface to start and stop the recording.

private class VideoRecorderThread extends Thread implements javax.microedition.media.PlayerListener
{
    private Player _player;
    private RecordControl _recordControl;

    VideoRecorderThread()
    {
    }

    public void run() 
    {
        try 
        {
            _player = javax.microedition.media.Manager.createPlayer
                                            ("capture://video?encoding=video/3gpp");

            _player.addPlayerListener(this);

            _player.realize();
            VideoControl videoControl = (VideoControl) _player.getControl
                                                                 ("VideoControl");
            _recordControl = (RecordControl) _player.getControl( "RecordControl" ); 

            Field videoField = (Field) videoControl.initDisplayMode
                     (VideoControl.USE_GUI_PRIMITIVE, "net.rim.device.api.ui.Field");

            try
            {
                videoControl.setDisplaySize(Display.getWidth(), Display.getHeight());
            }
            catch( MediaException me )
            {
                // setDisplaySize is not supported
            }
                    
                add(videoField);

                _recordControl.setRecordLocation
                                ("file:///store/home/user/VideoRecordingTest.3gpp" );   

                _recordControl.startRecord(); 
                _player.start();
    
            }
            catch( IOException e ) 
            {
                Dialog.alert(e.toString());
            }
            catch( MediaException e ) 
            {
                Dialog.alert(e.toString());
            }
        }
        
        public void stop() 
        {
            if (_player != null) 
            {
                _player.close();
                _player = null;
            }

            if (_recordControl != null) 
            {
                _recordControl.stopRecord();
                    
                try 
                {
                    _recordControl.commit();
                } 
                catch (Exception e) 
                {
                    Dialog.alert(e.toString());
                }
                    _recordControl = null;
                } 
            }

        public void playerUpdate(Player player, String event, Object eventData) 
        {
            Dialog.alert("Player " + player.hashCode() + 
                                         " got event " + event + ": " + eventData);
        }
    }
}

Find out more

For more information about recording video, visit the following resources:

Capture images

The following code sample extends the MainScreen class to create a viewfinder to capture images. You can present this screen to a user when they are ready to capture an image, and retrieve the image from the _rawImage variable.

class ImageCaptureDemoScreen extends MainScreen
{	
    Player _p;
    VideoControl _videoControl;    
    byte[] _rawImage = null;
 
    public ImageCaptureDemoScreen()
    {
        try 
        {
            _p = javax.microedition.media.Manager.createPlayer("capture://video?encoding=jpeg&width=1024&height=768");
            _p.realize();
            _videoControl = (VideoControl) _p.getControl("VideoControl");

            if (videoControl != null)
            {
                Field videoField = (Field) _videoControl.initDisplayMode (VideoControl.USE_GUI_PRIMITIVE, "net.rim.device.api.ui.Field");
                _videoControl.setDisplayFullScreen(true);
                _videoControl.setVisible(true);
                _p.start();

                EnhancedFocusControl efc = (EnhancedFocusControl)p.getControl("net.rim.device.api.amms.control.camera.EnhancedFocusControl");
                efc.startAutoFocus();

                if(videoField != null)
                {
                    add(videoField);
                }
            } 
        }
        catch(Exception e)
        {
            Dialog.alert(e.toString());
        }
    }

    protected boolean invokeAction(int action)
    {
        boolean handled = super.invokeAction(action); 
        
        if(!handled)
        {
            if(action == ACTION_INVOKE)
            {   
                try
                {                      
                    _rawImage = _videoControl.getSnapshot(null);        
                }
                catch(Exception e);
                {
                    Dialog.alert(e.toString());
                }
            }
        }           
        return handled;                
    }

    public byte[] getImage()
    {
        if(_rawImage != null)
        {
            return _rawImage;
        }
        else
        {
            return byte[0];
        }
    }
}  
Send data to an HTTP server

After the application user has captured some media to share, you can send that data to an HTTP server by using the Communication API. The following code sample demonstrates how to send an image captured by the camera.

import net.rim.device.api.io.messaging.*;
import net.rim.device.api.io.URI;

class SubmitPicture 
{

    private static UiApplication _app = UiApplication.getUiApplication();
    private String _result;

    public SubmitPicture(byte[] picture)
    {
            Thread t = new Thread(new Runnable() 
            {
                public void run()
                {
                    Message response = null;
                    String uriStr = "http://bookshelfwebservice/releaseBook?addPic";
                    BlockingSenderDestination bsd = null;
                    try
                    {
                        bsd = (BlockingSenderDestination)
                                   DestinationFactory.getSenderDestination
                                       ("CommAPISample", URI.create(uriStr));
                        if(bsd == null)
                        {
                            bsd =
                              DestinationFactory.createBlockingSenderDestination
                                  (new Context("CommAPISample"),
                                   URI.create(uriStr)
                                   );
                        }


                        ByteMessage pictureMsg = bsd.createByteMessage();
                        pictureMsg.setBytePayload(picture)
                        ((HttpMessage) pictureMsg).setMethod(HttpMessage.POST);

                        // Send message and wait for response
                        response = bsd.sendReceive(pictureMsg);

                        if(response != null)
                        {
                            BSDResponse(response);
                        }
                    }
                    catch(Exception e)
                    {
                        // process the error
                    }
                    finally
                    {
                        if(bsd != null)
                        {
                            bsd.release();
                        }
                    }
                }

            });
            t.start();
            
        }
    }


    private void BSDResponse(Message msg)
    {
        // process return message: picture accepted or picture rejected
    }

}

Finding a book

To help a user find books that have been released by others, Bookshelf needs to communicate with the Bookshelf web service about the current location of the user's BlackBerry® device. Bookshelf can use location information to notify the user if there is a book nearby. Book sharing is one way a Bookshelf keeps users connected to each other and the application.

Acquiring the location of the device can consume a lot of battery power. There are several strategies to use battery power efficiently in this scenario. The following table discusses three of those strategies.

Strategy

Description

Schedule an application to run periodically.

The ApplicationManager.scheduleApplication() method requests that the BlackBerry device runs an application at a particular time. Each time Bookshelf runs to retrieve the current location of the device, it can request that the device run the app again at a later time. In this way, you can have your application run periodically rather than use memory and battery power on the device when the application is not required.

For more information, see the Always on chapter.

Start with a cell-tower position.

To calculate the BlackBerry device's location, the GPS receiver must scan the sky for satellites. This part of acquiring location information consumes the most battery power.

In some cases, you can find the device's approximate location from the cell tower to which the device has a wireless connection. This strategy requires significantly less battery power than using the GPS receiver.

Bookshelf can then submit the location to the Bookshelf web service, which will respond with any books located in that area. If you want to only return books within a smaller area, you can then provide a more specific list based on the particular location acquired by using GPS.

For more information, see the Highly contextualized chapter.

Use message notifications.

When a user installs Bookshelf, the application creates an ApplicationMessageFolder. When Bookshelf discovers that a book is nearby, the application can add a new message to the ApplicationMessageFolder. By default, the message appears in the user's Messages application. On devices running BlackBerry® 6 or later, the message will also appear in the Notifications tray on the Home screen. This strategy is energy efficient because a user can review the details of a book before launching Bookshelf.

Bookshelf also implements ApplicationIndicator to display a custom icon for new message notifications. Instead of displaying a closed envelope icon, the BlackBerry device displays a book icon.

For more information, see the Proactive and notification-driven chapter.

After a user has found a book, they can register their acquisition and join the community of people who have read that copy of the book. To do so, they can scan the two-dimensional bar code that was attached by the person who released the book.

Find out more

For more information about scanning bar codes, visit the following resources:

Previous topic: Embedding UI components

Was this information helpful? Send us your comments.