Skip to content
ActivityPub object

FEP-136c: Comment Tracking Services

Summary

A comment tracking service adds the capability to comment on a site via the Fediverse. The site here is possibly static and usually hosted seperately from the comment tracking service.

This FEP describes

  • the mechanisms for linking the site to the comment tracking system
  • what is a comment
  • mechanisms to identify that an actor belongs to a comment tracking system
  • expectations on how the comment tracking system decimates information

Message Flow

We now describe the request flows between the user, the site, and the comments server.

Retrieving a page with comments

The page, the user retrieves from the static site, will contain an API endpoint on the comments server. From the API endpoint the comments will be fetched as a cross origin request. The comments will then be rendered inside the static page.

sequenceDiagram
actor User

User ->> Site: GET /page
Site ->> User: HTML
Note over User: Retrieve API endpoint for comments
User ->> Comments-Server: GET /comments/{pageId} (CORS)
Comments-Server ->> User: JSON Response
Note over User: Render comments in page

Commenting

When commenting the user will talk with comments server with their Fediverse home server as an intermediary.

sequenceDiagram
actor User

User ->> Site: GET /page
opt Open in Fediverse App
Note over User: Retrieve URL for ActivityPub
User ->> Fediverse Home: GET /query?uri={activity_pub_url}
Fediverse Home ->> Comments-Server: GET /{activity_pub_url}
end

opt Reply
User ->> Fediverse Home: Reply to retrieved object
Fediverse Home ->> Comments-Server: POST /inbox with reply
end

Here the ActivityPub URL is retrieved using one of the two mechanisms below.

Creating an initial page object

So far the comment tracking system hasn't talked to the site yet. This in fact only necessary in the second case below.

sequenceDiagram

Fediverse Home ->> Comments-Server: GET /{activity_pub_url}

alt In Database
Comments-Server ->> Fediverse Home: ActivityPub Object
else Not in Database
Comments-Server ->> Site: GET /page
Site  ->> Comments-Server: HTML
Comments-Server ->> Fediverse Home: ActivityPub Object
end

This also motivates one of our design choices! The ActivityPub url will need to contain the location of the page.

Linking between Comment Tracking System and the Site

We expect the site to be a collection of HTML files and possibly other assets. We do not assume control on the underlying hosting provider.

A HTML page can include information on alternative formats via a link element with rel="alternate". We will use this in the form of

<link rel="alternate"
    type="application/activity+json"
    href="https://comments.example/path/to/activity/pub/representation">

This mechanism is useful for programmatic retrievable. So when a Fediverse application looks up an object and retrieves an answer with content type text/html, it should check for such a link element. If it is found, the Fediverse application should follow the link.

Direct URL

This is done by providing a link inside the page, that is user visible, where the user can copy the ActivityPub URL from. This URL can then be pasted into their Fediverse application.

The URL format for ActivityPub objects

Note

One might want to make different choices here. Unfortunately, that would lead to different comment tracking systems not being interoperable.

As mentioned above, we will need to recover the URL of the original page from the ActivityPub object id. To do so, we use the format:

https://comments.server.domain/some/path/{base64-encoded-page-url}

for the URL of ActivityPub object. Here bas64 encoded means url safe with padding.

APIS

The ActivityPub endpoint

The ActivityPub endpoint should obey the following OpenAPI. This is not strictly necessary, as ActivityPub is quite flexible. However, by obeying it one reduces future interoperability headaches.

The comments API

Should obey the following OpenAPI.

Actors on the Comment Tracking System

It is recommended to use a different actor for each site supported by the comment tracking system.

Properties of each actor

  • The actor should be of type Service
  • The html url of the actor should be the root of the corresponding site
  • The actor should have a name and summary
  • Proper property values should be used to indicate this is a comment tracking system
  • The actor should automatically accept followers

Processing activities

Activities should be processed and made available in the appropriate collections as described in ActivityPub endpoint. Activities should be announced to all followers via the FEP-1b12: Group federation mechanism.

Implementing

Implementations are split into two parts

  • The Comment Tracking System
  • The generator for the site

If interoperability works, one should be able to mix and match these.

Comment Tracking System

Static Site Generators

What needs to be implemented:

  • Add the links as described here
  • Display replies, i.e. fetch from comments api and render

Examples

References

  • Christine Lemmer-Webber, Jessica Tallon, Erin Shepherd, Amy Guy, Evan Prodromou, ActivityPub, 2018

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.

Comments