Obtaining information about how your application is invoked from within BlackBerry Messenger

You can use BBMPlatformContextListener.appInvoked() to capture how your app was invoked from within BlackBerry Messenger and to gather related data, such as the current user, contact, PPID, and profile box items. You can use this information to learn how the BBM features that are integrated into your app are being used. For example, you might want to change the behavior of your app so that it opens in the context in which it is typically invoked, such as when displaying an achievement list in a user's profile box. It can also help you to determine the importance of these features to your app.

The following table shows the contextual information that BBMPlatformContextListener.appInvoked(reason, param, user) can capture with each reason constant:

Reason constant

App is invoked when the current user clicks

Param

User

INVOKE_PROFILE_BOX_ITEM

A user's profile box item for the application

The UserProfileBoxItem that was clicked

The user whose profile box item was clicked (might be the current user)

INVOKE_PROFILE_BOX

A user's profile box header for the application

null

The user whose profile box was clicked (might be the current user)

INVOKE_PERSONAL_MESSAGE

The app's personal message link in a contact's profile

The personal message string (excluding the link to the app)

The contact whose personal message link was clicked

INVOKE_CHAT_MESSAGE

The link to the app in a contact's chat message

null

The contact whose chat message link was clicked

Let's take a look at a few scenarios

public appInvoked(final int reason, final Object param, final Presence user)
{
    /* Scenario 1: The current user clicks a contact’s profile box header 
     * for the app. */

        if(reason == BBMPlatformContext.INVOKE_PROFILE_BOX)
        {
            int ppid = getPPID(user);

            /* Add code to capture all the items in the current user's profile box
             * for the app, for example, activities and achievements) /*
        }

    /* Scenario 2: The current user clicks a contact’s profile box item for the app.
     * The app can capture whose profile box was clicked, and the associated profile
     * box item. */

        if(reason == BBMPlatformContext.INVOKE_PROFILE_BOX_ITEM)
        {
            Int ppid = getPPID(user);
            UserProfileBoxItem item = (UserProfileBoxItem) param;

            // display the profile box item, for example, a game score

            int score = Integer.parseInt(item.getCookie());
        }

    /* Scenario 3: The current user clicks a contact’s personal message link
     * in a contact's profile. The app can capture whose personal message 
     * was clicked and the personal message (minus the app link).*/

        if(reason == BBMPlatformContext.INVOKE_PERSONAL_MESSAGE)

        {
            int ppid = getPPID(user);
            String personalMessage = (String) param;
        }

    /* Scenario 4: The current user clicks a contact’s chat message link
     * in a contact's chat message. The app can capture whose chat message 
     * link was clicked.*/

        if(reason == BBMPlatformContext.INVOKE_CHAT_MESSAGE)
        {
            int ppid = getPPID(user);

            //  Add code to start an activity with the contact
        }
}

// A generic function to obtain a user's unique ID

public static int getPPID (Presence user)
{
    if (user instanceof UserProfile)
    {   // returns the current user's PPID
        return ((UserProfile) user).getPPID();
    }
    else if(user instanceof BBMPlatformContact)
    {   // returns the contact's PPID
    return ((BBMPlatformContact) user).getPPID();
    }
}
Next topic: Troubleshooting

Was this information helpful? Send us your comments.