Creating a Social Provider

Making a new Social Provider

The Social API is one of the central, 'named' interfaces within freedom.js. By providing a standardized interface with strict semantics, we allow many different networks to be pluggable in any new freedom.js application. This allows users to use social applications on the social networks they are already a part of, reduces the load on developers to support every different network, and allows freedom.js applications to expand even to networks that don't have official APIs through user-developed plugins.

A social provider is typically implemented by mapping the small set of defined methods to external network communication over one of the provided communication channels. These include xhr requests made to an official API, websocket communications for long-lived and server-push based networks, and even socket communications to interact with legacy xmpp servers or other non-http networks for platforms supporting privileged network communications.

What is a social provider?

A social provider is responsible for the following things:

• Providing a 'Roster' of friends who are visible to the current user. These friends can have statuses of 'online' and 'offline', depending on how the network handles visibility.
• Sending and receiving messages to a friend listed in the roster. Some applications will be designed for these messages to be delivered in a relatively short amount of time if both users are online.

That's it.

To fulfill these tasks, the social interface also enforces conventions to ease development. This results in the following API:

The Social API

Code

• login(Object loginOptions)
  • Log into the network
  • loginOptions may contain a user agent and version of the application, whether the request is user interactive, and whether the login credentials should be remembered.
  • The provider should return the userId of the current user on successful login.
• clearCachedCredentials
  • Clears cached credentials of the provider.
• getClients
  • Get the client state objects that have been observed
• getUsers
  • Get the user profiles that have been observed
• sendMessage(String user, String message)
  • Send a message to a user or client
• logout
  • log out of the network.

The provider also is expected to raise the following events

• onMessage
  • A message has been received from another user.
• onUserProfile
  • A friend's status has been updated (namely their name or picture)
• onClientState
  • A friend's status has been updated (namely the online status of one of their devices)