Howto

Making your application a full-fledged participant in the federated social web is not easy, but gradual and incremental improvements can make your users' activities visible to others.

• Make good feeds. We need to have ActivityStreams feeds for OStatus. Fortunately, ActivityStreams has default behaviour defined for plain-old RSS 2.0 and Atom feeds, so the feeds you have now are probably fine. Ideally you should have a single feed for each person. You should define an author element at the feed level. Author elements should always have a URI element that uniquely identifies the author. Your feed should be discoverable with a <link> from the person's HTML profile page.

• Optional: use Activity Streams. Enhancing your feeds with ActivityStreams data like a verb and object can make the information much richer. Adding <link> elements with rel=”avatar” will make the user's avatar available.

• Optional: use Portable Contacts. You can add Portable Contacts elements as extensions to the <author> element. Important elements include <preferredUsername>, <displayName>, <note>, and <urls>.

• PuSH-enable your feeds. PubSubHubbub (“PuSH”) makes real-time updates to feed subscribers possible. Your user feeds should be PuSH-enabled. This requires two steps: first, adding the declaration of a hub in the Atom or RSS 2.0 feed. Second, sending a new-content update to the hub when there's new content.

If you get to this point, other people on the OStatus network can subscribe to your users by using their profile pages ('http://example.com/someuser') as the identifier.

• Provide WebFinger identities. OStatus users prefer identifiers like someuser@example.com. To let others refer to your users with this syntax, you'll need to implement WebFinger. You should at least implement the http://schemas.google.com/g/2010#updates-from Link to link to your activities feed.

At this point, your users are full-fledged broadcasters on the federated social web, but they're unable to receive information from others.

• Model remote users. This can be the trickiest part of implementing OStatus. You'll need to allow for authors of comments, “favorites”, and so on to be people who don't have accounts on your local system. One typical way to do this is to have a superclass, Author, with subclasses User and RemoteAuthor (or something similar). Be careful about modeling identifiers; typically usernames are unique for Users but not for RemoteAuthors. Another option is to model remote users as a user role with the absolute minimum permissions.

• Accept Salmon for replies. OStatus servers will try to send a Salmon slap when a remote user comments on or replies to an activity by one of your users. Ideally, you should accept these Salmon messages, display them, and notify the user. Note that typical precautions about comment spam apply here.

• Accept Salmon for social activities. OStatus servers will also send Salmon slaps containing ActivityStreams representations of social activities involving your users when those activities happen remotely. If you keep a record of “followers” for a user, the Follow verb can be useful. Also important are the Like (or “Fave”) and Share verbs. If you cache remote users' profile data on your server, you should also handle the ProfileChange verb (custom for OStatus).

By here, your users can publish activities and have a two-way conversation with remote users. If your application also has reading capabilities, you may want to add remote users as an information source, too.

• Allow subscriptions to remote users. You can implement the more complex subscriber role in PuSH. Note that there's a user-interface issue here; your users will have to tell you which remote user feeds they want to subscribe to. You should allow discovery using WebFinger and the “updates-from” relationship; also with a profile page, digging for the element that points to an Atom feed.

• Optional: implement OStatus subscribe link. Some OStatus systems (like StatusNet) let a browsing user provide a WebFinger identity to initiate subscription from the publisher's Web interface. To make this work, you'll need to implement the http://ostatus.org/schema/1.0/subscribe WebFinger relationship (described in the OStatus protocol documents)

• Optional: extract Portable Contacts profile information. You can get richer representations of remote users' profiles by extracting the Portable Contacts data from the <author> elements in feeds. You can also watch for profile update activities to come through the PuSH-enabled feed.

• Send Salmon for replies. If your user replies to, or comments on, a remote activity, send a Salmon slap to the remote user. This will require discovering the remote user's Salmon endpoint and posting a reply to it.

• Send Salmon for social activities. You can help remote users track popularity and reach by posting ActivityStreams representations of your user interactions with their feeds. The Follow verb helps them keep a list of followers. If you send the Follow verb, make sure to send ProfileUpdate activities so that the social graph on the remote user's site stays in synch. Like and Share are also useful for remote users to track. Finally, the corresponding verbs (Unlike, Unshare, Unfollow) can help keep the state synchronized.