Content Index

1. Introduction

High quality offline-enabled web content is not easily discoverable by users right now. Users would have to know which websites work offline, or they would need to have an installed PWA, to be able to browse through content while offline. This is not a great user experience as there no entry points to discover available content. To address this, the spec covers a new API which allows developers to tell the browser about their specific content.

The content index allows websites to register their offline enabled content with the browser. The browser can then improve the website’s offline capabilities and offer content to users to browse through while offline. This data could also be used to improve on-device search and augment browsing history.

Using the API can help users more easily discover content for the following example use cases:

• A news website prefetching the latest articles in the background.

• A content streaming app registering downloaded content with the browser.

1.1. Example

function deleteArticleResources(id) {
  return Promise.all([
    caches.open('offline-articles')
        .then(articlesCache => articlesCache.delete(`/article/${id}`)),
    // This is a no-op if the function was called as a result of the
    // `contentdelete` event.
    self.registration.index.delete(id),
  ]);
}

self.addEventListener('activate', event => {
  // When the service worker is activated, remove old content.
  event.waitUntil(async function() {
    const descriptions = await self.registration.index.getAll();
    const oldDescriptions =
        descriptions.filter(description => shouldRemoveOldArticle(description));
    await Promise.all(
        oldDescriptions.map(description => deleteArticleResources(description.id)));
  }());
});

self.addEventListener('push', event => {
  const payload = event.data.json();

  // Fetch & store the article, then register it.
  event.waitUntil(async function() {
    const articlesCache = await caches.open('offline-articles');
    await articlesCache.add(`/article/${payload.id}`);
    await self.registration.index.add({
      id: payload.id,
      title: payload.title,
      description: payload.description,
      category: 'article',
      icons: payload.icons,
      url: `/article/${payload.id}`,
    });

    // Show a notification if urgent.
  }());
});

self.addEventListener('contentdelete', event => {
  // Clear the underlying content after user-deletion.
  event.waitUntil(deleteArticleResources(event.id));
});    

2. Privacy Considerations

Firing the contentdelete event may reveal the user’s IP address after the user has left the page. Exploiting this can be used for tracking location history. The user agent SHOULD limit tracking by capping the duration of the event.

When firing the contentdelete event, the user agent SHOULD prevent the website from adding new content. This prevents spammy websites from re-adding the same content, and the users from being shown content they just deleted.

Displaying all registered content can cause malicious websites to spam users with their content to maximize exposure. User agents are strongly encouraged to not surface all content, but rather choose the appropriate content to display based on a set of user agent defined signals, aimed at improving the user experience.

3. Infrastructure

3.1. Extensions to service worker registration

A service worker registration additionally has:

3.2. Content index entry

A content index entry consists of:

3.2.1. Display

The user agent MAY display a content index entry (entry) at any time, as long as entry exists in a service worker registration's content index entries.

Note: User agents should limit surfaced content to avoid showing too many entries to a user.

3.2.2. Undisplay

4. Algorithms

4.1. Delete a content index entry

4.2. Activate a content index entry

4.3. Fire a content delete event

5. API

5.1. Extensions to ServiceWorkerGlobalScope

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler oncontentdelete;
};

5.1.1. Events

The following is the event handler (and its corresponding event handler event type) that must be supported, as event handler IDL attributes, by all objects implementing ServiceWorker interface:

5.2. Extensions to ServiceWorkerRegistration

partial interface ServiceWorkerRegistration {
  [SameObject] readonly attribute ContentIndex index;
};

5.3. ContentIndex

enum ContentCategory {
  "",
  "homepage",
  "article",
  "video",
  "audio",
};

dictionary ContentDescription {
  required DOMString id;
  required DOMString title;
  required DOMString description;
  ContentCategory category = "";
  sequence<ImageResource> icons = [];
  required USVString url;
};

[Exposed=(Window,Worker)]
interface ContentIndex {
  Promise<undefined> add(ContentDescription description);
  Promise<undefined> delete(DOMString id);
  Promise<sequence<ContentDescription>> getAll();
};

5.4. ContentIndexEvent

dictionary ContentIndexEventInit : ExtendableEventInit {
  required DOMString id;
};

[Exposed=ServiceWorker]
interface ContentIndexEvent : ExtendableEvent {
  constructor(DOMString type, ContentIndexEventInit init);
  readonly attribute DOMString id;
};