Create a Custom Client

Union Platform is designed to allow you, the developer, to create custom clients using any programming language that has TCP/IP socket or HTTP request capabilities, such as Java, Objective C, Python, C#, and C++.

To create a custom client application in the language of your choice, implement the Union client/server handshake, then communicate with the server using the set of commands defined by the UPC protocol (the XML-based message format used by Union clients to communicate with the Union server). The steps below describe process in detail.

If you make a custom client and would like to list it on unionplatform.com for others to use, please let us know!

Step 1. Connect to Union Server

Connect your client to Union Server using either a TCP/IP socket or HTTP.

TCP/IP Socket Connections

If you connect to Union Server with a socket, transmit your messages as UTF-8 encoded strings. Each transmission must contain one or more messages, and must be terminated by a null character (ASCII 0).

HTTP Connections

Union's HTTP implementation uses three HTTP request modes, as follows:

  • Mode "d":

    In mode "d", the HTTP request sends messages to the server, and also receives messages in the HTTP response. Mode "d" is used in one case only: to send the client's first message to the server, which is known as the "client hello" (u65 in UPC Protocol specification).

  • Mode "s":

    In mode "s", the HTTP request sends data to the server, and immediately receives an empty HTTP response. Mode "s" is used to send messages from the client to the server, such as a request to join a room.

  • Mode "c":

    In mode "c", the client opens an HTTP request, but sends no data to the server. Instead, the server holds the request open until it has messages to deliver to the client. In traditional terms, mode "c" is a "long poll". Mode "c" is used to send messages from the server to the client, such as the result of an attempt to join a room.

Client Hello

A custom client that communicates using HTTP must send an initial "client hello" (u65) using an HTTP POST with the following parameters:

  • Name: mode
    Value: d
  • Name: data
    Value: A URI-encoded u65 message

The server's response (a u66 message) will contain a session id that must be included in all future requests.

Here is an example client hello HTTP Request:

POST / HTTP/1.1
Host: user1.net:10100
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-us) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19
Content-Type: text/plain;charset=UTF-8
Referer: http://tryunion.com:80/orbiter
Origin: http://tryunion.com:80
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Content-Length: 327
Connection: keep-alive

mode=d&data=%3CU%3E%3CM%3Eu65%3C%2FM%3E%3CL%3E%3CA%3EOrbiterMicro%3C%2FA%3E%3CA%3EMozilla%2F5.0%20(Macintosh%3B%20U%3B%20Intel%20Mac%20OS%20X%2010_5_8%3B%20en-us)%20AppleWebKit%2F530.19.2%20(KHTML%2C%20like%20Gecko)%20Version%2F4.0.2%20Safari%2F530.19%3B1.0.0%20(Build%20363)%3C%2FA%3E%3CA%3E1.9.1%3C%2FA%3E%3C%2FL%3E%3C%2FU%3E

Client-to-Server Messages

To send UPC messages to the server, the client must open an HTTP POST request with the following parameters.

  • Name: mode
    Value: s
  • Name: rid
    Value: A sequential integer uniquely identifying the request among all mode "s" requests
  • Name: sid
    Value: The session id delivered to the client in the server's hello (u66) message
  • Name: data
    Value: One or more URI-encoded, UPC-formatted messages

A response with HTTP status 200 (OK) indicates that the server received the message.

Here is an example client-to-server HTTP Request:

POST / HTTP/1.1
Host: user1.net:10100
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-us) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19
Content-Type: text/plain;charset=UTF-8
Referer: http://tryunion.com:80/orbiter
Origin: http://tryunion.com:80
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Content-Length: 148
Connection: keep-alive

rid=1&sid=-14017638719a31704-b279-4bb9-81fa-db8fbb69ff75&mode=s&data=%3CU%3E%3CM%3Eu24%3C%2FM%3E%3CL%3E%3CA%3EchatRoom%3C%2FA%3E%3C%2FL%3E%3C%2FU%3E

Server-to-Client Messages

To receive UPC messages from the server, the client must open an HTTP POST request with the following parameters.

  • Name: mode
    Value: c
  • Name: rid
    Value: A sequential integer uniquely identifying the request among all mode "c" requests
  • Name: sid
    Value: The session id delivered to the client in the server's hello (u66) message

When the server has messages to deliver, it will send a response with HTTP status 200 (OK), and an HTTP body containing the messages, encoded as a UTF-8 string. Upon receiving the response, the client must open a new HTTP POST request with the preceding parameters. That is, the client must maintain an open mode "c" request at all times, otherwise the server will have no way to send messages to the client.

Here is an example server-to-client HTTP Request:

POST / HTTP/1.1
Host: user1.net:10100
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-us) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19
Content-Type: text/plain;charset=UTF-8
Referer: http://tryunion.com:80/orbiter
Origin: http://tryunion.com:80
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Content-Length: 63
Connection: keep-alive

rid=1&sid=-14017638719a31704-b279-4bb9-81fa-db8fbb69ff75&mode=c

Retry on HTTP Failure

If any HTTP request fails, it should be resent using the same request ID. The request ID is typically a simple incremented integer.

HTTP Heartbeat

In order to prevent the client's session from expiring, the client must send the server at least one message every client_timeout milliseconds, where client_timeout is the server's configurable session timeout, specified in Union Server's union.xml file.

Step 2. Implement the Union Handshake

When a Union client connects to Union server, it transmits and receives a standard set of UPC messages known as the Union handshake. The Union handshake sets up the client by assigning its initial attributes, client ID, and session ID. Your custom client must implement the Union Handshake according to the Union Handshake documentation.

Step 3. Send and Receive UPC Messages

Once your client has connected and completed the Union Handshake, it can communicate with the server using XML-based UPC messages. Each message has a message ID (specified in the tag ) and list of parameters (specified in the tag ). For example, here's a UPC-formatted message showing a client request to join a room named "Meeting1":

<U><M>u4</M><L><A>examples.chat</A><A></A></L></U>

For a complete list of available UPC messages consult the Union Protocol specification.

Happy multiuser coding!