660 lines
28 KiB
HTML
660 lines
28 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1">
|
|
<title>Cosmopolite Reference</title>
|
|
|
|
<link rel="stylesheet" href="stylesheets/styles.css">
|
|
<link rel="stylesheet" href="stylesheets/pygment_trac.css">
|
|
</head>
|
|
<body>
|
|
<div class="wrapper">
|
|
<header>
|
|
<h1 class="header"><a href="/">Cosmopolite</a></h1>
|
|
<p class="header">Client/server publish/subscribe, presence and key/value storage for AppEngine</p>
|
|
|
|
<ul>
|
|
<li class="download"><a class="buttons" href="https://github.com/flamingcowtv/cosmopolite/zipball/master" onclick="return trackOutboundLink(this.href);">Download ZIP</a></li>
|
|
<li class="download"><a class="buttons" href="https://github.com/flamingcowtv/cosmopolite/tarball/master" onclick="return trackOutboundLink(this.href);">Download TAR</a></li>
|
|
<li><a class="buttons github" href="https://github.com/flamingcowtv/cosmopolite" onclick="return trackOutboundLink(this.href);">View On GitHub</a></li>
|
|
<li><a class="buttons forum" href="https://groups.google.com/a/cosmopolite.org/forum/#!forum/discuss" onclick="return trackOutboundLink(this.href);">Mailing list</a></li>
|
|
</ul>
|
|
|
|
</header>
|
|
<section>
|
|
<h1>
|
|
<a name="cosmopolite" class="anchor" href="#cosmopolite"><span class="octicon octicon-link"></span></a>Cosmopolite Reference</h1>
|
|
|
|
<ul>
|
|
<li><a href="#terms">Terms</a>
|
|
<ul>
|
|
<li><a href="#profile">Profile</a></li>
|
|
<li><a href="#client">Client</a></li>
|
|
<li><a href="#instance">Instance</a></li>
|
|
<li><a href="#channel">Channel</a></li>
|
|
<li><a href="#subject">Subject</a></li>
|
|
<li><a href="#subscription">Subscription</a></li>
|
|
<li><a href="#message">Message</a></li>
|
|
<li><a href="#pin">Pin</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#callbacks">Callbacks</a>
|
|
<ul>
|
|
<li><a href="#onConnect">onConnect</a></li>
|
|
<li><a href="#onDisconnect">onDisconnect</a></li>
|
|
<li><a href="#onLogin">onLogin</a></li>
|
|
<li><a href="#onLogout">onLogout</a></li>
|
|
<li><a href="#onMessage">onMessage</a></li>
|
|
<li><a href="#onPin">onPin</a></li>
|
|
<li><a href="#onUnpin">onUnpin</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#methods">Methods</a>
|
|
<ul>
|
|
<li><a href="#constructor">Constructor</a></li>
|
|
<li><a href="#shutdown">shutdown()</a></li>
|
|
<li><a href="#getProfile">getProfile()</a></li>
|
|
<li><a href="#currentProfile">currentProfile()</a></li>
|
|
<li><a href="#subscribe">subscribe()</a></li>
|
|
<li><a href="#unsubscribe">unsubscribe()</a></li>
|
|
<li><a href="#sendMessage">sendMessage()</a></li>
|
|
<li><a href="#getMessages">getMessages()</a></li>
|
|
<li><a href="#getLastMessage">getLastMessage()</a></li>
|
|
<li><a href="#pin_method">pin()</a></li>
|
|
<li><a href="#unpin">unpin()</a></li>
|
|
<li><a href="#getPins">getPins()</a></li>
|
|
<li><a href="#trackEvent">trackEvent()</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3><a name="terms">Terms</a></h3>
|
|
|
|
<h4><a name="profile">Profile</a></h4>
|
|
|
|
<p>A profile is a collection of clients that all speak as the same user, and so should appear as the
|
|
same to subscribers. Profiles are identified by a string key assigned by the server. Clients can
|
|
fetch their own profile by calling <a href="#getProfile">getProfile()</a> or
|
|
<a href="#currentProfile">currentProfile()</a>. Profile information for other users is provided
|
|
in the <i>sender</i> field of a <a href="#message">Message</a>.</p>
|
|
|
|
<p>A client keeps its profile when it logs in to a Google account, accept if that account is
|
|
already associated with a different profile. In that case, messages that were sent using the old
|
|
profile are re-assigned to the profile associated with the logged in user.</p>
|
|
|
|
<p>Logging out changes profiles.</p>
|
|
|
|
<p>The profile key is passed to Google Analytics (if enabled) as the userId, so sessions from
|
|
different clients across different browsers are associated with the same user for analytics
|
|
purposes.</p>
|
|
|
|
|
|
<h4><a name="client">Client</a></h4>
|
|
|
|
<p>A client is a persistent identifier for a given browser. It is identified by a string key
|
|
generated by the client and stored in localStorage, so it is persistent across restarts (except in
|
|
incognito mode or the like). A client is associated with exactly one <a href="#profile">profile</a>
|
|
at any time, but may change associated profiles on log in.</p>
|
|
|
|
<p>Logging out generates and stores a new client key.</p>
|
|
|
|
|
|
<h4><a name="instance">Instance</a></h4>
|
|
|
|
<p>An instance is a persistent identifier for a single connection to the server. It is generated
|
|
when a new Cosmopolite instance is constructed or whenever the server -> client
|
|
<a href="#channel">channel</a> connection is interrupted.</p>
|
|
|
|
<p>Instances are used to track <a href="#subscription">Subscriptions</a> and <a href="#pin">Pins</a>
|
|
which cease to exist (from the server perspective) when a client disconnects.</p>
|
|
|
|
|
|
<h4><a name="channel">Channel</a></h4>
|
|
|
|
<p>A channel is the message push connection from the server to the client used to send updates. It
|
|
uses Google AppEngine's
|
|
<a href="https://developers.google.com/appengine/docs/python/channel/">Channel service</a>.</p>
|
|
|
|
<p>In addition to message passing, the channel library also provides notification of connection
|
|
state to the server. This is passed to the application code using the
|
|
<a href="#onConnect">onConnect</a> and <a href="#onDisconnect">onDisconnect</a> callbacks.</p>
|
|
|
|
|
|
<h4><a name="subject">Subject</a></h4>
|
|
|
|
<p>A subject is a topic that clients publish and subscribe to. Subjects may be strings, numbers
|
|
or objects with access control information embedded. The follow are all valid <b>and different</b>
|
|
subjects:
|
|
|
|
<ul>
|
|
<li><code>"foo"</code></li>
|
|
<li><code>5</code></li>
|
|
<li><code>{ name: "foo", readable_only_by: "XXXprofileXXX" }</code></li>
|
|
<li><code>{ name: "foo", writable_only_by: "YYYprofileYYY" }</code></li>
|
|
<li><code>{ name: "foo", readable_only_by: "XXXprofileXXX", writable_only_by: "YYYprofileYYY" }</code></li>
|
|
<li><code>{ name: "foo", readable_only_by: "admin" }</code></li>
|
|
<li><code>{ name: "foo", writable_only_by: "admin" }</code></li>
|
|
</ul>
|
|
|
|
where XXXprofileXXX and YYYprofileYYY are profile keys. <code>admin</code> is a magic value that
|
|
only allows accounts marked as administrators in the AppEngine application to perform the action.
|
|
</p>
|
|
|
|
|
|
<h4><a name="subscription">Subscription</a></h4>
|
|
|
|
<p>A subscription ties an <a href="#instance">instance</a> to a <a href="#subject">subject</a> and
|
|
requests that the client be kept informed of changes to that subject. Changes that cause
|
|
notification are:
|
|
|
|
<ul>
|
|
<li>A client sends a <a href="#message">message</a> to the subject.</li>
|
|
<li>A client adds a <a href="#pin">pin</a> to the subject.</li>
|
|
<li>A client removes a <a href="#pin">pin</a> from the subject.</li>
|
|
<li>A client which had previously added a <a href="#pin">pin</a> disconnects. This appears to an
|
|
observer as if the client had removed the pin.</li>
|
|
</ul>
|
|
|
|
When a new subscription is established, the server sends all active pins and a client-specified
|
|
subset of historical messages to the client.</p>
|
|
|
|
<p>Subscriptions are automatically destroyed on the server side when an instance disconnects. The
|
|
client library keeps lists of subjects and the last messages seen from them and automatically
|
|
re-subscribes after reconnection. This process is transparent to application code.</p>
|
|
|
|
<p>Subscriptions are created by the application using the <a href="#subscribe">subscribe()</a>
|
|
method.</p>
|
|
|
|
|
|
<h4><a name="message">Message</a></h4>
|
|
|
|
<p>A message is a piece of information sent by a <a href="#client">client</a> to a
|
|
<a href="#subject">subject</a>. It is stored by the server and transmitted to any clients currently
|
|
<a href="#subscription">subscribing</a> to that subject.</p>
|
|
|
|
<p>A message can consist of any type that is serializable in JSON: numbers, booleans, strings,
|
|
null, arrays and objects composed of these values (or of other arrays and objects). Serialization
|
|
and deserialization is handled by Cosmopolite.</p>
|
|
|
|
<p>When a message is received (via the <a href="#onMessage">onMessage callback</a> or the return
|
|
result from <a href="#getMessages">getMessages()</a> or
|
|
<a href="#getLastMessage">getLastMessage()</a>), metadata is attached, packaged into an object with
|
|
the message data itself:
|
|
|
|
<pre>{
|
|
<comment>// Server-assigned sequence number</comment>
|
|
"id": 1,
|
|
|
|
<comment>// Type may also be <a href="#pin">"pin"</a></comment>
|
|
"event_type": "message",
|
|
|
|
<comment>// Sender-assigned UUID</comment>
|
|
"sender_message_id": "cbdae48d-7a02-4850-208c-986b18121b9c",
|
|
|
|
<comment>// Canonical subject that message was sent to</comment>
|
|
"subject": {
|
|
"name": "foobar"
|
|
},
|
|
|
|
<comment>// Server-recorded UNIX timestamp that the server received the message</comment>
|
|
"created": 1402212355.0,
|
|
|
|
<comment>// Deserialized message data</comment>
|
|
"message": "test",
|
|
|
|
<comment>// <a href="#profile">Profile</a> key of sender</comment>
|
|
"sender": "XXXprofileXXX"
|
|
}</pre></p>
|
|
|
|
<p>Messages are sent by the application using the <a href="#sendMessage">sendMessage()</a>
|
|
method.</p>
|
|
|
|
|
|
<h4><a name="pin">Pin</a></h4>
|
|
|
|
<p>A pin is a <a href="#message">message</a> that is deleted when the
|
|
<a href="#instance">instance</a> that sent it disconnects. Subscribers to the pin's
|
|
<a href="#subject">subject</a> are notified (via the <a href="#onPin">onPin</a> and
|
|
<a href="#onUnpin">onUnpin</a> callbacks) when it is added and deleted. This allows pins to be
|
|
used for presence detection.</p>
|
|
|
|
<p>Pins are added and deleted by the application using the <a href="#pin_method">pin()</a>
|
|
and <a href="#unpin">unpin()</a> methods.</p>
|
|
|
|
|
|
<h3><a name="callbacks">Callbacks</a></h3>
|
|
|
|
Callbacks are used by the Cosmopolite client library to notify the application of events. Callbacks
|
|
are passed to the Cosmopolite constructor in an object. The object itself and all callbacks are
|
|
optional.
|
|
|
|
|
|
<h4><a name="onConnect">onConnect</a></h4>
|
|
|
|
<p>Arguments: <i>none</i></p>
|
|
|
|
<p>The onConnect callback is called when the <a href="#channel">channel</a> is established to the
|
|
server. It is paired with the <a href="#onDisconnect">onDisconnect</a> callback except when
|
|
<a href="#shutdown">shutdown()</a> is called.</p>
|
|
|
|
|
|
<h4><a name="onDisconnect">onDisconnect</a></h4>
|
|
|
|
<p>Arguments: <i>none</i></p>
|
|
|
|
<p>The onDisconnect callback is called when the <a href="#channel">channel</a> is disconnected.
|
|
This can happen due to connectivity problems, server outages or periodically when the channel
|
|
expires.</p>
|
|
|
|
|
|
<h4><a name="onLogin">onLogin</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>username</code>: The user's Google username string.</li>
|
|
<li><code>logout_url</code>: A URL that the user can load to terminate their session. This should
|
|
be opened in a new window (using <code>target="_blank"</code>).</li>
|
|
</ol></p>
|
|
|
|
<p>The onLogin callback is called when the user logs in. It is also called after the first RPC
|
|
to the server succeeds if the user was already logged in. It is guaranteed that either onLogin
|
|
or <a href="#onLogout">onLogout</a> is called after the first RPC succeeds.</p>
|
|
|
|
|
|
<h4><a name="onLogout">onLogout</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>login_url</code>: A URL that the user cna load to log in to their Google account. This
|
|
should be opened in a new window (using <code>target="_blank"</code>).</li>
|
|
</ol></p>
|
|
|
|
<p>The onLogin callback is called when the user logs out or is logged out by Google. It is also
|
|
called after the first RPC to the server succeeds if the user was not already logged in. It is
|
|
guaranteed that either <a href="#onLogin">onLogin</a> or onLogout is called after the first RPC
|
|
succeeds.</p>
|
|
|
|
|
|
<h4><a name="onMessage">onMessage</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>message</code>: A <a href="#message">message</a> object including metadata and message
|
|
content.</li>
|
|
</ol></p>
|
|
|
|
<p>The onMessage callback is called when a historical or new message is received from the server.
|
|
It is only called for <a href="#subject">subjects</a> that the client is currently subscribed to.
|
|
</p>
|
|
|
|
<p>After a call to <a href="#subscribe">subscribe()</a>, onMessage fires once for each historical
|
|
message received from the server. After all historical messages have been processed, the resolve
|
|
callback for the Promise returned by subscribe() is called. Any onMessage events after that point
|
|
are for new messages.</p>
|
|
|
|
<p>Calling <a href="#subscribe">subscribe()</a> more than once may lead to additional historical
|
|
messages being retreived. onMessage will not fire twice for the same message unless
|
|
<a href="#unsubscribe">unsubscribe()</a> is called in the interim.</p>
|
|
|
|
<p>onMessage fires for messages sent by our own <a href="#profile">profile</a> and
|
|
<a href="#client">client</a>. You can filter messages by comparing their sender field to the return
|
|
value of <a href="#currentProfile">currentProfile()</a> to avoid processing your own messages.</p>
|
|
|
|
<p>onMessage may fire when we are not connected (per the <a href="#onConnect">onConnect</a> and
|
|
<a href="#onDisconnect">onDisconnect</a> callbacks), as messages may be received in RPC responses
|
|
instead of over the <a href="#channel">channel</a></p>
|
|
|
|
|
|
<h4><a name="onPin">onPin</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>message</code>: A <a href="#message">message</a> object including metadata and message
|
|
content.</li>
|
|
</ol></p>
|
|
|
|
<p>The onPin callback is called when a new pin is received from the server. It is only called for
|
|
<a href="#subject">subjects</a> that the client is currently subscribed to.</p>
|
|
|
|
<p>After a call to <a href="#subscribe">subscribe()</a>, onPin fires once for each pin already
|
|
present in the subject. After all standing pins have been processed, the resolve callback for the
|
|
Promise returned by subscribe() is called. Any onPin events after that point are for new pins.</p>
|
|
|
|
<p>onPin callbacks are paired with <a href="#onUnpin">onUnpin</a> callbacks except when
|
|
<a href="#shutdown">shutdown()</a> is called.</p>
|
|
|
|
<p>onPin fires for pins from own <a href="#profile">profile</a> and <a href="#client">client</a>.
|
|
You can filter pins by comparing their sender field to the return value of
|
|
<a href="#currentProfile">currentProfile()</a> to avoid processing your own pins.</p>
|
|
|
|
<p>onPin may fire when we are not connected (per the <a href="#onConnect">onConnect</a> and
|
|
<a href="#onDisconnect">onDisconnect</a> callbacks), as messages may be received in RPC responses
|
|
instead of over the <a href="#channel">channel</a></p>
|
|
|
|
|
|
<h4><a name="onUnpin">onUnpin</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>message</code>: A <a href="#message">message</a> object including metadata and message
|
|
content.</li>
|
|
</ol></p>
|
|
|
|
<p>The onUnpin callback is called when a pin is deleted on from the server. It is also called when
|
|
the <a href="#channel">channel</a> disconnects from the server, hence the server state of pins is
|
|
unknown.</p>
|
|
|
|
<p>onUnpin callbacks are paired with <a href="#onPin">onPin</a> callbacks except when
|
|
<a href="#shutdown">shutdown()</a> is called.</p>
|
|
|
|
<p>onUnpin fires for pins from own <a href="#profile">profile</a> and <a href="#client">client</a>.
|
|
You can filter pins by comparing their sender field to the return value of
|
|
<a href="#currentProfile">currentProfile()</a> to avoid processing your own pins.</p>
|
|
|
|
<p>onUnpin may fire when we are not connected (per the <a href="#onConnect">onConnect</a> and
|
|
<a href="#onDisconnect">onDisconnect</a> callbacks), as messages may be received in RPC responses
|
|
instead of over the <a href="#channel">channel</a></p>
|
|
|
|
|
|
<h3><a name="methods">Methods</a></h3>
|
|
|
|
|
|
<h4><a name="constructor">Constructor</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>callbacks</code> (optional): An object with <a href="#callbacks">callback</a> names as
|
|
keys and functions as values. All callbacks are optional.</li>
|
|
<li><code>urlPrefix</code> (optional): A string containing the URL path at which to find the
|
|
server-side cosmopolite endpoints. Defaults to "/cosmopolite". See the
|
|
<a href="overview#architecture">architecture</a> diagram.</li>
|
|
<li><code>namespace</code> (optional): A string containing a namespace prefix to be used for
|
|
entries in localStorage. Defaults to "cosmopolite". Changing this allows multiple local instances
|
|
of Cosmopolite to co-exist on the same domain without interfering.</li>
|
|
<li><code>trackingID</code> (optional): A string containing a
|
|
<a href="https://support.google.com/analytics/answer/1032385?hl=en">Google Analytics tracking /
|
|
web property ID</a> (usually starting with "UA-") identifying your analytics account. Passing
|
|
this argument enables event tracking and the <a href="#trackEvent">trackEvent()</a> method.</li>
|
|
</ol></p>
|
|
|
|
<p>Construct a new Cosmopolite instance. Always use the <code>new</code> keyword. All methods on
|
|
the instance are available for immediate use, though some deferred initialization is occuring and
|
|
some actions may be queued.</p>
|
|
|
|
</ol>
|
|
|
|
|
|
<h4><a name="shutdown">shutdown()</a></h4>
|
|
|
|
<p>Arguments: <i>none</i></p>
|
|
|
|
<p>Start shutdown of this instance. No callbacks will be fired after this call. Some RPCs may be
|
|
outstanding and some cleanup may be deferred.</p>
|
|
|
|
|
|
<h4><a name="getProfile">getProfile()</a></h4>
|
|
|
|
<p>Arguments: <i>none</i></p>
|
|
|
|
<p>Returns: A
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">
|
|
Promise</a> to provide a <a href="#profile">profile</a> ID string.</p>
|
|
|
|
<p>As the <a href="#profile">profile</a> ID is generated by the server, it requires a round trip
|
|
to complete successfully before it is known to the client. getProfile() returns a promise that
|
|
resolves immediately if the profile ID is already known, or fires when it becomes available.</p>
|
|
|
|
|
|
<h4><a name="currentProfile">currentProfile()</a></h4>
|
|
|
|
<p>Arguments: <i>none</i></p>
|
|
|
|
<p>Returns: A <a href="#profile">profile</a> ID string, or null if unknown.</p>
|
|
|
|
<p>currentProfile() has simpler semantics than <a href="getProfile()">getProfile()</a> but may
|
|
return null if the initial RPC to the server is still outstanding. It is not safe to use just after
|
|
construction. It is safe to use from callbacks and promises returned by other functions, as those
|
|
require a server response.</p>
|
|
|
|
|
|
<h4><a name="subscribe">subscribe()</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>subject</code>: A valid <a href="#subject">subject</a> (string, number or object with
|
|
specific keys), or an Array of subjects</li>
|
|
<li><code>messages</code> (optional): An integer number of historical messages to retrieve from
|
|
this subject if available. 0 means no messages; -1 means all messages.</li>
|
|
<li><code>lastID</code> (optional): The id field from the last message received by the client.
|
|
The server will send historical messages starting from the message after that.</li>
|
|
</ol>
|
|
|
|
<p>Returns: A
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">
|
|
Promise</a> that resolves with no arguments on success, or rejects with no arguments if the client
|
|
is denied access to read the subject. If the <code>subject</code> argument was an Array of
|
|
subjects, returns an Array of Promises that correspond.</p>
|
|
|
|
<p>subscribe() creates a <a href="#subscription">subscription</a> on the server to a particular
|
|
subject. The subscription is tied to our current <a href="#instance">instance</a> but is re-created
|
|
by the client library when it reconnects, transparent to the application.</p>
|
|
|
|
<p>Before the promise returned by subscribe() resolves, the <a href="#onMessage">onMessage</a> and
|
|
<a href="#onPin">onPin</a> callbacks will fire for any historical messages requests and available
|
|
and for any current pins. After the promise resolves, <a href="#message">messages</a> and
|
|
<a href="#pin">pins</a> sent to this subject will cause the callbacks to fire when they are
|
|
received. Additionally, the <a href="#onUnpin">onUnpin</a> callback will fire for deleted pins.</p>
|
|
|
|
<p>Callbacks fire for messages sent by our own <a href="#profile">profile</a> and
|
|
<a href="#client">client</a>. You can filter messages by comparing their sender field to the return
|
|
value of <a href="#currentProfile">currentProfile()</a> to avoid processing your own messages.</p>
|
|
|
|
<p>subscribe() may be called multiple times for the same subject to retrieve additional historical
|
|
messages. The subscriptions do not stack, however; a single call to
|
|
<a href="#unsubscribe">unsubscribe()</a> undoes all preceding subscribe() calls to that subject.
|
|
</p>
|
|
|
|
<p>subscribe() calls may fail (and reject the promise) when subscription is requested to a
|
|
<a href="#subject">subject</a> that sets <code>readable_only_by</code> and that does not match our
|
|
profile.</p>
|
|
|
|
|
|
<h4><a name="unsubscribe">unsubscribe()</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>subject</code>: A valid <a href="#subject">subject</a> (string, number or object with
|
|
specific keys)</li>
|
|
</ol></p>
|
|
|
|
<p>Returns: A
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">
|
|
Promise</a> that resolves on RPC completion.</p>
|
|
|
|
<p>Unsubscribe from a <a href="#subject">subject</a> and stop receiving
|
|
<a href="#callbacks">callbacks</a> related to it. Callbacks stop immediately after calling
|
|
unsubscribe().</p>
|
|
|
|
<p>A single call to unsubscribe() undoes all calls to <a href="#subscribe">subscribe()</a> for the
|
|
given subject.</a>
|
|
|
|
|
|
<h4><a name="sendMessage">sendMessage()</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>subject</code>: A valid <a href="#subject">subject</a> (string, number or object with
|
|
specific keys)</li>
|
|
<li><code>message</code>: The <a href="#message">message</a> data. Any value that JSON can
|
|
serialize is valid.</li>
|
|
</ol></p>
|
|
|
|
<p>Returns: A
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">
|
|
Promise</a> that resolves on success, or rejects with no arguments if the client is denied access
|
|
to write to the subject. On success, a <a href="#message">message</a> argument is passed to the
|
|
resolution callback; it differs from the original <code>message</code> argument in that it has
|
|
metadata added by the server.</p>
|
|
|
|
<p>Sends a <a href="#message">message</a> to the given <a href="#subject">subject</a>. The message
|
|
contents are serialized and sent to the server (see
|
|
<a href="overview#architecture">architecture</a>). The server adds metadata (sequence number,
|
|
timestamp, sender profile ID), stores the message and sends it on to any current
|
|
<a href="#subscription">subscribers</a> to the subject, including possibly back to the local
|
|
client. Future subscribers can fetch the historical message from the server's storage (as opposed
|
|
to a <a href="#pin">pin</a> which is ephemeral and tied to the current
|
|
<a href="#instance">instance</a>).</p>
|
|
|
|
<p>The message may be rejected by server (causing the promise to reject) if the
|
|
<a href="#subject">subject</a> sets <code>writable_only_by</code> and it does not match our
|
|
current profile.</p>
|
|
|
|
<p>If we are also <a href="#subscribe">subscribed</a> to the given subject and have provided an
|
|
<a href="#onMessage">onMessage</a> callback, it will fire for this message when it is received
|
|
back from the server. You can filter messages by comparing their sender field to the return value
|
|
of <a href="#currentProfile">currentProfile()</a> to avoid processing your own messages.</p>
|
|
|
|
|
|
<h4><a name="getMessages">getMessages()</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>subject</code>: A valid <a href="#subject">subject</a> (string, number or object with
|
|
specific keys)</li>
|
|
</ol></p>
|
|
|
|
<p>Returns: An ordered (oldest to newest) array of <a href="#message">message</a> objects.</p>
|
|
|
|
<p>The client library keeps a cache of messages received from
|
|
<a href="#subscription">subscriptions</a>. getMessage() returns the contents of that cache.</p>
|
|
|
|
<p>Note that only subjects for which <a href="#subscribe">subscribe()</a> has been called are valid
|
|
to pass to getMessage(), and that getMessage() only returns historical messages as specified by the
|
|
arguments to subscribe(). To fetch more historical messages, call subscribe() again with different
|
|
arguments.</p>
|
|
|
|
|
|
<h4><a name="getLastMessage">getLastMessage()</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>subject</code>: A valid <a href="#subject">subject</a> (string, number or object with
|
|
specific keys)</li>
|
|
</ol></p>
|
|
|
|
<p>Returns: The most recent <a href="#message">message</a> object received, or null if none.</p>
|
|
|
|
<p>Similar to <a href="#getMessages">getMessages()</a>, but only returns the most recent message
|
|
received from the server (in server sequence number ordering). This is useful for applications
|
|
using Cosmopolite as a key/value store that don't need to interact with the historical messages.
|
|
</p>
|
|
|
|
|
|
<h4><a name="pin_method">pin()</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>subject</code>: A valid <a href="#subject">subject</a> (string, number or object with
|
|
specific keys)</li>
|
|
<li><code>message</code>: The <a href="#message">message</a> data. Any value that JSON can
|
|
serialize is valid.</li>
|
|
</ol></p>
|
|
|
|
<p>Returns: A
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">
|
|
Promise</a> that resolves on success, or rejects with no arguments if the client is denied access
|
|
to write to the subject. If successful, it is passed a single string argument containing a unique
|
|
identifier for the pin that can later be passed on <a href="#unpin">unpin()</a>.</p>
|
|
|
|
<p>A <a href="#pin">pin</a> is like a <a href="#message">message</a>, with some differences: it is
|
|
tied to the lifetime of the current <a href="#instance">instance</a> and
|
|
<a href="#channel">channel</a>, it can be deleted by the publishing <a href="#client">client</a>
|
|
(by calling <a href="#unpin">unpin()</a>, and it is unordered on the server.</p>
|
|
|
|
<p>The pin may be rejected by server (causing the promise to reject) if the
|
|
<a href="#subject">subject</a> sets <code>writable_only_by</code> and it does not match our
|
|
current profile.</p>
|
|
|
|
<p>If we are also <a href="#subscribe">subscribed</a> to the given subject and have provided an
|
|
<a href="#onPin">onPin</a> callback, it will fire for this pin when it is received back from the
|
|
server. You can filter pins by comparing their sender field to the return value of
|
|
<a href="#currentProfile">currentProfile()</a> to avoid processing your own pins.</p>
|
|
|
|
|
|
<h4><a name="unpin">unpin()</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>id</code>: An ID string previously passed to the resolve callback of the promise
|
|
returned by <a href="#pin_method">pin()</a> or the <code>sender_message_id</code> from the
|
|
<a href="#onPin">onPin</a> callback or the return value of <a href="#getPins">getPins()</a>.</p>
|
|
</ol></p>
|
|
|
|
<p>Returns: A
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">
|
|
Promise</a> that resolves with no arguments on RPC completion</p>
|
|
|
|
<p>Remove a currently active <a href="#pin">pin</a>. The pin must have been added by this
|
|
<a href="#client">client</a>, but not necessarily by this <a href="#instance">instance</a> (the
|
|
client library automatically re-adds pins after reconnection).</p>
|
|
|
|
|
|
<h4><a name="getPins">getPins()</a></h4>
|
|
|
|
<p>Arguments:
|
|
<ol>
|
|
<li><code>subject</code>: A valid <a href="#subject">subject</a> (string, number or object with
|
|
specific keys)</li>
|
|
</ol></p>
|
|
|
|
<p>Returns: An unordered array of <a href="#message">message</a>-like <a href="#pin"> objects.</a>
|
|
</p>
|
|
|
|
<p>The client library keeps a list of currently active pins
|
|
<a href="#subscription">subscriptions</a>. getPins() returns the contents of that cache.</p>
|
|
|
|
|
|
<h4><a name="trackEvent">trackEvent()</a></h4>
|
|
|
|
<p>Arguments: the same as the
|
|
<a href="https://developers.google.com/analytics/devguides/collection/analyticsjs/method-reference">ga()</a>
|
|
function from Google Analytics.</p>
|
|
|
|
<p>If trackingID was passed to the Cosmopolite <a href="#constructor">constructor</a>, Cosmopolite
|
|
sends analytics events on load and subscribe. To avoid duplicate work initializing the analytics
|
|
library, trackEvent() provides a passthrough to the analytics interface.</p>
|
|
|
|
<p>Cosmopolite does not send a
|
|
<a href="https://developers.google.com/analytics/devguides/collection/analyticsjs/pages">pageview</a>
|
|
event. To tie together tracking data, it is recommended that you send at least one pageview from
|
|
your application code.</p>
|
|
|
|
</section>
|
|
</div>
|
|
<script>
|
|
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-37845853-2', 'auto');
|
|
ga('require', 'displayfeatures');
|
|
ga('send', 'pageview');
|
|
|
|
var trackOutboundLink = function(url) {
|
|
ga('send', 'event', 'outbound', 'click', url, {
|
|
'hitCallback': function () {
|
|
document.location = url;
|
|
}
|
|
});
|
|
return false;
|
|
}
|
|
|
|
</script>
|
|
</body>
|
|
</html>
|