- Elements of the Channel API
- Life of a typical channel message
- Example Tic Tac Toe application
- Tracking client connections and disconnections
- Tokens and security
Elements of the Channel API
- Connecting to the channel after it receives the channel's unique token from the server.
- Listening on the channel for updates regarding other clients and making appropriate use of the data, such as updating the interface.
- Sending update messages to the server so they may be passed on to remote clients.
The server is responsible for:
- Receiving update messages from clients via HTTP requests.
- Sending update messages to clients via their channels.
- Optionally, managing client connection state.
The client ID
A client ID can be anything that makes sense in the design of your application. For example, you can use something like cookie or login information, randomized numerical ID, or a user-selected name.
You can also create client IDs in whatever way makes sense in your application. For example, you might choose to create the client ID on the client and pass it to the server in an explicit request for a token, or create it on the server and inject it into the page's HTML when the server replies to the browser's request for the page.
Tokens expire after two hours and should also be treated as secret. For more details, see the Tokens and Security section.
Messages are sent via HTTP requests from one client to the server. When a message is received, the server passes the message to the designated client via the correct channel identified by the client ID. Messages are limited to 32K.
The server can register to receive a notification when a client connects to or disconnects from a channel.
Life of a typical channel message
These two diagrams illustrate the life of a typical example message sent via Channel API between two different clients using one possible implementation of Channel API.
Next, the server uses client A’s client ID to create a channel and then sends the token for that channel back to client A. Client A uses the token to open a socket and listen for updates on the channel.
This diagram shows client B sending a message using HTTP
POST to the server.
The server processes the message and sends it to client A over the channel.
Client A receives the message and makes use of the new information.
Example Tic Tac Toe application
To better illustrate how to use Channel API, take a look at the following example Tic Tac Toe game application written in Python. The game allows users to create a game, invite another player by sending out a URL, and play the game together in real time. The application updates both players' views of the board in real time as soon as the other player makes a move.
The full source code of the application is available at the Channel Tac Toe Project page. We'll go over major highlights that illustrate Channel API below.
Creating and connecting to a channel
When a user visits the Tic Tac Toe game for the first time, two things happen:
- The game server injects a token into the html page sent to the client. The client uses this token to open a socket and listen for updates on the channel.
- The game server provides the user with a URL they can share with a friend in order to invite him or her to join the game.
method and get a token that the client page can use to connect to the channel.
create_channel(), they should use a key that the application can
use to uniquely identify the client.
The following server side Python code creates the channel on the server for the Tic Tac Toe application:
The client creates a new
goog.appengine.Channel object using the token
provided by the server.
The game client uses the Channel object's
open() method to create a socket.
The client also sets callback functions on the socket to be called when the
state of the socket changes.
Opening the socket
In our example, when the Tic Tac Toe client is ready to receive messages, it
onOpened() function, which is set to the socket's
onOpened function also updates the UI for the user to indicate that the
game is ready to play and sends a
POST message to the server to ask it to send
the latest game state.
Note that the application defines
sendMessage() as a wrapper around
XmlHttpRequest, which the client uses to send messages to the server.
Updating the game state
onClick handler called
moveInSquare to handle mouse clicks in the board. When a player makes a move
in the Tic Tac Toe applicaiton by clicking on a square, the client uses
XmlHttpRequest to send a HTTP
POST message to the application with the
Validating and sending the new game state
Use an HTTP request to send messages from the client to the server. In this
example, when the server receives the client's message via an HTTP request, it
first uses its request handler to validate the move. Then, if the move is
legal, the server uses the
method to send messages indicating the new state of the board to both clients.
In the code sample below, the
MovePage RequestHandler is called in response to
the client's HTTP
POST in the
sendMessage call above. This handler is
responsible for validating the move and broadcasting the new board state to the
GameFromRequest class uses the
gamekey parameter on the HTTP
retrieve the current game.
GameUpdater class checks that the move is valid and, if it is, uses the
channel.send_message method to send updates to the clients informing them of
the new state.
Tracking client connections and disconnections
Applications can request to be notified when a client connects to or disconnects from a channel.
You can enable this inbound service in
inbound_services: - channel_presence
When you enable
channel_presence, your application receives HTTP
requests to the following URL paths:
/_ah/channel/connected/signal that the client has connected to the channel and can receive messages.
/_ah/channel/disconnected/signal that the client has disconnected from the channel.
Your application can register handlers to these paths in order to receive notifications. You can use these notifications to track which clients are currently connected.
"from" parameter in the HTTP
POST request identifies the
used to create the channel whose presence has changed.
# In the handler for _ah/channel/connected/ client_id = self.request.get('from')
Tokens and security
Treat the token returned by
create_channel() as a secret. If a malicious application gains access to the token, it could listen to messages sent along the channel you are using. Avoid using the token in a URL request because a malicious website could see it in their referrer logs.
By default, tokens expire in two hours, unless you
explicitly set an expiration time by providing the
create_channel() function when generating the token. If a
client remains connected to a channel for longer than the token duration, the
onclose() callbacks are called. At this point, the
client can make an XHR request to the application to request a new token and
open a new channel.
One client per client ID
Only one client at a time can connect to a channel using a given client ID, so an application cannot use a client ID for fan-out. In other words, it's not possible to create a central client ID for connections to multiple clients. For example, you can't create a client ID for something like a "global-high-scores" channel and use it to broadcast to multiple game clients.
One client per channel per page
A client can only connect to one channel per page. If an application needs to
send multiple types of data to a client, aggregate it on the server side and
send it to appropriate handlers in the client's