xeps/inbox/notification-inbox.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Notification Inbox</title>
  <abstract>This document defines a protocol to manage a notification inbox for pending events.</abstract>
  &LEGALNOTICE;
  <number>XXXX</number>
  <status>ProtoXEP</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>inbox</shortname>
  <schemaloc/>
  <author>
    <firstname>Valerian</firstname>
    <surname>Saliou</surname>
    <email>valerian@valeriansaliou.name</email>
    <jid>valerian@jappix.com</jid>
    <uri>https://valeriansaliou.name/</uri>
  </author>
  <revision>
    <version>0.0.2</version>
    <date>2015-12-09</date>
    <initials>XEP Editor (mam)</initials>
    <remark><p>Updated contact information for Valerian Saliou.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2011-05-06</date>
    <initials>vs</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>When interacting with an user, like replying to some comments or adding photo tags, this remote user has no way to get notifications of what happen about him. This specification defines a method for managing such notifications.</p>
</section1>

<section1 topic='Requirements' anchor='requirements'>
  <p>The user who will receive notifications MUST:</p>
  <ul>
    <li>Create a "urn:xmpp:inbox" PEP node on his JID.</li>
    <li>Configure the "urn:xmpp:inbox" PEP node with "pubsub#access_model" to "whitelist" and "pubsub#publish_model" to "open".</li>
  </ul>
  <p>In order to get incoming notifications in real-time, the client MAY advertise support for "urn:xmpp:inbox+notify" in its &xep0115; data.</p>
  <p>Clients that provide notifications inbox support MAY request all the "urn:xmpp:inbox" node items on the user's PEP service.</p>
</section1>

<section1 topic='Protocol' anchor='protocol'>
  <section2 topic='Notification types' anchor='notif_types'>
    <p>If the event to notify is listed in the following array, the client MUST consider using the defined event type:</p>
    <table caption='Notification types'>
      <tr>
        <th>Type Name</th>
        <th>Definition</th>
      </tr>
      <tr>
        <td>comment</td>
        <td>The sender replied to some comments.</td>
      </tr>
      <tr>
        <td>like</td>
        <td>The sender liked an item.</td>
      </tr>
      <tr>
        <td>quote</td>
        <td>The sender quoted the user in a post.</td>
      </tr>
      <tr>
        <td>wall</td>
        <td>The sender published an entry on the user's wall.</td>
      </tr>
      <tr>
        <td>photo</td>
        <td>The sender tagged the user in a photo.</td>
      </tr>
      <tr>
        <td>video</td>
        <td>The sender tagged the user in a video.</td>
      </tr>
  </table>
  </section2>
  <section2 topic='Publishing a notification' anchor='notif_publish'>
    <p>If Romeo wants to notify all the users who posted a comment in a comment node, his client MUST send a payload to every user's PEP node.</p>
    <p>The notification type is stored in the "title" attribute of the "link" element, also containing the URI ("href" attribute) to the target item. The notification text content is stored in the "content" element.</p>
    <example caption="Publishing a notification"><![CDATA[
<iq from='romeo@montague.lit/mobile'
    id='pub1'
    to='juliet@capulet.lit'
    type='set'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='urn:xmpp:inbox'>
      <item id='9844f81e1408f6ecb932137d33bed7cfdcf518a3'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <source>
            <author>
              <name>Romeo Montague</name>
              <uri>xmpp:romeo@montague.lit</uri>
            </author>
          </source>
          <content type="text">May I bring my horse?</content>
          <link rel="via" title="comment" href="xmpp:benvolio@montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0%3Acomments%3A97b64c89747aecbc8077cdab941d92be;item=f3fea3c068f66fee8b66673a6ccd78b6">
          <published>2011-05-06T13:31:51Z</published>
        </entry>
      </item>
    </publish>
  </pubsub>
</iq>
    ]]></example>
  </section2>
  <section2 topic='Receiving a notification' anchor='notif_receive'>
    <p>Juliet tagged Romeo in a photo. Romeo's client gets pushed of the new item:</p>
    <example caption="Receiving a notification"><![CDATA[
<message to='romeo@montague.lit'
         from='juliet@capulet.lit'
         type='headline'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='urn:xmpp:inbox'>
      <item id='6728ffa81dddf38d375eb3d86e3f70086a41db65'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <source>
            <author>
              <name>Juliet Capulet</name>
              <uri>xmpp:juliet@capulet.lit</uri>
            </author>
          </source>
          <content type='text'>Hiking with Romeo</content>
          <link rel="via" title="photo" href="xmpp:juliet@capulet.lit?;node=urn%3Axmpp%3Aalbum%2Fa73933b0408af49f1305cb47a4bb10d7913f0fd0;item=6a18f571bc9b92a442aa80ad2649b0679c8e7b30">
          <published>2011-05-06T14:39:43Z</published>
        </entry>
      </item>
    </items>
  </event>
</message>
    ]]></example>
  </section2>
  <section2 topic='Removing a notification' anchor='notif_remove'>
    <p>Romeo viewed the last notification he received. His client now removes it (as defined in &xep0060;):</p>
    <example caption='Removing a notification'><![CDATA[
<iq type='set'
    from='romeo@montague.lit/mobile'
    id='retract1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <retract node='urn:xmpp:notify'>
      <item id='9844f81e1408f6ecb932137d33bed7cfdcf518a3'/>
    </retract>
  </pubsub>
</iq>
    ]]></example>
  </section2>
  <section2 topic='Emptying notifications' anchor='notif_empty'>
    <p>Romeo wants to clear all the pending notifications. His client purges the "urn:xmpp:inbox" PEP node (as defined in &xep0060;):</p>
    <example caption='Emptying notifications'><![CDATA[
<iq type='set'
    from='romeo@montague.lit/mobile'
    id='purge1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <purge node='urn:xmpp:notify'/>
  </pubsub>
</iq>
    ]]></example>
  </section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>The client SHOULD check that the author informations (provided in the "author" element) are valid, by checking that the "publisher" item attribute value matches the "uri" element value. If there is a difference, the notification MIGHT NOT be displayed, and the client SHOULD remove it (see the <link url='#notif_remove'>Removing a notification</link> section of this document).</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <p>This specification re-uses the schema for the Atom content format, i.e., the 'http://www.w3.org/2005/Atom' namespace (see <cite>RFC 4287</cite>).</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Laurent Eschenauer for his initial idea.</p>
</section1>
</xep>