Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Social and connected

The most frequently-used apps often help people share their experiences, data, and media with others. For example, an app 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 app 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.

When creating the social aspect of your app, ask yourself: How do I want users to interact with each other? One to one, like email? Or many to many, like a forum? Or one to many, like a Personal Message on a BlackBerry Messenger profile?

What are the benefits of a social and connected app?

  • 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 creating a social user experience

Approach

Examples

Deliver timely and relevant information through the Push Service.

You can use the Push Service to send information to a BlackBerry device without that device explicitly requesting it. You can use the Push Service to anticipate your user's needs, and provide them with information contextually, or to keep them continually updated of changing situations.

In a corporate environment, you can send push messages through the BlackBerry Enterprise Server.

Fetch additional information for a user from web sites and social networking services.

You can simplify the process of interacting with web services and other apps using the Communication API. In addition, the Network API provides simplified access to a wireless network. You can add context, and make your app more social by using these APIs.

Send application data between BlackBerry devices using the BlackBerry Messenger SDK.

You can use the BlackBerry Messenger SDK to send and receive messages, images, songs or videos from a user's BlackBerry Messenger contacts. Your app can also act as a host, allowing users to meet and add each other to BlackBerry Messenger.

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

You can use the Barcode Scanning API, and the ZXing library. to allow users to scan QR codes for information. You can encode small amounts of text, such as a website address into a QR code using the ZXing library.

Tutorial: Making an app social

Making an app social and connected makes it more integrated with a user's daily life and activities.

For example, say you're creating an app called Bookshelf that has the following social aspects:

  • Talking about a book: When a user reads a new book, they can share their opinions with other users via groups.
  • Finding a book: The app should hint to the user if there's a book nearby. If the user finds it, they can scan the QR barcode and update the book's status.
  • Releasing a book: When a user is done with their book, they have the option to print a QR barcode, attach it to the book, and leave it somewhere public for another to find. They have the option to take and upload photos or video of the place they left their book. Information associated with the book is then sent to a server, where other Bookshelf users can see that it's been released.

Releasing a book

One of the key aspects of the Bookshelf app is the releasing of books for another user to find. When a user releases a book, the Bookshelf app communicates with the Bookshelf web service to transmit information about the book's location and identity, and to get a printable QR code for that book. To release a book for other users, a user takes the following actions:

  • To idenitfy a specific copy of a book, a user generates a printable QR code from the Bookshelf's web interface. The user can then attach the QR code to the book, allowing a future user to find it and scan the QR code, add a book to their list, and retrieve its history.
  • 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.

Capturing media

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

Here's how to 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);
    }
}

For more information about recording audio, see Working with audio.

Here's how to 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);
        }
    }
}

For more information about recording video, see Working with video.

Here's how to 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];
        }
    }
}  

Here's how to send data to an HTTP server. In this example, this process releases the book so it can be shared by others.

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
    }

}

Finally, here's how a user finds a book.

When a book is released, the user who releases it sends information about the book's location to the Bookshelf web service. To help another user find a book, the Bookshelf app needs to communicate with the Bookshelf web service about the user's BlackBerry device. You can use this to notify the user if there is a book nearby. Once found, a user can update the book's status in the Bookshelf app. To find a book, Bookshelf can take the following actions:

  • Acquire a device's location, and access a web service to see if there are any books in the area.
  • Once a book is found, a user can scan the QR code attached to the book, and update the book's status in the Bookshelf web service.

Acquiring a device's location can be draining on the device's resources. There are three ways we can enable Bookshelf to scan for books without draining battery life. First, we can schedule an app to run periodically, as covered in the Always on page. Secondly, we can find a device's location from a cell tower, as covered in the Highly contextualized page. Finally, we can use message notifications to alert the user when a book is found, as covered in the Proactive and notification-driven page.