BlackBerry Hub integration
You can use the Unified Data Source (UDS) Library to add data from your app directly to the BlackBerry Hub. When you integrate data from your app with the BlackBerry Hub, you can make it easier for users to interact with your app and view notifications.
For example, if your app provides regular notifications of certain events (for example, updates to content that your app provides, or reminders to renew subscriptions to your app's content), you can register with the BlackBerry Hub to include these notifications in a dedicated account view for your app data. Or, if your app lets users send messages or start conversations with other users, you can integrate your chat and conversation interface with the BlackBerry Hub and let users view and create messages there, instead of opening your app explicitly.
When your app adds data to the BlackBerry Hub, this data is available to users even when your app isn't running. The only exception is if the schema of the BlackBerry Hub changes (for example, after updating the OS on the device), in which case you might need to add your data to the BlackBerry Hub again to make it available to users.
To use the UDS library in your app, you must have the _sys_manage_pimdomain_external_accounts and _sys_access_pim_unified permissions. You specify these permissions in the bar-descriptor.xml file for your app.
To use the permissions for BlackBerry Hub integration, send an email to email@example.com. Include an explanation of your use case for BlackBerry Hub integration and your signing account email address so the correct account is updated with permissions upon approval.
Elements of the UDS library
The UDS library consists of several elements that you can interact with and use to organize your data in the BlackBerry Hub.
An account represents a group of related items that can be displayed together in the BlackBerry Hub. If you open the BlackBerry Hub on a device, notice that there are already some accounts that are predefined, such as "Notifications", "BBM", and "Text Messages". You can add your own accounts to this list. When you add an account, it appears in the Hub Management settings screen where users can choose to show or hide items in specific accounts.
The uds_account_status_t structure represents the different account statuses that can be registered with the BlackBerry Hub. Account status is used to categorize an account as a work account (UDS_ACOUNT_ENTERPRISE), personal account (UDS_ACCOUNT_PERSONAL), or hybrid account (UDS_ACCOUNT_HYBRID).
The uds_account_data_t structure represents account-related data. This structure includes all of the information that's required to register and display an account in the BlackBerry Hub, such as name, description, icon, and so on.
The uds_account_type_t structure represents the different account types that can be registered with the BlackBerry Hub. The types of accounts are:
- SMS/MMS text messaging
- instant messaging (IM)
- another type of account that's not listed in the structure
The account type is used to group and order the accounts on the account tab in the BlackBerry Hub, but does not guarantee a specific placement order.
Inbox list items
An inbox list item is an individual item that appears in an account in the BlackBerry Hub. For example, if you're viewing an account that's associated with an email account, each message that appears in that view is an inbox list item. You can add data from your app as inbox list items, and you can associate these items with accounts in the BlackBerry Hub so that they're displayed on that account's tab.
The uds_inbox_item_data_t structure represents data that's related to inbox list items. This structure includes all of the information needed to add and display an inbox list item in the BlackBerry Hub, such as source ID, category ID, name, and so on.
BlackBerry 10 devices include two perimeters, enterprise and personal. The perimeters separate sensitive work information from personal information. Each inbox list item in the BlackBerry Hub can be associated with one of these perimeters. In the uds_perimeter_type_t structure, UDS_PERIMETER_ENTERPRISE indicates the inbox list item that belongs in the enterprise perimeter. This value is used only for hybrid accounts because items with this value can belong to both perimeters. UDS_PERIMETER_PERSONAL indicates the inbox list item that belongs in the personal perimeter.
Categories provide a way to group items in an account. You can use categories to sort and filter inbox list items in the account. For example, a messaging account might contain folders for different types of messages, and each folder is considered a category.
The uds_category_data_t structure represents category-related data. This structure includes all of the information that's required to correctly place a category in a particular account, such as account ID, parent ID, type, and so on.
An account action is an action that users can select when they view a particular account in the BlackBerry Hub. Account actions can appear in the action bar at the bottom of the screen, in the overflow menu, or in both locations.
You can associate an account action with one of the invocation actions that are available as part of the invocation framework. When a user selects the account action in the BlackBerry Hub, the appropriate target app is invoked to perform the action. For example, you might specify the "bb.action.CREATE" invocation action for an account action. To learn more about actions, targets, and other invocation framework principles, see App integration.
The uds_account_action_data_t structure represents data that's related to account actions. This structure includes all of the information that's required for an account action, such as the target, type, MIME type, and so on.
Inbox item actions
An inbox item action is similar to an account action, but it applies to the inbox list items that appear in an account in the BlackBerry Hub. Inbox item actions appear in the context menu when a user presses and holds an inbox list item.
Again, similar to account actions, you can associate an inbox item action with one of the invocation actions that are available as part of the invocation framework. To learn more about invocation framework principles, see App integration.
Inbox item actions typically appear in the context menu for inbox list items in a particular account. You can specify context-sensitive inbox actions, which appear only for certain inbox list items, depending on the state of the item.
The uds_item_action_data_t structure represents data that's related to inbox item actions. This structure includes all of the information that's required for an inbox item action, such as the target, type, MIME type, and so on.
Connection modes for the UDS library
You can use the UDS library in one of two modes: synchronous or asynchronous. For code samples that illustrate how to use the library functions, see Using the Unified Data Source APIs.
In synchronous mode, calls to UDS library functions (such as uds_account_added() , uds_item_updated() , and so on) block until a response is received from the BlackBerry Hub server, or until an error occurs.
In asynchronous mode, calls to UDS library functions return immediately after sending the associated command to the BlackBerry Hub server. Your app calls uds_wait_for_response() on a separate thread to block until your app receives a response. Then, when a response is available, your app can call uds_get_response() to retrieve and parse the response. You might choose to use asynchronous mode instead of synchronous mode if you want your app to be able to continue doing its own operations (such as processing information) while it's waiting for responses from the BlackBerry Hub server.
The sequence of operations for asynchronous mode is the same as for synchronous mode except that a few extra function calls are required to wait for and retrieve responses.
Last modified: 2015-07-24