Replay sharing

Replay sharing made easy

Sc2gears has a "Share replay" feature which allows the users to upload any number of StarCraft II replays to a selected replay site in one step or one by one.

You can simply choose "Share replays..." from the File menu and select the replays you want to share. The "Share replays..." is also part of the replay operations menu item: you can right click on any replays in the replay list of a replay search or right click on the charts in the Replay analyzer, and choose "Share replays".

On the "Share replays" dialog you can provide basic information about the replay (like the replay name, description), you can choose a replay site to upload to, and you can provide authentication info (user name and password) if the selected replay site requires it. That's all. Press the "Upload" button, and you get back the link where your replay is shared right away.

Sc2gears automatically manages your replay sharing history. To view it, click "My shared replays" in the File menu. You get assistance to copy the replay links in different formats or you can visit the replay link.

How to add your replay site to the list inside Sc2gears

First you have to implement the replay upload specification described below to be able to receive replays from Sc2gears. Once you're done with it, contact me via email (email address:

), send me the details (name of your site, where can your service be reached, the logo of your site). Once your interface has been tested (and passed the tests), your site will be added to Sc2gears.

Google Ads

Sc2gears replay upload specification

The following information is intended for replay site admins and developers.

Sc2gears performs an HTTP POST operation to a replay server which implements this specification. The server handles the POST operation, stores the replay, and sends back a simple XML document which explains the success of the operation and provides additional information.

The content of the replay is also attached to the HTML form for easier processing (no multi-part request).

Sc2gears submits an HTML form with a POST action containing the authentication info, the replay meta-data and the replay itself.

Included parameters:

• • requestVersion: indication of the upload request version (1.0 for now)

  • fileName: name of the replay file

  • fileSize: size of the (original) file in bytes

  • description: description of the replay

  • userName: optional name of the user if the server requires authentication

  • password: optional password of the user if the server requires authentication

  • fileMd5: MD5 digest of the (original) file (use this link to calculate MD5 digest of test replays: MD5 calculator)

  • fileContent: the Base-64 encoded form of the replay file (use this link to convert test replays to Base64: Base64 encoder)

It is up to the replay sites whether they require or use the listed parameters.

Example replay upload request:

Example replay upload request:

Standard HTML FORM request parameters that will be available on server side: (File content is truncated for readability.)

• • requestVersion=1.0

  • fileName=2010-11-17 PvP Caverne xe U DiViNo.SC2Replay

  • fileSize=3659

  • description=Short game.

  • userName=someUserName

  • password=somePassword

  • fileMd5=8c17c86b7e0849828c32a0298a8dcaa2

  • fileContent=TVBRGwACAAAABAAAOwAA...Jo/zWOgLEXA=

These parameters will be encoded propery in the HTTP request body: (The order of the parameters is arbitrary; the file content is truncated for readability.)

fileSize=3659&fileMd5=8c17c86b7e0849828c32a0298a8dcaa2&description=Short+game.&fileName=2010-11-17+PvP+Caverne+xe+U+DiViNo.SC2Replay&userName=someUserName&fileContent=TVBRGwACAAAABAAAOwAA...Jo%2FzWOgLEXA%3D&password=somePassword&requestVersion=1.0

The server should send an XML response after it received and processed the request.

Information to be included:

• • docVersion: version of the response document (1.0 for now)

  • errorCode: a numeric code for the success or failure of the upload process; 0 means no error; any non-zero value indicates that an error occurred

  • message: a human readable message

  • replayUrl: URL where the uploaded replay can be viewed/downloaded

All the listed parameters are mandatory. If the replay upload failed, the replayUrl parameter might not be used. If the replay upload succeeds, the message parameter might not be used.

A simple example of the sever response:

Example server response:

<?xml version="1.0" encoding="UTF-8"?>

<uploadResult docVersion="1.0">

<errorCode>0</errorCode> <!-- 0 means no error -->

<message>Upload OK.</message>

<replayUrl>http://some.host.com/replay?id=1234</replayUrl>

</uploadResult>

In summary, the server only needs to implement handling a simple HTML form POST. Every server side technology supports that. The parameters are sent as normal URL encoded form parameters (you don't have to care about this: the server side technologies handle these for you and you get the encoded parameter values back). You get the binary data of the replay if you decode the included Base64 string representation of the replay. There are Base64 utilities for all platforms, you can read more about Base64 here: Base64 on Wikipedia. The provided MD5 value and the file size parameters should be checked.

The response is a very simple XML document, which is also supported by almost all technologies. But you don't even need an XML library, you can assemble the XML yourself (XML is a simple text format).

Sc2gears posts the HTML form using UTF-8 encoding, and the server also has to use UTF-8 encoding for the response.

Recommendations

The replay sites should follow these recommendations:

• • If a replay site supports anonymous upload and the user provides invalid user name or password, the server should not store the replay as anonymous upload but rather send back a response providing an error code and error message indicating the invalid user name/password. The reason for this is because if the user provided authentication info it is likely he/she has an account and he/she wants the replay stored with that account and not as an anonymous upload.

  • If the replay being sent has been uploaded previously, the server should indicate a successful upload and providing URL to the existing replay in the replayUrl parameter.

  • The provided replay MD5 and file size parameters should be checked on the decoded replay on server side to ensure the file was transferred properly.

Tips

• • If you need some fix extra parameters (for example if you use the same service for multiple cases and you want to distinguish the clients), you can provide the service URL with the extra parameters appended.

  • If your service can be reached at: http://some.host.com/replayUpload

  • Then you can provide the following URL: http://some.host.com/repUpload?source=Sc2gears

• The feature is called "replay sharing" therefore there is no option to indicate private/public upload. But if you want to implement a private sharing, your users can add a Custom replay site (in the Miscellaneous settings dialog), where you can provide a different upload URL for them, and if they share the replay to this custom site, you would store the replays as private. The different URL might differ only in a parameter (like http://some.host.com/repUpload?private=true).

• Sc2gears supports sharing multiple replays at once. If multiple replays are shared, they will be uploaded one-by-one, one after another. If your site is under heavy load or cannot process the replays fast enough, you can delay the response of the replay upload (wait a few seconds before you send back the XML response) that way the next replay upload will be delayed as well (Sc2gears will not start the next upload until the current one is finished).