Integrating with the BBM Social Platform, One Step at a Time

1. Integrating with the BBM Social Platform, One Step at a Time Brian Zubert Team Lead, Developer Relations bzubert@rim.com July 19, 2011

2. BlackBerry Messenger CommunityExperiencing explosive growth • 45+ million global BBM subscribers • >70% of BBM users use it daily • >2 million new users per month • >2 thousand new users per hour • >100 billion BBM messages sent per month! • BBM community is there when it counts • 300% lift in traffic after winning goal at World Cup finals

3. BBM Social PlatformWhat is it? • Gives apps access to the enormous user base of BBM • 3 Major API Areas: • Access BBM contact list • Access and update user profiles • Including app-specific area, where anything goes • Enable in-app chat • (and a 4th): • Share files such as pictures, voice notes, videos and music.

4. BBM Social PlatformSupported Platforms • Backwards compatible: Supports OS 5.0 and above • Support for BlackBerry Java Applications • Support for BlackBerry WebWorks Applications http://us.blackberry.com/developers/choosingtargetos.jsp

5. BBM Social PlatformWhere do I get it? • Releases • Java release is gold! • WebWorks release is in beta! • Get updates: • BlackBerry Developer’s Blog - http://devblog.blackberry.com/ • @BlackBerryDev on Twitter • BBM Dev Page - http://www.blackberry.com/developers/bbm/

6. BBM Registration

7. BBM Registration Registration is the first step! Requires user’s permission Requires a new class that extends BBMPlatformApplication (does not replace UIApplication) 7

8. BBM Registration - Java Create your BBMPlatformApplication class public class MyBBMAppPlugin extends BBMPlatformApplication { public MyBBMAppPlugin() { //UUID is a unique identifier used for the test environment super( "Insert your UUID here" ); } } 8

9. BBM Registration - Java Create your BBMPlatformContextListener class public class MyBBMPlatformContextListener extends BBMPlatformContextListener { public void accessChanged(boolean isAccessAllowed, int accessErrorCode) { if (!isAccessAllowed) { // You cannot access the BBM platform, handle this situation here, disable features, etc. } } public void appInvoked(int reason, Object param) { // Code for handling different contexts for invocation such as user invite, profile click, etc. } } 9

10. BBM Registration - Java Register your app MyBBMAppPlugin myPlugin = new MyBBMAppPlugin(); UiApplication.getUiApplication().invokeLater(new Runnable() { public void run() { //The platformContext variable will need to be saved and used //throughout your application. It should be an instance or static variable. BBMPlatformContext platformContext = BBMPlatformManager.register(myPlugin); MyBBMPlatformContextListener platformContextListener; platformContextListener = new MyBBMPlatformContextListener(); platformContext.setListener(platformContextListener); } } ); 10

11. BBM Registration - WebWorks document.onload = function() { //onAccessChanged *must* be defined *before* a call is made to register. // Invoked when application access status changes (such as a successfully registered app): blackberry.bbm.platform.onAccessChanged = function(accessible, status) { if (status === "allowed") { //Access is allowed: complete any steps that make use of the BBM APIs which // would normally occur during a pageLoad event which: blackberry.bbm.platform.io.onConnectionCreated = function(event, connectionType, connection, param) { // ... }; } }; //The onAccessChanged method will be called after a registration request. // If successfully registered, the status will be "allowed“. blackberry.bbm.platform.register( { uuid: “0cee5bbb-cee9-3bd4-8e3a-4d3247301e38" } ); //Don't make any further calls to BBM APIs in the onload event after a call to register. // The BBM SDK will call the onAccessChanged method if this app is successfully registered. } 11

12. BBM Registration If the user clicks Decide Later You can not ask the user again The user must grant permissions via the BBM Options screen 12

13. Working with ContactsViral Distribution

14. Viral Distribution • What is Viral Distribution • Use of a social network to increase brand awareness or other marketing objectives • The natural spread of a product, service or marketing material through peer to peer interaction • Key Components: • A compelling product • Empowered users • A strong medium • Leverage the already familiar BBM chat interface for app recommendations to friends

15. The BBM Advantage • Millions of users • 45+ million users • Tightly connected with friends, family and coworkers • Instant communication • Push-based communication system • Delivery and Read notices • Carrier agnostic • Free to use • Free to implement

16. Invite to Download • What • Allow users to invite their friends to download your app • Why • Leverage the social graph exposed by BBM to grow your user base • How • Very simple! • Just one method call to initiate the whole process!

17. Invite to Download • A single API call that performs the following: • Contact Picker is displayed • User selects a contact • User confirms contact • The invitee receives a message on BBM inviting them to download the app.

18. Invite to Download What the inviter sees What the invitee sees

19. Invite to Download (Java) MessagingService messagingService = platformContext.getMessagingService(); messagingService.sendDownloadInvitation(); Reminder: the object ‘platformContext’ was provided upon registering with the service.

20. Invite to Download (WebWorks) var result = blackberry.bbm.platform.io.inviteToDownload(onComplete);

21. Working with ContactsSharing with BBM Contacts

22. Sharing with BBM Contacts • What • Sending a message or file to BBM contacts • Why • Share the application experience with BBM contacts who do not have the app. • Get them interested in the content, and maybe they will download the app! • How • Simple API calls for each messages and files.

23. Sharing with BBM Contacts • Sending a message • User can select a contact to message • App can pre-populate text • User must confirm / complete the sending of the pre-populated text • Prevents spamming of users friends • App is hyperlinked in the conversation for identification and easy access Java platformContext.getUIService().startBBMChat("Hello!"); WebWorks blackberry.bbm.platform.users.startBBMChat(onComplete, "Hello");

24. Sharing with BBM Contacts • Sending a file • App or user can select a contact • App or user can select a file • User must confirm file transfer Java platformContext.getMessagingService().sendFile( contact, filePath, “See my file sent from BBM SDK Demo!"); WebWorks blackberry.bbm.platform.io.sendFile(filePath, “See my file sent from BBM SDK Demo!”, onFailure, contact);

25. Working with Contacts Listening for Contact List Changes

26. Listening for Contact List Changes • What • Receive notification when a user’s contacts change status, picture, name, etc. • Why • Integrating these values into your app will allow it to truly behave as if it’s part of the BBM network. • How • Implement the PresenceListener (Java) • or onUpdate listener (WebWorks)

27. Listening for Contact List Changes • The listener notifies on updates to: • Display name • Display picture • Personal messages • Status • App installation/uninstallation (Your app only) • Receipt of application invite

28. Listening for Contact List Changes

29. Listening for Contact List Changes Java public class MyBBMContactListScreen implements PresenceListener { public MyBBMContactListScreen(BBMPlatformContext platformContext) { platformContext.getContactListService().setPresenceListener(this); }} • Implement the PresenceListener interface and set it as a listener for the service: WebWorks blackberry.bbm.platform.users.onUpdate = onUpdate; • Set the onUpdate event listener to your own onUpdate method

30. Listening for Contact List ChangesJava • Implement PresenceListener.presenceUpdated public void presenceUpdated(BBMPlatformContact contact, int eventType) { final String str = "[" + getEventName(eventType) + "] was changed by " + contact.getDisplayName(); Dialog.inform(str); } private String getEventName(int eventType) { switch(eventType) { case PresenceListener.EVENT_TYPE_DISPLAY_PICTURE: return "Display picture"; break; case PresenceListener.EVENT_TYPE_DISPLAY_NAME: return "Display name"; break; default: return “Other event"; } }

31. Listening for Contact List ChangesWebWorks • Implement onUpdate function onUpdate(user, event) { switch (event) { case "displaypicture": var src = user.displayPicture; break; case "displayname": var name = user.displayname; break; case "personalmessage": var msg = user.personalmessage; break; case "status": var status = user.status; var statusMessage = user.statusMessage; break; } } blackberry.bbm.platform.users.onUpdate = onUpdate;

32. Working with ContactsInviting Users to BBM via PIN

33. Inviting Users to BBM via PIN • What • Add to your users’ social graph when PINs are available. • Why • Allows your users to add friends via PIN if that information is available • How • Call the appropriate method and pass it the list of PINs to invite.

34. Inviting Users to BBM via PIN • Users can have address book contacts that have PIN information • Your app may already be using PINs • Create a community around your application • Allows anonymous users to interact and, if a friendship is formed, add them to each others contact list. • Users are more likely to return to your app to interact with their new friends • Users will remind others of your app via invitations

35. Invite Session Participants to BBM Java BBMInvitationRequest requests[] = new BBMInvitationRequest[1]; Requests[0] = new BBMInvitationRequest(“2100000A”, “Nicole”); UIService.inviteToBBM(requests) WebWorks var users = blackberry.bbm.platform.users; var invitations = [ new users.ContactInvitation("2100000A", “Nicole"), ]; blackberry.bbm.platform.users.inviteToBBM(onComplete, invitations);

36. The User Profile and Profile BoxIn-App User Information

37. In-App User Information Add profile information to your app Instant personalization Customize your application with profile information Complements the Presence Listener Add in-app awareness of user status The user is busy? Maybe reduce notifications, sounds, etc. Apply busy status to own in-app network 37

38. In-App User Information Instant access to: Display Name Display Picture Personal Message Status (Available/Busy) Status Message 38

39. In-App User Information UserProfile userProfile = platformContext.getUserProfile(); String displayName = userProfile.getDisplayName(); Bitmap displayPicture = userProfile.getDisplayPicture(); String personalMsg = userProfile.getPersonalMessage(); int status = userProfile.getStatus(); String statusMsg = userProfile.getStatusMessage(); Java 39

40. In-App User Information var userProfile = blackberry.bbm.platform.self; var displayName = userProfile.displayName; var displayPicture = userProfile.displayPicture; var personalMsg = userProfile.personalMessage; var status = userProfile.status; var statusMsg = userProfile.statusMessage; WebWorks 40

41. The User Profile and Profile BoxUpdate Your Users’ Status

42. Update Your Users’ Status Elements of the User Status field Personal Message Available/Busy Status Custom Status Message Display Picture 42

43. Update Your Users’ Status What Set your users status on their behalf with their permission Why Raise awareness of your users activities in your application How Simple! Basic getter/setter design pattern 43

44. Update Your Users’ Status • Update the user status with: Java UserProfileuserProfile = platformContext.getUserProfile(); userProfile.setStatus(Presence.STATUS_BUSY, “Gone Fishing!”); WebWorks function onComplete(result) { //result = true/false if user allowed the change } blackberry.bbm.platform.self.setStatus("busy", “Gone Fishing!", onComplete); 44

45. Update Your Users’ Personal Message • Update the user personal message with: Java UserProfileuserProfile = platformContext.getUserProfile(); userProfile.setPersonalMessage(“Feeling Good!”); WebWorks function onComplete(result) { //result = true/false if user allowed the change } blackberry.bbm.platform.self.setStatus("Feeling Good!", onComplete); 45

46. Update Your Users’ Display Picture • Update the user display Picture with: Java UserProfileuserProfile = platformContext.getUserProfile(); userProfile.setDisplayPicture(Bitmap OR EncodedImage); WebWorks function onComplete(result) { //result = true/false if user allowed the change } blackberry.bbm.platform.self.setDisplayPicture(“URI", onComplete); 46

47. The User Profile and Profile BoxCustom Profile Boxes

48. Custom Profile Boxes Apps can add profile boxes to the user profiles Consists of an icon and text Benefits Increase user engagement Spreads awareness of your app amongst contacts Can be fun or informative for users and their peers Links back to your application 48

49. Custom Profile Boxes Features A field that appears on a users profile screen. Visible to all BBM 6.0 users Can contain an icon and text Clicking the box launches your app If the app isn’t installed, takes the user to the app page in BlackBerry App World Maximum of 3 activities per app 49

50. Custom Profile Boxes Java UserProfile userProfile = platformContext.getUserProfile(); UserProfileBox profileBox = userProfile.getProfileBox(); if (profileBox.isAccessible()) // Ensure that we have permission to access the box { // Each icon used by your application must have a unique ID int iconId = 1; EncodedImage icon = EncodedImage.getEncodedImageResource("smiley.png"); profileBox.registerIcon(iconId, icon); profileBox.addItem(iconId, "Always Happy!");  } 50