Integrate with BBM and Watch Your Application Go Viral
How to Integrate Your Native Application with BBM
How to Integrate Your BlackBerry WebWorks Application with BBM

Now let’s take a look at how you can use the invocation framework to invoke BlackBerry Messenger and bring cards from BBM into your application. In case the term card is new to you, let me explain. Think of cards as a screen of another application that is shown within your application and acts like a screen in your own app. A card becomes part of the flow that makes up BlackBerry® 10, allowing for a seamless user experience that prevents the user from having to switch applications.

The code samples used in this blog post are in QML, but keep in mind that you can use these invocation features from C++, BlackBerry® WebWorks™ and Adobe® AIR®.

Below is a screenshot of the actions available that you could use in the menu of your application to invoke BBM. The “BBM Invocation” text you see below represents your application screen (it actually says BBM Invocation Sample). Each BBM card is going to be displayed on top of it. At any time the user can peek back to see your applications screen or close the card completely, returning to your application screen.

Let’s take a look at each of these cards individually, see how they’re invoked and what they look like once invoked.

Start a BBM Chat

InvokeActionItem {
    title: "Start BBM Chat"
    query {
        invokeActionId: "bb.action.BBMCHAT"
        uri: "pin:2100000a"
    }
}

The code above shows how to initiate a BBM chat. The chat window will flow into your application as a card. In the example above, a single PIN is used. If you omit the URI parameter, the user will be prompted to choose a contact from their BBM contact list to include in the chat session. If a chat session already exists with the contact, it will be shown with previous messages populated.

Set BBM Avatar Image

InvokeActionItem {
    title: "Set BBM Avatar Pic"
    query {
        invokeTargetId: "sys.bbm.imagehandler"
        invokeActionId: "bb.action.SET"
        uri: "file:///path/to/the/file.png"
    }
}

You can prompt the user to change their BBM avatar image to one specified by your application. This triggers a card that previews the image and allows the user to crop or zoom. Once the user is happy with their selection, they click Save to update their BBM Avatar.

Invite to BlackBerry Messenger

InvokeActionItem {
    title: "Invite to BBM"
    query {
        invokeActionId: "bb.action.INVITEBBM"
        uri: "pin:2100000A"
    }
}

If you know the BlackBerry PIN for contacts who are not yet BlackBerry Messenger users, you can invite them to BBM by using the BlackBerry.action.INVITEBBM invoke action as shown above. The user can then write a personalized message to their contact before sending the message.

Share Text over BBM

InvokeActionItem {
    title: "Share Text Over BBM"
    query {
        mimeType: "text/plain"
        invokeTargetId: "sys.bbm.sharehandler"
        invokeActionId: "bb.action.SHARE"
        data: "This is some text to share."
    }
}

Sharing text over BBM enables your application to start a chat session and populates the message entry field with the text specified in the data section. Just like starting a BBM chat session above, if a previous chat session exists, the message history will be shown.

Share Image over BBM

InvokeActionItem {
    title: "Share Image Over BBM"
    query {
        invokeTargetId: "sys.bbm.sharehandler"
        invokeActionId: "bb.action.SHARE"
        uri: "file:///path/to/image/file.png"
    }
}

Sharing an image over BBM works almost the same way as sharing text, except you specify a URI that points to an image file. It brings up a chat card with a message composed and ready to send with the image attached.

Wrapping It Up

For simplicity, the QML code samples above are using hard coded data and URI values. However, in a real application you’d want to use dynamic values based on variables within your application. You can do this using the onTriggered method. Here is an example of its use:

InvokeActionItem {
    title: "Share Text Over BBM"
    query {
        mimeType: "text/plain"
        invokeTargetId: "sys.bbm.sharehandler"
        invokeActionId: "bb.action.SHARE"
        data: "This is some text to share."
    }
    onTriggered: {
        data = "Some new text"
    }
}

When invoked, the sample above would populate the chat session with “Some new text”. In a real application you’d change the “Some new text” string to point to a variable or control in your application.

That concludes the list of BBM cards currently available for BlackBerry 10. As you can see, by using just a few lines of code you can integrate some powerful features like BBM Chat into your application. Invoke away!

First and foremost, there are two kinds of invocations – unbound and bound. An unbound invocation is performed when an app does not specify a specific target app that should get invoked, and hence relies on the invocation framework to select the best target. For example, if there are three apps that can open .DOC files, the framework chooses the best one based on its own target selection logic. So, for unbound invocations, the framework provides automatic brokering to find the best-fit targets and also performs target selection to choose the best among the best. This is very powerful because the client application does not need to know any target applications at all, and yet it can discover and invoke them via the invocation framework.

On the other hand, a bound invocation is performed when the target app is specified by the client application while sending an invocation request. For example, a client app may request that Docs to Go® should be invoked for opening a .doc file. In this case, the invocation framework does not provide any brokering (or target selection) and blindly invokes the specified target app with the request parameters. Extra care must be taken when performing a bound invocation because an app may be sending a request to a target that the target does not understand at all. One thing is clear — bound invocation assumes that the client knows the target well.

There are really two ways you can know a target. First, you might have had a conversation with the author of the target app and have an agreement on the invocation request parameters. In return, they have made you aware of their target ID that you can use to perform a bound invocation. Second, you can query the invocation framework with an invocation request to get a list of best-fit targets and programmatically parse their attributes (capabilities) including their target IDs and invoke one programmatically. Note that querying is another way to discover apps without knowing them and is even more powerful and flexible than unbound invocations. As long as you have a valid target ID, you can perform a bound invocation with the appropriate parameters.

So far so good, but how does the invocation framework know about all the target apps? It does because each target app is required to register with the framework if they wish to be considered by the framework. While registering with the framework, targets must specify a target id which alone makes them candidates for bound invocation. However if a target wants to make itself available for unbound invocations or invocation queries, it must define one or more invoke filters. Each filter is a combination of the following attributes.

• Actions (e.g. bb.action.OPEN) that describes the action it can perform
• MIME types (e.g. application/pdf) describing the content type it can perform the action on
• URIs (e.g. http://, file://) specifying the protocols it can handle to retrieve the data
• EXTs describing the file extensions it can handle if the URI scheme is file://

Note that at least one action and one MIME type is mandatory for each filter definition, and if the URI is file://, at least one EXT must be specified. Filters are what really allow the invocation framework to broker between clients and potential targets as well as target selection that lead to successful invocations.

Well, that’s a 30,000 feet overview of the invocation framework but as a developer I know your hands are itching for some real code. The good news is I have that covered — I have already uploaded a few sample applications on Github that you may find very (very) useful.

• InvokeClient – An application that demos different ways to invoke and to query for targets
• InvokeTarget1 – A dummy target app that can be used with InvokeClient
• InvokeTarget2 – A second dummy target app that can also be used with InvokeClient

Samples are great, but so are documentations (if we read them) for a solid understanding. Please refer to our App Integration development guide for a comprehensive guide with code snippets for both invoke clients and targets.

I am more excited than ever before to introduce the invocation framework as part of the BlackBerry 10 Native SDK beta 2 and have no doubt that this will help most app developers out there to provide a deeply integrated user experience. Invocation is one of the core aspects of the BlackBerry 10 experience and come launch, it is going to be hard to find an app that does not invoke or get invoked. I will keep everyone posted on new features as we add them to this framework but more importantly, I am all ears to your feedbacks at shaque[at]rim[dot]com, @BlackBerryDev and @shadidhaque.

You might have heard the terms “push” and “push notifications” thrown around before. So in a nutshell, what’s push good for? Push does pretty much what the name implies: it allows you to push information to BlackBerry® smartphones the moment it is available, and the user gets the push message almost immediately after it’s sent.

Push is an interesting technology because you need to write two applications for it to work:

1) You have to write a server-side push application (sometimes called a Push Initiator) so that you can send out push messages to BlackBerry smartphones.
2) You also have to write a client-side push application (sometimes called a push-enabled application) so that users can receive those push messages on a BlackBerry smartphone.

I highly recommend that you look at the Push Service SDK to write your Push Initiator. You can download and find information on that SDK here: https://developer.blackberry.com/services/push

The rest of this blog post concentrates on the push-enabled application, and explains how to write a good application using the BlackBerry® WebWorks™ SDK.

The Push Service APIs that are part of the BlackBerry WebWorks SDK are brand new for BlackBerry® 10. When we created the APIs, our goal was to start fresh – to make things clean and simple. We also wanted to make sure that the Push Service APIs would work well with other new APIs introduced for BlackBerry 10, like invoke events (that is, the blackberry.invoked feature).

There are only two classes that you have to worry about in the Push Service APIs:

1) PushService has the business logic that you need to start receiving push messages in your app

and

2) PushPayload is essentially a value object containing the content and headers of your push message.

Now that you want your app to start receiving pushes, where do you start? The first question to ask yourself is whether or not you’re developing this app for the general public. If you are, you should register to evaluate the Push Service at this link: https://www.blackberry.com/profile/?eventId=8121 After registering, you’ll receive an email with all the information that you need to write your push-enabled application, including your application ID, password, and the PPG URL you will be pushing messages to. If you’re developing your app for enterprise users, you don’t have to worry about registering.

Alright, what’s next?

At some point, you should check out the Push Capture sample app available here: https://github.com/blackberry/BB10-WebWorks-Samples/tree/master/pushCapture. The sample is a fully functional app that uses the Push Service APIs.

The UI for the sample app looks like this:

There are also a lot of good examples and information in the API Reference about the PushService and PushPayload classes. For information about the PushService class, see https://developer.blackberry.com/html5/apis/blackberry.push.PushService.html For information about the PushPayload class, see https://developer.blackberry.com/html5/apis/blackberry.push.PushPayload.html

In order to use the Push Service APIs, you need to update your application’s config.xml:

1) You need to reference the blackberry.push feature:

<feature id=”blackberry.push” />

2) You need to add a feature tag for blackberry.invoked:

<feature id=“blackberry.invoked” />

This feature tag relates to the handling of invoke events. A push notification comes into your application as an invoke event.

3) Finally, you need to have an entry relating to the invoke events that you receive for push messages:

Take note of the id attribute (also known as the “invoke target id”). This attribute has to match the options.invokeTargetID that is passed in to the call to the static create function of the PushService class (more about the create function in a moment). Another important detail is that the action tag is set to “bb.action.PUSH”. This setting makes it clear that the invoke relates specifically to push messages.

Now, here’s a quick rundown of the Push Service APIs. Don’t worry, there aren’t many.

1) Call the static create function on the PushService class to get a PushService object you can start using. If the create call fails, you won’t have access to a PushService object. That’s why the create function has success and fail callbacks. You’ll need a lot of the info from the email you received when you registered to evaluate the Push Service (for public apps), so have that info handy for this call.

2) If your application is not running, one of the major advantages of push is to allow your application to be launched when a new push comes in, and to have your app continue to run in the background. This allows valuable device resources to be saved because your app doesn’t have to be running all the time to be able to receive push messages.

The default behavior for your application is to not have it launch when a new push comes in. That’s where the launchApplicationOnPush function comes in (from the PushService class). If you call it with a value of true, then it will activate the launch functionality. You can turn this functionality off at any time by calling launchApplicationOnPush again with a value of false.

3) Call the createChannel function on your PushService object to allow pushes to start coming to your app.

When that’s done, how does the server-side Push Initiator know who to push to? There’s something we call a “token” that you get back when you do a createChannel. You need to pass the toke along to the Push Initiator so it knows who to address a push to. If you’re using the Push Service SDK I recommended above, then you just simply pass this token to the Push Initiator using an HTTP request (we call it a subscribe operation).

4) Ok, you’re now ready to receive pushes (you created the channel) and you’re ready to send pushes (the Push Initiator has the token). Fire off a push to the token using your Push Initiator.

5) In BlackBerry 10, the push comes to the app as an invoke event using the new blackberry.invoked feature in BlackBerry WebWorks. We register for the event with the following call:

Now that we have the invoke request in our invokedCallbackFunc callback, how do we get the push out of it? Simply call the PushService object’s extractPushPayload function passing in the invoke request and it will give you back a PushPayload object.

(Quick side note: You’ll probably want to make sure the invoke event you received was for a push. The invoke event can be for other various reasons too. It’s easy to check though. Just make sure

before you call extractPushPayload).

Here’s a link to the blackberry.invoked API Reference if you want to check it out: https://developer.blackberry.com/html5/apis/blackberry.invoked.html

6) And there you go. You have the PushPayload object, and you can do whatever you want with the data.

You might have noticed that the “data” property of the PushPayload object is of type Blob. Look at the extractPushPayload function in the API Reference for PushService (see the link I gave above). It shows examples of how to convert that Blob into something that you can actually display to users.

7) From this point onwards, you app will continue to receive push messages. If at any time you want your app to stop receiving push messages, simply call the destroyChannel function on your PushService object.

Sure, using push requires some extra effort. You do need to write two applications, but the benefits to your users are huge. Just imagine displaying notifications in your app the moment an event of interest happens in the real world. That’s a pretty powerful thing.

And that’s why the BlackBerry WebWorks SDK for the client-side application (and Push Service SDK for the server-side application) is there to help make your life easier and to use push to its full potential.

Beta 2 of the BlackBerry® 10 SDK for Adobe® AIR® now has support for participating in the BlackBerry 10 Invoke Framework. You can find all of the APIs in the QNXDevice.ane and they are all documented.

Invoking a Application

By leveraging the Invoke API, you can invoke virtually any other application on the BlackBerry® smartphone through some simple API call, where you’ll set a parameter for the app you want to invoke and then pass in any parameters that application is expecting. A typical example would be that your application can invoke the BlackBerry® Maps application when it comes across an address. InvokeManager.invoke() will invoke an application.

When the application has been successfully invoked, an InvokeEvent.INVOKE_TARGET event will be dispatched. If there was an error invoking the target, an ErrorEvent.ERROR event will be dispatched. Please refer to the following Knowledge Base article for details on some known issues which will be addressed in an upcoming patch.

Invoking a Viewer

InvokeManager.invokeViewer() will invoke a viewer. A Viewer class is returned and is used to communicate with the viewer.

Let’s say you have an image viewer application and you want to invoke it from the main application you’re working on. In the main application, you want to pass the image file that the imager viewer app will open when invoked.

Below is a sample of how you can invoke a viewer and wait for it to be created. This example assumes that you have created the viewerRequest object with the correct data for your viewer.

var viewer:Viewer = InvokeManager.invokeManager.invokeViewer( viewerRequest );
viewer.addEventListener( ViewerEvent.VIEWER_CREATED, viewerCreated );

private function viewerCreated( event:ViewerEvent ):void
{
   //viewer is created and ready to communicate with.
}

Making your Application an Invoke Handler

If you are developing an application that can be invoked by another application, you will want to add a listener for the invoke event at the very start of your application. These should be the first lines of your application.
Once you have received the invoke event, you can check the startup mode and get the data that you were invoked with.
Below is a sample of how you would accomplish this:

InvokeManager.invokeManager.addEventListener(InvokeEvent.INVOKE, onInvoked );
private function onInvoked( event:InvokeEvent ):void
{
    if( InvokeManager.invokeManager.startupMode == InvokeStartupMode.INVOKE )
    {
        var invokeRequest:InvokeRequest = InvokeManager.invokeManager.startupRequest;
    }
    else if( InvokeManager.invokeManager.startupMode == InvokeStartupMode.VIEWER )
    {
        var viewerRequest:InvokeViewerRequest = InvokeManager.invokeManager.startupViewerRequest;
    }
}

Query a list of targets

You can also query a list of targets or viewers on the device by calling the InvokeManager.queryTargets() method. At some point in the future, this will make a pop-up list in your application that will allow users to select items from the list. For now, it returns the results and it is up to you to use those values in your invoke() and invokeViewer() calls.

InvokeEvent

No matter how your application is started, you will receive an InvokeEvent dispatched by the InvokeManager. In order to determine how your app was started, you can check the InvokeManager.startupMode in your InvokeEvent handler. So, your application would look something like the following, assuming that your application can be launched as a target and a viewer:

package
{
    import qnx.events.InvokeEvent;
    import qnx.invoke.*;

    public class Main extends Sprite
    {

        public function Main()
        {
            //NOTE: THIS MUST BE THE FIRST THING SET IN YOUR APPLICATION CONSTRUCTOR
            InvokeManager.invokeManager.addEventListener(InvokeEvent.INVOKE, onInvoke );
        }

        private function onInvoke( event:InvokeEvent ):void
        {
            if( InvokeManager.invokeManager.startupMode == InvokeStartupMode.INVOKE )
            {
                //invoked as an application/target.
                var data:InvokeRequest = InvokeManager.invokeManager.startupRequest;
            }
            else if( InvokeManager.invokeManager.startupMode == InvokeStartupMode.VIEWER )
            {
                //invoked as a viewer
                var data:InvokeViewerRequest = InvokeManager.invokeManager.startupViewerRequest;
            }
            else
            {
                //launched by the pressing on the icon on the home screen.
            }
        }
    }
}

Closing a Viewer

There are two different ways a viewer can be closed:

1. From the application
2. From the viewer

When an application wishes to close a viewer that it has created, it can simply call the Viewer.dispose() method. This will cause the viewer to be removed immediately.

A viewer can request to be closed by the application and should never actually attempt to close itself directly. Viewers can call the InvokeManager.requestViewerClose() method. This will send a message to the application requesting that it be closed. The Viewer instance in the application will dispatch a ViewerEvent.VIEWER_CLOSE_REQUEST event. When application receives this event, it should call the dispose() method on the viewer to close it. The reason this doesn’t happen automatically is so that applications can transition viewers out before removing them. We may make this a bit more automated in the future, and we’ll let you know when this happens.

Viewer message relay

Viewers can send data to applications using the InvokeManager.viewerSendMessage() method. The Viewer instance will then dispatch ViewerEvent.VIEWER_MESSAGE events with the message and data properties set to what was passed into the viewerSendMessage(). Here is an example of how you would use this:

Viewer code

InvokeManager.invokeManager.viewerSendMessage( "select", {name:"Fred"});

App Code

__currentViewer = InvokeManager.invokeManager.invokeViewer(viewerRequest);
__currentViewer.addEventListener( ViewerEvent.VIEWER_MESSAGE, onMessage );

private function onMessage( e:ViewerEvent ):void
{
    trace( e.message, e.data ); //outputs "select Fred";
}