Account API

The Account API provides functionality for using existing configured online accounts and providers, and for creating accounts of known types.

The basic concepts are:

  • Provider is an online service provider entity, such as Google, Vodafone or Facebook. A service provider is identified by its applicationId. Account provider will be registered while the application is installed. The information will be used in the "Add account" screen in Settings.
  • Account collects all the data (user name, credential, settings) needed for connecting to services. An account is always bound to a single provider, and has a list of service instances bound to the account. The services can be individually enabled and disabled on the given account. For instance, account1@gmail.com can identify a Google account, giving access to services such as gmail, gtalk, Picasa, and Youtube with each service having a separate service instance bound to the account.

To use add(), remove(), and update() methods of AccountManager a web application needs to be an account provider application. A web application is an account provider when its config.xml contains Account provider section. For example:
<tizen:account multiple-account-support="true">
   <tizen:icon section="Account">icon.png</tizen:icon>
   <tizen:icon section="AccountSmall">icon.png</tizen:icon>
   <tizen:display-name xml:lang="en-gb">Test</tizen:display-name>
   <tizen:capability>http://tizen.org/account/capability/contact</tizen:capability>
</tizen:account>

For more information about how to use Account API, see Account Guide.

Since: 2.3

Table of Contents

Summary of Interfaces and Methods

Interface Method
AccountManagerObject
AccountProvider
AccountInit
Account
void setExtendedData (DOMString key, DOMString value)
DOMString getExtendedData (DOMString key)
void getExtendedData (AccountExtendedDataArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
AccountManager
void add (Account account)
void remove (AccountId accountId)
void update (Account account)
void getAccounts (AccountArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional DOMString? applicationId)
void getProviders (AccountProviderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional DOMString? capability)
void removeAccountListener (long accountListenerId)
AccountExtendedData
AccountArraySuccessCallback
void onsuccess (Account[] accounts)
AccountExtendedDataArraySuccessCallback
void onsuccess (AccountExtendedData[] extendedDataArray)
AccountProviderArraySuccessCallback
void onsuccess (AccountProvider[] providers)
AccountChangeCallback
void onadded (Account account)
void onremoved (AccountId accountId)
void onupdated (Account account)

1. Type Definitions

1.1. AccountId

Account identifier. 
  typedef unsigned long AccountId;

Since: 2.3

2. Interfaces

2.1. AccountManagerObject

The AccountManagerObject interface defines what is instantiated in the tizen object. 
  [NoInterfaceObject] interface AccountManagerObject {
    readonly attribute AccountManager account;
  };
  Tizen implements AccountManagerObject;

Since: 2.3

The tizen.account object allows accessing the functionality of the Account API. There is one account manager in one web runtime. The Accounts back-end may support multiple account managers.

Attributes

  • readonly AccountManager account
    Object representing an account manager.

    Since: 2.3

2.2. AccountProvider

The AccountProvider interface represents a service provider, such as Google, Yahoo or Vodafone. 
  [NoInterfaceObject] interface AccountProvider {
    readonly attribute ApplicationId applicationId;
    readonly attribute DOMString displayName;
    readonly attribute DOMString iconUri;
    readonly attribute DOMString smallIconUri;
    readonly attribute DOMString[] capabilities;
    readonly attribute boolean isMultipleAccountSupported;
  };

Since: 2.3

Attributes

  • readonly ApplicationId applicationId
    Identifier of the account provider application.

    Since: 2.3

  • readonly DOMString displayName
    Logical (translatable) display name.

    Since: 2.3

  • readonly DOMString iconUri
    Path to the icon representing the account provider.

    Since: 2.3

  • readonly DOMString smallIconUri
    Path to the small icon representing the account provider.

    Since: 2.3

  • readonly DOMString[] capabilities
    Capabilities of the account provider defined in IRI format.

    The following predefined capabilities can be used.

    • http://tizen.org/account/capability/contact - Used when the account is related to contacts
    • http://tizen.org/account/capability/calendar - Used when the account is related to calendar

    Since: 2.3

  • readonly boolean isMultipleAccountSupported
    Boolean value that indicates whether multiple accounts are supported.

    Since: 2.3

2.3. AccountInit

The AccountInit dictionary represents options for creating accounts. Attributes are not mandatory, and can be added and modified by accessing the properties of account after the account is created. 
  dictionary AccountInit {
    DOMString userName;
    DOMString iconUri;
  };

Since: 2.3

2.4. Account

The Account interface is the interface for a single account. The implementation should manage authentication, storing eventual user credentials, presenting password dialogs, and so on. 
  [Constructor(AccountProvider provider, optional AccountInit? accountInitDict)]
  interface Account {
    readonly attribute AccountId? id;
    attribute DOMString? userName;
    attribute DOMString? iconUri;
    readonly attribute AccountProvider provider;
    void setExtendedData(DOMString key, DOMString value) raises(WebAPIException);
    DOMString getExtendedData(DOMString key) raises(WebAPIException);
    void getExtendedData(AccountExtendedDataArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                         raises(WebAPIException);
  };

Since: 2.3

The information is hidden from web applications.

Constructors

Constructor (AccountProvider, AccountInit?) 
Account(AccountProvider provider, optional AccountInit? accountInitDict);

Attributes

  • readonly AccountId id [nullable]
    Identifier for the account. By default, this attribute is set to null.

    Since: 2.3

  • DOMString userName [nullable]
    Account user name. By default, this attribute is set to null.

    Since: 2.3

  • DOMString iconUri [nullable]
    Name, identifier or URI of the icon. By default, this attribute is set to null.

    Since: 2.3

  • readonly AccountProvider provider
    Reference to the provider. There is one provider for each account. A given provider can be referenced from many accounts.

    Since: 2.3

Methods

setExtendedData
Adds the specified key and value to the extended data. 
void setExtendedData(DOMString key, DOMString value);

Since: 2.3

If the specified key already exists, the corresponding value is overwritten with the specified value.

Privilege level: public

Privilege: http://tizen.org/privilege/account.write

Parameters:

  • key: Key of the extended data.
  • value: Value of the extended data.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotFoundError, if account ID is null.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        var key = "nickname";
        var value = "nickname of anonymous user";
        account.setExtendedData(key, value);
        console.log(account.getExtendedData(key));

        account.setExtendedData(key, "nickname updated");
        console.log(account.getExtendedData(key));
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);

Output example:

"nickname of anonymous user"
"nickname updated"
getExtendedData
Gets the value for the given key from the extended data. Returns null if the given key is not found. 
DOMString getExtendedData(DOMString key);

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/account.read

Parameters:

  • key: Key of the extended data.

Return value:

    DOMString: Value of the extended data.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotFoundError, if account ID is null.

    • with error type UnknownError, if any other error occurs.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        var key = "accessToken";
        var value = account.getExtendedData(key);
        console.log(account.userName + "'s accessToken is " + value);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);
getExtendedData
Gets the extended data for the account as an array, asynchronously. Returns an empty array if there is no extended data. 
void getExtendedData(AccountExtendedDataArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/account.read

Parameters:

  • successCallback: Callback method that is invoked when an asynchronous call completes successfully.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any of the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotFoundError, if account ID is null.

    • with error type UnknownError, if any other error occurs.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        account.getExtendedData(
            function(extendedData)
            {
              for (var i = 0; i < extendedData.length; i++)
              {
                var key = extendedData.key;
                var value = extendedData.value;
                console.log(key + ": " + value);
              }
            },
            function(e)
            {
              console.log("Error: " + e.message);
            });
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);

2.5. AccountManager

The AccountManager interface provides configuration functionality for providers and accounts. 
  [NoInterfaceObject] interface AccountManager {
    void add(Account account) raises(WebAPIException);
    void remove(AccountId accountId) raises(WebAPIException);
    void update(Account account) raises(WebAPIException);
    Account? getAccount(AccountId accountId) raises(WebAPIException);
    void getAccounts(AccountArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                     optional DOMString? applicationId) raises(WebAPIException);
    AccountProvider? getProvider(ApplicationId applicationId) raises(WebAPIException);
    void getProviders(AccountProviderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                      optional DOMString? capability) raises(WebAPIException);
    long addAccountListener(AccountChangeCallback callback) raises(WebAPIException);
    void removeAccountListener(long accountListenerId) raises(WebAPIException);
  };

Since: 2.3

Methods

add
Adds an account to the account database. 
void add(Account account);

Since: 2.3

If the account is added successfully, an accountId and provider are newly assigned when the function returns.

This method can be used only by an account provider application.
If the application is registered as provider, it will be launched to authenticate the account. You should implement the appcontrol for the account provider.
For more details, see Account Provider

Privilege level: public

Privilege: http://tizen.org/privilege/account.write

Parameters:

  • account: Account object to be added.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any of the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
var provider = tizen.account.getProvider(appId);
var account = new tizen.Account(provider, {userName: "admin", iconUri: "path/to/icon.jpg"});

tizen.account.add(account);
remove
Removes an account from the account database. 
void remove(AccountId accountId);

Since: 2.3

Removes the account in the database that corresponds to the specified identifier. The function will throw an exception if it failed to remove the specified account.

This method can be used by an account provider application.

Privilege level: public

Privilege: http://tizen.org/privilege/account.write

Parameters:

  • accountId: Identifier of the account to remove.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        tizen.account.remove(account.id);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);
update
Updates an account. 
void update(Account account);

Since: 2.3

This method can be used only an account provider application.

Privilege level: public

Privilege: http://tizen.org/privilege/account.write

Parameters:

  • account: Account object to update.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any of the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        account.userName = "abc";
        tizen.account.update(account);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);
getAccount
Gets the Account object with the given identifier. 
Account? getAccount(AccountId accountId);

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/account.read

Parameters:

  • accountId: Account identifier.

Return value:

    Account [nullable]: Object with the given identifier or null.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

var account = tizen.account.getAccount(1);
getAccounts
Gets the accounts associated with the provider that has a specified applicationId, asynchronously. If you want to get all accounts, omit the applicationId argument. 
void getAccounts(AccountArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                 optional DOMString? applicationId);

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/account.read

Parameters:

  • successCallback: Callback method that is invoked when an asynchronous call completes successfully.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.
  • applicationId [optional] [nullable]: ApplicationId of the provider application.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any of the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

tizen.account.getAccounts(
    function(accounts)
    {
      /* Accounts is an array whose members are all registered accounts in this device. */
    },
    function(e)
    {
      console.log("Error: " + e.message);
    });
getProvider
Gets the account provider with the given application identifier. 
AccountProvider? getProvider(ApplicationId applicationId);

Since: 2.3

You can register your application as an account provider by writing account related information in config.xml.
For more details, see Account Provider

Privilege level: public

Privilege: http://tizen.org/privilege/account.read

Parameters:

  • applicationId: Identifier of the account provider application.

Return value:

    AccountProvider [nullable]: Object with the given applicationId or null.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
var provider = tizen.account.getProvider(appId);
if (!provider)
{
  console.log("Current application is not account provider");
}
getProviders
Gets the providers with the given capabilities, asynchronously. If you want to get all the providers, omit the capability argument. 
void getProviders(AccountProviderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                  optional DOMString? capability);

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/account.read

Parameters:

  • successCallback: Callback method that is invoked when an asynchronous call completes successfully.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.
  • capability [optional] [nullable]: Predefined capability or the vendor-specific capability in IRI format.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any of the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

tizen.account.getProviders(
    function(providers)
    {
      /* Providers is an array whose members are account providers, */
      /* which have contact capability. */
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    "http://tizen.org/account/capability/contact");
addAccountListener
Adds an account listener for watching changes to accounts. 
long addAccountListener(AccountChangeCallback callback);

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/account.read

Parameters:

  • callback: Callback method that is invoked for the events about accounts such as adding or removing an account.

Return value:

    long: Identifier to clear the watch subscription for account changes.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any of the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

tizen.account.addAccountListener({
  onadded: function(account)
  {
    /* Callback function which will be called when account is added. */
  },
  onremoved: function(accountId)
  {
    /* Callback function which will be called when account is removed. */
  },
  onupdated: function(account)
  {
    /* Callback function which will be called when account is updated. */
  }
});
removeAccountListener
Removes the previously registered listener. 
void removeAccountListener(long accountListenerId);

Since: 2.3

Calling this function has no effect if there is no listener with given id.

Privilege level: public

Privilege: http://tizen.org/privilege/account.read

Parameters:

  • accountListenerId: Identifier of the listener for the account changes.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

var watchId = tizen.account.addAccountListener(
{
  onadded: function(account)
  {
    /* Callback function which will be called when account is added. */
  },
  onremoved: function(accountId)
  {
    /* Callback function which will be called when account is removed. */
  },
  onupdated: function(account)
  {
    /* Callback function which will be called when account is updated. */
  }
});
tizen.account.removeAccountListener(watchId);

2.6. AccountExtendedData

The AccountExtendedData interface defines the extended data of an account. 
  [NoInterfaceObject] interface AccountExtendedData {
    readonly attribute DOMString key;
    readonly attribute DOMString value;
  };

Since: 2.3

Attributes

  • readonly DOMString key
    Name (key) of the account extended data item.

    Since: 2.3

  • readonly DOMString value
    Value of the account extended data item.

    Since: 2.3

2.7. AccountArraySuccessCallback

The AccountArraySuccessCallback interface provides the success method for AccountManager.getAccounts. 
  [Callback, NoInterfaceObject] interface AccountArraySuccessCallback {
    void onsuccess(Account[] accounts);
  };

Since: 2.3

Methods

onsuccess
Called when information of accounts is ready. 
void onsuccess(Account[] accounts);

Since: 2.3

Parameters:

  • accounts: Received accounts.

2.8. AccountExtendedDataArraySuccessCallback

The AccountExtendedDataArraySuccessCallback provides the success method for Account.getExtendedData. 
  [Callback, NoInterfaceObject] interface AccountExtendedDataArraySuccessCallback {
    void onsuccess(AccountExtendedData[] extendedDataArray);
  };

Since: 2.3

Methods

onsuccess
Called when information of extended data is ready. 
void onsuccess(AccountExtendedData[] extendedDataArray);

Since: 2.3

Parameters:

  • extendedDataArray: Array of extended data.

2.9. AccountProviderArraySuccessCallback

The AccountProviderArraySuccessCallback interface provides the success method for AccountManager.getProviders. 
  [Callback, NoInterfaceObject] interface AccountProviderArraySuccessCallback {
    void onsuccess(AccountProvider[] providers);
  };

Since: 2.3

Methods

onsuccess
Called when information of providers are ready. 
void onsuccess(AccountProvider[] providers);

Since: 2.3

Parameters:

  • providers: Received providers.

2.10. AccountChangeCallback

The AccountChangeCallback interface defines callbacks for getting notified about account changes. 
  [Callback, NoInterfaceObject] interface AccountChangeCallback {
    void onadded(Account account);
    void onremoved(AccountId accountId);
    void onupdated(Account account);
  };

Since: 2.3

Methods

onadded
Called when an account is added. 
void onadded(Account account);

Since: 2.3

Parameters:

  • account: Added account information.
onremoved
Called when an account is removed. 
void onremoved(AccountId accountId);

Since: 2.3

Parameters:

  • accountId: ID of the removed account.
onupdated
Called when an account is updated. 
void onupdated(Account account);

Since: 2.3

Parameters:

  • account: Updated account information.

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee the running of the application on a device with Account feature, declare the following feature requirement in the config file:

  • http://tizen.org/feature/account

    • For more information, see Application Filtering.

    4. Full WebIDL

    module Account {
  typedef unsigned long AccountId;
  dictionary AccountInit {
    DOMString userName;
    DOMString iconUri;
  };
  Tizen implements AccountManagerObject;
  [NoInterfaceObject] interface AccountManagerObject {
    readonly attribute AccountManager account;
  };
  [NoInterfaceObject] interface AccountProvider {
    readonly attribute ApplicationId applicationId;
    readonly attribute DOMString displayName;
    readonly attribute DOMString iconUri;
    readonly attribute DOMString smallIconUri;
    readonly attribute DOMString[] capabilities;
    readonly attribute boolean isMultipleAccountSupported;
  };
  [Constructor(AccountProvider provider, optional AccountInit? accountInitDict)]
  interface Account {
    readonly attribute AccountId? id;
    attribute DOMString? userName;
    attribute DOMString? iconUri;
    readonly attribute AccountProvider provider;
    void setExtendedData(DOMString key, DOMString value) raises(WebAPIException);
    DOMString getExtendedData(DOMString key) raises(WebAPIException);
    void getExtendedData(AccountExtendedDataArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                         raises(WebAPIException);
  };
  [NoInterfaceObject] interface AccountManager {
    void add(Account account) raises(WebAPIException);
    void remove(AccountId accountId) raises(WebAPIException);
    void update(Account account) raises(WebAPIException);
    Account? getAccount(AccountId accountId) raises(WebAPIException);
    void getAccounts(AccountArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                     optional DOMString? applicationId) raises(WebAPIException);
    AccountProvider? getProvider(ApplicationId applicationId) raises(WebAPIException);
    void getProviders(AccountProviderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                      optional DOMString? capability) raises(WebAPIException);
    long addAccountListener(AccountChangeCallback callback) raises(WebAPIException);
    void removeAccountListener(long accountListenerId) raises(WebAPIException);
  };
  [NoInterfaceObject] interface AccountExtendedData {
    readonly attribute DOMString key;
    readonly attribute DOMString value;
  };
  [Callback, NoInterfaceObject] interface AccountArraySuccessCallback {
    void onsuccess(Account[] accounts);
  };
  [Callback, NoInterfaceObject] interface AccountExtendedDataArraySuccessCallback {
    void onsuccess(AccountExtendedData[] extendedDataArray);
  };
  [Callback, NoInterfaceObject] interface AccountProviderArraySuccessCallback {
    void onsuccess(AccountProvider[] providers);
  };
  [Callback, NoInterfaceObject] interface AccountChangeCallback {
    void onadded(Account account);
    void onremoved(AccountId accountId);
    void onupdated(Account account);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.