Developers can make use of the Identity Service library APIs to enhance their app in several ways: +* - Data storage and retrieval +* - User authentication and authorization to access apps and off-device services offered by the Identity Provider (without prompting for credentials) +* - Access to the user's personal information stored in the Identity Provider's account system +* +*
These capabilities are described further in the sections below, and the specific implementation will vary for each Identity Provider. For example, the data storage and retrieval APIs might +* provide off-device data storage, or on-device data storage - that could differ between one Identity Provider and another. Similarly, the personal information that can be retrieved with the +* getProperties() API call will differ based on what information each Identity Provider stores in their account system. +* +*
As such, this document gives an overview of the Identity Service library APIs that are available, and this information must be used in conjunction with the Identity Provider's specific Identity +* Service API overview to confirm the specifics of their implementation of each of these APIs. +* +*
DataStorage_section Data storage and retrieval APIs +* +*
Applications can make use of APIs in the IDS library to store and retrieve data. +*
APIs are provided for: +* - initial storage of the data (createData()) +* - retrieving the data (getData()) +* - updating the data (setData()) +* - removing the data (deleteData()) +* - listing the stored data (istData()) + +*
UserAuth_Section User authentication without prompting for credentials +* +*
Developers can use the Identity Services user authentication APIs in this library to avoid the need to implement user name and password management for their app. With these APIs, once the user is signed in using their account with the Identity Provider on the device, the user is automatically signed in to the app as well. +* - Users won't need to create or remember a username and password for the app. +* - Users won't need to specifically log in to the app, thus improving the ease of use of the app. +* +* +*
OffDeviceAuth_Section User authorization to access apps and off-device services offered by the Identity Provider +* +*
If your app interacts with an off-device service that requires user authentication (for example, a web site that requires the user to sign in with a username and password), +* you can use the Identity Service APIs to perform the off-device authentication/authorization using tokens, instead of prompting the user for credentials. Your app and the off-device service interact seamlessly. +* +* +*
PII_Section Access to the user's personal information associated with their account +* +*
The user's personal information that is available to the app will depend on what information is available from the Identity Provider's account system. +* +*
For example, if the app uses BlackBerry ID as the Identity Provider, the app can access the following personal information (provided that the user gives the app their consent): +* - first name +* - last name +* - screen name +* - username +* +*
For other Identity Providers, the personal information available will depend on what that provider stores in their identity account system. +* +*
ids_callback_sec About Callback functions +* +*
Many of the IDS APIs have the following three parameters: +* - Success callback function +* - Failure callback function +* +*
When your app sends API calls using the IDS APIs, the Identity Provider +* service responds asynchronously. When an app receives a response, the +* corresponding callback function that your application had provided for the +* success or failure case is executed. +* +*
The Identity Provider service uses callback functions to pass the parsed response +* back to your app. Callback functions cannot be NULL. Your app must specify what +* to do in both the success and failure scenarios. +* +* +*
bbid_modes_sec Registering your app to use the IDS APIs +* +*
To register your app so that it can use the IDS APIs, call +* registerProvider() from your app for at least one identity provider. +* +*
After your app sends a request, the Identity Provider service will process the +* request asynchronously, and call the corresponding success/failure callback function. +* +*
For example, your app can call getProperties() and pass a success +* callback of myAppSuccessCallback and a failure callback of +* myAppFailureCallback. When a response is ready from the identity provider, the +* success or failure callback will execute based on the results of the call. +* +* +* +* @featureID blackberry.user.identity +* @permission read_personally_identifiable_information Permits your app to access user +* identity information including the ability to store secondary user properties. +* @permission access_internet Permits your app to use the internet to access user data +* in remote storage. +*/ + +blackberry.user.identity = { + +/** + * The getVersion() function retrieves the version of the IDS library + * that your application is using. + * @BB10X + * @returns {int} + * "1000000" + * @example +* <script type="text/javascript"> +* alert("Identity Service version is:" + blackberry.user.identity.getVersion()); +* </script> */ +getVersion : function(){}, + +/** + * Applications use this function to register which Identity Provider(s) that + * they want to use. Once the application has initialized the library, it can + * register for each of the identity providers it is interested in. + * @param {String} name The name of the identity provider that the application wants to + * use for retrieving user identity information (only BlackBerry ID is supported + * at this time). + * @returns {int} result + * @BB10X + * @example + * <script type="text/javascript"> + var registerResult = blackberry.user.identity.registerProvider("ids:rim:bbid"); + if( registerResult.result ) { + alert("IDS register provider error: " + registerResult.result + " errno: " + registerResult.errno); + } + * </script> +*/ +registerProvider : function(name) { }, + + +/** + * Configure an option in the Identity Services library. These options allow an + * application to modify the default behavior of the IDS library as well as + * configure the way the library and application integrate together. + *
Available options are: + *
Set GUI Allowed (option = 0, value = true/false) + *
Option to set whether or not GUI allowed flag is set. Value is "true" or + * "false". By default, in cases where user input is required, the Identity + * Service performs the user interaction on behalf of the calling + * application. If this has been set to false, and user input is required, + * the API will return an error. If no user interaction is required to + * complete the API, this setting has no effect. + *
Set Group ID (option = 1, value = groupId) + *
Set the group ID of the calling application for UI dialogs. String + * version of UI group id. This is required in cases where the Identity + * Service requires user input from the user and must open an interface in + * the context of the calling application. + *
Set Verbosity (option = 2, value = {"Silent", "Normal", "Verbose") + *
Set the library logging verbosity level. Useful during application + * development to allow developers to be able to increase logging for + * diagnostics. Note that IDS logs are generated on stderr, and so should be + * captured in the application's log file. + * @param {int} option The option to be modified. + * @param {String} value The new string value to set + * @returns {int} + * @BB10X + * @example + * <script type="text/javascript"> + var setOptionResult = blackberry.user.identity.setOption(0, true); + if( setOptionResult.result ) { + alert("IDS set option error: " + setOptionResult.result + " errno: " + setOptionResult.errno); + } + * </script> + */ +setOption : function(option, value) { }, + +/** + * Issue a get token request. + * + * @param {String} provider The identity provider to send this request to. + * @param {String} tokenType A token type. It must be NOT NULL + * and 32 characters >= tokenType > 0 character + * @param {String} appliesTo The application or service to which the token applies. It + * must be NOT NULL and 96 characters >= applies_to > 0 character + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {JSON} successCallback.tokenResult A JSON object containing a token and it's information in the form below: + *
{
+ * "token": "ghdaj23i8rghaepeghk;a",
+ * "params": ["name":"TOKEN_SECRET","value":"oguireqhge"]
+ * }
+ * @callback {Function} failureCallback Function which is invoked when this method fails. This
+ * callback contains an errorCode parameter to specify the failure condition.
+ * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below:
+ *{
+ * "result":"50009",
+ * "errorDescription":"The appliesTo value is not valid"
+ * }
+ *
+ * Error Handling:
+ * Requests that do not complete successfully will result in the failure
+ * callback being called with one of the following result codes:
+ *
- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *
- IDS_UNKNOWN_APPLIES_TO: The appliesTo value is not valid. + *
- IDS_UNKNOWN_TOKEN_TYPE: The tokenType value is not valid. + *
- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *
- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *
- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *
- IDS_CANNOT_GET_TOKEN_WHILE_OFFLINE: The service is currently offline + * and cannot retrieve the requested token. + *
- IDS_ERROR_WHILE_CONTACTING_SERVICE: An error occurred communicating + * with the service. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function getTokenSuccess(tokenResult) { + alert("Received token: " + tokenResult.token); + for( param in tokenResult.tokenParams ) { + alert("Token param: " + tokenResult.tokenParams[param].name + " and value: " + tokenResult.tokenParams[param].value); + } + } + + function getTokenFailure(result) { + alert("Failed to retrieve token - result is: " + result.result + " with description: " + result.errorDescription); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.getToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", getTokenSuccess, getTokenFailure); + * </script> +*/ +getToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, + +/** + * Issue a clear token request. In cases where the token seems to be invalid or + * too close to expiry to be deemed useful, an application can clear out the + * currently cached token in order to retrieve a newly generated token in the + * next getToken() call. + * + * @param {String} provider The identity provider to send this request to. + * @param {String} tokenType A token type. It must be NOT NULL + * and 32 characters >= tokenType > 0 character + * @param {String} appliesTo The application or service to which the token applies. It + * must be NOT NULL and 96 characters >= applies_to > 0 character + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {JSON} successCallback.result A JSON object containing the in the form below: + *
{
+ * "result": true
+ * }
+ * @callback {Function} failureCallback Function which is invoked when this method fails. This
+ * callback contains an errorCode parameter to specify the failure condition.
+ * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below:
+ *{
+ * "result":"50009",
+ * "errorDescription":"The appliesTo value is not valid"
+ * }
+ *
+ * Error Handling:
+ * Requests that do not complete successfully will result in the failure
+ * callback being called with one of the following result codes:
+ *
- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *
- IDS_UNKNOWN_APPLIES_TO: The @c applies_to value is not valid. + *
- IDS_UNKNOWN_TOKEN_TYPE: The @c token_type value is not valid. + *
- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *
- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *
- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function clearTokenSuccess(clearTokenResult) { + alert("Token cleared: " + clearTokenResult.clear); + } + + function clearTokenFailure(result) { + alert("Failed to clear token - result is: " + result.result + " with description: " + result.errorDescription); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.clearToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", clearTokenSuccess, clearTokenFailure); + * </script> +*/ +clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, + +/** + * Issue a request for a property. + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of properties contained in the @c propertyList + * parameter. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {String} propertyList A comma separated string listing each of the properties + * requested + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {JSON} successCallback.result A JSON object containing the in the form below: + *
{[
+ * {"uri":"urn:bbid:firstname":"value":"john"},
+ {"uri":"urn:bbid:lastname":"value":"doe"}
+ * }
+ * @callback {Function} failureCallback Function which is invoked when this method fails. This
+ * callback contains an errorCode parameter to specify the failure condition.
+ * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below:
+ *{
+ * "result":"50004",
+ * "errorDescription":"The user could not be authenticated."
+ * }
+ * Error Handling:
+ * Requests that do not complete successfully will result in the failure
+ * callback being called with one of the following result codes:
+ *
- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *
- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *
- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *
- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *
- IDS_TOO_MANY_NAMES_PASSED: Too many properties were requested. See + * IDS_MAX_PROPERTY_COUNT. + *
- IDS_NAME_TOO_LONG: The length of a property name in the list exceeds + * the maximum name length IDS_MAX_PROPERTY_NAME_LEN. + *
- IDS_PROPERTY_NOT_AUTHORIZED: The application does not have access to + * one of the requested properties. + *
- IDS_PROPERTY_DOES_NOT_EXIST: Property does not exist. + *
- IDS_BAD_PROPERTY_NAME: Invalid property name. + *
- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *
- IDS_NON_EXISTING_PROPERTY: Property does not exist. + *
- IDS_PROFILE_SERVER_ERROR: Server error. + *
- IDS_PROPERTY_VALUE_TOO_LARGE: Property value is too large. + *
- IDS_GET_FAIL: Get failed. + * + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function getPropertiesSuccess(properties) { + alert("Get properties returned the following user properties:" + JSON.stringify(properties)); + } + + function getPropertiesFailure(result) { + alert("Failed to retrieve user properties: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.getProperties("ids:rim:bbid", 0, "urn:bbid:firstname,urn:bbid:lastname", getPropertiesSuccess, getPropertiesFailure); + * </script> +*/ +getProperties : function(idsProvider, 0, userProperties, successCallback, failureCallback) { }; + +/** + * Issue a request to set data + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of data. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {int} flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @param {String} dataName The data identifier + * @param {String} dataValue The content of the data + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+ * "result":"50004",
+ * "errorDescription":"The user could not be authenticated."
+ * }
+ * Error Handling:
+ * Requests that do not complete successfully will result in the failure
+ * callback being called with one of the following result codes:
+ *
- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *
- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *
- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *
- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *
- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *
- IDS_DOES_NOT_EXIST: Entry with the given name does not exist. + *
- IDS_NOT_ALLOWED: Application is not allowed to perform this operation. + *
- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *
- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function setDataSuccess() { + alert("Set property was successful"); + } + + function setDataFailure(result) { + alert("Failed to set data: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.setData("ids:rim:profile", 1, "usershandle", "johndoe123", setDataSuccess, setDataFailure); + * </script> +*/ +setData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; + +/** + * Issue a request to create data + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of data. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {int} flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * + * @param {String} dataName The property identifier + * @param {String} dataValue The content of the property + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+ * "result":"50004",
+ * "errorDescription":"The user could not be authenticated."
+ * }
+ * Error Handling:
+ * Requests that do not complete successfully will result in the failure
+ * callback being called with one of the following result codes:
+ *
- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *
- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *
- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *
- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *
- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *
- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *
- IDS_ALREADY_EXISTS: Entry with name already exists. + *
- IDS_NOT_ALLOWED: Application is not allowed to perform this operation. + *
- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider + * + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function createDataSuccess() { + alert("Create Data was successful"); + } + + function createDataFailure(result) { + alert("Failed to create data: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.createData("ids:rim:profile", 1, 0, "usershandle", "johndoe123", createDataSuccess, createDataFailure); + * </script> +*/ +createData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; + +/** + * Issue a request to data + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of data.Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {int} flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @param {String} dataName The property identifier + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+ * "result":"50004",
+ * "errorDescription":"The user could not be authenticated."
+ * }
+ * Error Handling:
+ * Requests that do not complete successfully will result in the failure
+ * callback being called with one of the following result codes:
+ *
- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *
- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *
- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, + * access is unavailable while locked. + *
- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *
- IDS_NOT_ALLOWED: The application does not have access to delete + * the requested value. + *
- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *
- IDS_DOES_NOT_EXIST: Name specified does not exist. + *
- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *
- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function deleteDataSuccess() { + alert("Delete data was successful"); + } + + function deleteDataFailure(result) { + alert("Failed to delete data: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.deleteData("ids:rim:profile", 1, 0, "usershandle", deleteDataSuccess, deleteDataFailure); + * </script> +*/ +deleteData : function(idsProvider, 0, 0, dataName, successCallback, failureCallback) { }; + + +/** + * Issue a request to challenge for identity + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of challenge requested. Each identity provider may + * have a unique set of types that it supports. See the identity provider's + * documentation for details on valid types and their behavior. + * @param {int}flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+ * "result":"50004",
+ * "errorDescription":"The user could not be authenticated."
+ * }
+ * Error Handling:
+ * Requests that do not complete successfully will result in the failure
+ * callback being called with one of the following result codes:
+ * - @c IDS_DEFAULT_ERROR: An internal error has occurred attempting to process
+ * the request.
+ * - @c IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to
+ * process the request.
+ * - @c IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked,
+ * access is unavailable while locked.
+ * - @c IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be
+ * authenticated.
+ * @returns {void}
+ * @BB10X
+ * @example
+ * <script type="text/javascript">
+ function challengeSuccess(level) {
+ alert("Challenge was successful: " + level);
+ }
+
+ function challengeFailure(result) {
+ alert("Challenge failed: " + result.result + " details: " + result.failureInfo);
+ }
+
+ blackberry.user.identity.registerProvider("ids:rim:bbid");
+ blackberry.user.identity.challenge("ids:rim:bbid", 0, 0, challengeSuccess, challengeFailure);
+ * </script>
+*/
+challenge : function(idsProvider, 0, 0, successCallback, failureCallback) { };
+
+
+/**
+ * Register a callback function to be called when the named entry
+ * changes
+ * @param {String} provider The identity provider to send this request to.
+ * @param {int} type The type of data referred to by name.
+ * @param {int} flags Special flags for the operation. Each provider may have a unique
+ * set of flags that it supports. See the documentation for the provider for
+ * details on valid values and their behaviour for this operation.
+ * @param {String} name The name of the entry to receive notifications for.
+ * @callback {Function} onChangeCallback The function that is invoked when a change is detected.
+ * @returns {void}
+ * @BB10X
+ * @example
+ * <script type="text/javascript">
+ function onChangeCb(tyfpe, name, notification) {
+ alert("Notification received: " + name + " with notification: " + notification);
+ }
+
+ blackberry.user.identity.registerProvider("ids:rim:bbid");
+ blackberry.user.identity.registerNotifier("ids:rim:bbid", 0, "propertyName", onChangeCb);
+ * </script>
+*/
+registerNotifier : function(idsProvider, 0, name, onChangeCallback) { };
+
+
+};
\ No newline at end of file
diff --git a/api/blackberry_user_identity_blackberryid.js b/api/blackberry_user_identity_blackberryid.js
new file mode 100644
index 0000000000..0648844478
--- /dev/null
+++ b/api/blackberry_user_identity_blackberryid.js
@@ -0,0 +1,77 @@
+/*
+* Copyright 2013 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+* @toc {User Identity} User Identity - BlackBerry ID
+* @BB10X
+* @namespace Use BlackBerry ID as an identity provider for your application.
+*
+*
Using the BlackBerry ID service as an identity provider, you can enhance
+* your app in several ways:
+* - Provide secure, off-device data storage and retrieval within the
+* BlackBerry ecosystem.
+* - Provide user authentication within your app, without prompting for
+* user credentials.
+* - Provide user authorization to access other BlackBerry apps and off-device
+* services without prompting for user credentials.
+* - Provide access to users' personal information that is stored in the
+* BlackBerry ID account system. User permission to access this information
+* is required.
+
+*
+*
Benefits of implementing BlackBerry ID user authentication:
+* - Eliminate the need to build your own username and password management.
+* - Automatically sign users in to your app after they sign in with their
+* BlackBerry ID account on their devices. This makes your app easier to use.
+* - Eliminate the need for users to create and remember a username and
+* password for your app.
+*
+*
If your app interacts with an off-device service that requires user +* authentication (for example, a website that requires the user to sign in +* with a username and password), you can use BlackBerry ID APIs to perform +* the off-device authentication/authorization using tokens, instead of +* prompting the user for credentials. Your app and the off-device service +* interact seamlessly. +* +*
You can personalize the user experience of your app by incorporating your
+* users' personal information in your app. Users must allow your app to
+* access the information associated with their BlackBerry ID accounts before
+* you can access it. The application must have the
+* read_personally_identifiable_information permission included in their bar
+* descriptor. The information that is available includes:
+* - first name
+* - last name
+* - screen name
+* - username (an email address)
+*
+*
The getProperties() function can be used to retrieve personal +* information stored in the BlackBerry ID account system, with +* CORE_PROPERTY_TYPE passed as the type parameter. +* +* @featureID blackberry.user.identity +* @permission read_personally_identifiable_information Permits your app to access user +* identity information including the ability to store secondary user properties. +* @permission access_internet Permits your app to use the internet to access user data +* in remote storage. +*/ +blackberry.user.identity.blackberryid = { +}; \ No newline at end of file diff --git a/api/blackberry_user_identity_blackberryprofile.js b/api/blackberry_user_identity_blackberryprofile.js new file mode 100644 index 0000000000..632bfbb9a4 --- /dev/null +++ b/api/blackberry_user_identity_blackberryprofile.js @@ -0,0 +1,131 @@ +/* +* Copyright 2013 Research In Motion Limited. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +/** +* @toc {User Identity} User Identity - BlackBerry Profile +* @BB10X +* @namespace Use BlackBerry profile as an identity provider, and provide +* off-device data storage. +* +*
BBProfile_Provider BlackBerry profile +* BlackBerry profile is an identity provider that allows access to +* off-device, encrypted storage space. The storage space is bound to the +* BlackBerry ID user that is currently logged in. The storage is accessible +* remotely from all devices logged in with the same BlackBerry ID user, +* allowing applications installed on multiple devices access to the same +* information. +* +* +*
BlackBerry profile supports the following Identity Service functions. Using
+* BlackBerry profile with other functions will result in errors.
+* - createData()
+* - getData()
+* - setData()
+* - deleteData()
+* - listData()
+* - registerNotifier()
+*
+*
+*
Applications can use the APIs to securely store data in, and retrieve data +* from, the BlackBerry ecosystem. APIs are provided for storing data initially +* (createData()), retrieving the data (getData()), updating the data +* (setData()), and removing the data (deleteData()). +* +* +*
In order to store and retrieve data off of the device, wireless data is +* consumed. Applications using storage from BlackBerry profile must have +* the access_internet permission included in their bar descriptor file. +* +*
There's a limit to the amount of off-device storage that is available to +* each of your users. Storage limits are set according to user and app +* vendor, and apply to all of the apps that a user might have with a +* single vendor. For example, if you have multiple apps that require +* off-device storage, and you have a user who makes use of three of those +* apps, that user's storage limit applies to the total amount of storage +* space that those three apps require. Users can have multiple storage +* allocations, one for each app vendor. +* +* +*
In cases where the application may need data stored locally for quick or +* repeated access, the value can be cached securely on the device and +* retrieved on demand, even when not connected to the remote storage copy. +* The cache is synchronized with the remote copy so that the cache is always +* up to date while the device has appropriate data coverage. +* +* +*
Create - Store a new entry
+* Call createData() to store new profile entries.
+* - type is one of the "profile types".
+* - flags are one of CREATE_DATA_ constants.
+*
+*
Set - Update an entry
+* Call setData() to update profile entries.
+* - type is one of the "profile types".
+* - flags are one of SET_DATA_ constants.
+*
+*
Get - Retrieve an entry
+* Call getData() to retrieve profile entries.
+* - type is one of the "profile types".
+* - flags are one of GET_DATA_ constants.
+*
+*
Delete - Remove an entry
+* Call deleteData() to remove profile entries.
+* - type is one of the "profile types".
+* - flags are one of DELETE_DATA_ constants.
+*
+*
Get - List available entries
+* Call listData() to list profile entries.
+* - type is one of the "profile types".
+* - flags are one of LIST_DATA_ constants.
+*
+*
+*
Notifications can be registered for entries either before or after they have +* been created. In cases where the registration is done after creation, the +* application is notified each time the value changes so that it can +* perform any necessary operations. If registration is done before an entry +* is created, the application is notified upon creation of the value as +* if it were an update. Additionally, registered applications receive a +* change notification when an entry is deleted. +* +*
To register for profile entry change notifications, call
+* registerNotifier().
+* - type is one of the "profile types".
+* - flags are one of NOTIFY_ constants.
+*
+*
Each time a registered entry changes, the registered callback function is +* executed and the corresponding NOTIFICATION_ indicates the kind of change +* that occurred. +* +* @featureID blackberry.user.identity +* @permission access_internet Permits your app to use the internet to access user data +* in remote storage. +*/ +blackberry.user.identity.blackberryprofile = { +}; \ No newline at end of file