How to adapt HTML5 games to be published on Telegram

The Announcement

On October 3rd, Telegram published its gaming platform. Now, the bots are able to launch HTML5 games inside Telegram and share your score with your friends. @gamebot and @gamee were the two first bots announced and Ludei is not going to be the last when it comes to HTML5.

The Rules

When creating a game with @BotFather, he will make you accept a series of rules:

  1. You will not implement any ads or any external links on your custom URL pages.
  2. You will not invite users to pay for any services provided on custom URL pages.
  3. You will not use any data collected over the course of user interaction with your custom URLs for spamming Telegram users.
  4. You will not transfer any Telegram data collected over the course of user interaction with your custom URLs to any third parties.
  5. In order to protect the privacy of Telegram users, your custom URL pages must not set any cookies.

Now, those are some serious rules that made us change some things in our games.

Due to these rules we had to remove every way of promoting the rest of our games and every social media integration like Twitter or Facebook. Thankfully, we didn’t collect any information for third parties neither used cookies in our games -removing all that sounds like a headache.

Game Rules by @BotFather

Game rules by @BotFather

Sharing the games

The first thing you notice when reading the technical post is the script you have to include inside your games. It is a rather short script. This is because launching a game inside Telegram means opening a URL, provided by our bot, in the webview of Telegram. Our game should need hardly any changes.

<script src="https://telegram.org/js/games.js"></script>

This script provides us with the TelegramGameProxy.shareScore() method, which is used to share the game (but not a score, weird) with Telegram chats. It works like the usual share button in Telegram, there is no complexity with this part. We added a button with the shareScore() function at the result screen of each game in case you don’t know what to do with it.

Sending scores

The name “shareScore“ is quite confusing since you can’t even pass it a parameter to share. To actually send a score you should also read our post about a game bot creation. The game must send the score to the bot (with a HTTP POST, in our case) and the bot is responsible of notifying Telegram of our score. But how does the bot know who we are when it receives it? We solved this problem sending along the score a number of identifiers the bot previously added to the URL of the page. These identifiers are always userId (identifies the user) and either inlineId (if the bot was summoned with an inline call), or the pair chatId and messageId. The necessary ones are in the request Telegram sends to our bot when a user taps the play button.

Update scores in Telegram

@ludeiBot updates scores in Telegram

To sum it up: the user activates the play button, Telegram asks our bot for a URL to open and sends the identifications of the user, the bot returns a URL containing those identifiers in a query, and finally, our game can send the score and the identifiers of the user so the bot can update the rankings.

Detecting Telegram

At this point we have a game that can be published to Telegram, but why would we use two versions of the source code of our game? We still want to be able to promote our games if the user plays at ludei.net. If we can know when the game is executing as a Telegram game we can serve it from its original server to Telegram. Any special change we made for Telegram just has to follow a condition.

At first we tried checking window.TelegramWebviewProxy !== undefined  (like Telegram does in its script), but somehow TelegramWebviewProxy is undefined even inside the Telegram webview, so in the end, we just check if the URL contains the identifiers of Telegram our bot adds. In our case the identifiers were query parameters because our games already had a method to parse them. Although they could have been hash parameter too; Telegram exposes an object containing them.

Testing your game

The last thing to do is testing. Most of the testing can be done easily like with any web page development: set up a local server and open the URL in your devices. But we found some resolution problems when Telegram launched the games. Some elements appeared several times larger than when using a typical browser app. Therefore, one last advice from us is to create a minimal test bot, capable of just launching the games, enough to be able to fix any bug that might appear only in Telegram.

Our games

Check out our games (please open the following links on your mobile device):

CocoonJS CLI now with live reload

At Ludei coding never stops, and today, we’d like to introduce to you the new feature we’ve added to our CocoonJS Command Line Interface: live reload.

We are javascript developers too and we’re aware of the need of being productive. We realized we needed a faster way to iterate over our JS code, so why not include the live reload capability to our CLI?

For those who don’t know what live reload is, this feature reloads automatically the code of your app inside the connected browsers each time you save your changes. This way you forget about saving, going to the launcher, and refreshing the content to see the changes every time.

How do I benefit from this new feature?

First of all you must update your cocoonjs-cli version. You can find more information about our CLI here.
sudo npm install -g cocoonjs
Then, you can create a new project, as always:
$ cocoonjs create MyProject com.ludei.test LudeiTest
$ cd MyProject
$ cocoonjs platform add android
$ cocoonjs serve

You’ll read a message like this one:

[CocoonJS] Executing command 'serve'
[CocoonJS] A 'cordova prepare' is needed before executing 'cordova serve'.
[CocoonJS] Command 'cordova prepare' executed correctly.


[CocoonJS] Static file server running on port 8070 (i.e. http://192.168.0.43:8070)
[CocoonJS] Path: /Volumes/data/hello-world
[CocoonJS] CTRL + C to shut down

Now, open a launcher an point to that web address. In our case http://172.16.100.43:8070. You’ll find the default main page. Also, if you are working in the same machine where the command was executed, you can point to the loopback/localhost interface (127.0.0.1).

Open the contents of the www folder with your code editor, and edit them. Each time you save the code, the launcher will refresh with the new content!

The video below is a good demo.

We hope you’ll love it!

CocoonJS Announces the WebView+ for iOS 8: Publish WKWebView Powered Standalone Apps

Apple’s new iOS version 8 announcement brought many good news for the HTML5 developer community. Safari has improved much (it now supports WebGL for example, yay!) and the system webview now comes in two different flavors: UIWebView and WKWebView. The main difference is related to the JIT optimization for JavaScript. To put it in plain words: the execution speed for JavaScript code is orders of magnitude faster using a JIT compiler and thus, your web app may run much faster inside the new WKWebView than in our older friend the UIWebView. To know more about the WKWebView and to have a glimps of the performance improvements, please, check the following great article by Sencha or check our own tests below.

At Ludei, we immediately started playing around with the WKWebView as we were eager to provide it along with all the great runtime environments we have (Canvas+, WebView and WebView+ for Android). But there was a catch. At least in the current version of iOS, there is no way of deploying a native hybrid HTML5 app using the WKWebView that has access to local files, something that is quite common on Hybrid apps to be able to execute them off-line. But Ludei has always loved a good challenge and we decided to solve the problem and make the WKWebView available to every developer that would like to use it.

Today, we are happy to announce that we have added a way to create WKWebView based completely standalone hybrid applications for iOS 8 in our CocoonJS Cloud Compiler System version 2.1. As far as we know, no other technology allows to publicly create completely offline WKWebView based apps at the moment. We have decided to call the WKWebView based runtime environment: WebView+ on iOS 8. We will still provide Canvas+ and the regular UIWebView, but every CocoonJS developer that wants to take advantage of the WKWebView, is able to do it right now. Whenever the application is running on an iOS version lower than 8.0 where the WKWebView is not available, there will be a fallback to the UIWebView.

We have also added this shiny new WebView+ for iOS inside our CocoonJS Launcher that is still in review by Apple. Meanwhile, if you want to check the awesome performance that it provides, you can build a Custom CocoonJS Launcher using our cloud.

ADDITIONAL NOTE: We are working hard to add the WebView+ to the CocoonJS CLI too! Stay tuned!

WebView+ Vs WebView on iOS 8

We have performed some tests ourselves to check how much of a better option the WKWebView (CocoonJS WebView+ for iOS 8) is compared to the UIWebView (CocoonJS WebView). These are the results:

Canvas intensive operations

All the test were executed on a iPad Air iOS 8.0.2

First test

2000 sprites rotation + translation with sprite animation rotation and random colored vertices

  • Webview+ : 30 FPS stable
  • System Webview: 6 FPS stable

Second test

3000 sprites Rotation + translation. Using 3 framebuffers. Transparency and tint with custom shader and custom clip area

  • Webview+: 20 FPS stable
  • System Webview: 4 FPS with unstable frame timing

Third test

5000 sprites 32×32 using rotation + translation, tinted vertices and MipMap

  • Webview+ 17 FPS stable
  • System Webview: 3FPS with a frame timing between 379 and 400ms

Tests with well known benchmarks

All the test were executed on a iPhone 5 running iOS 8.0.2

Octane 2.0

Octane 2.0: is the javascript benchmark from the v8 team. Lets see the differences between webview+ and webview. The higher the mark, the better.

Octane test Webview+ Webview
Richards 2712 117
Deltablue 2834 125
Crypto 3491 203
Raytrace 3474 365
EarleyBoyer 5118 636
Regexp 382 42,5
Splay 2384 605
SplayLatency 1641 2101
NavierStrokes 3455 323
pdf.js 3025 1006
Mandreel 2407 118
MandreelLatency 1784 702
GB emulator 4593 943
CodeLoad 5315 3912
Box2DWeb 2806 689
zlib 4675 N/A
Typescript 4363 N/A
Octane Score 2819 N/A

N/A means that the benchmark stops or freezes the the device.

Wirple BMark

This is test for webGL performance. The higher the score, the better.

Test Name Webview+ Webview
Canvas test1 61 26
Canvas test 2 38 10
WebGL test 1 17 7
WebGL test 2 14 7
Total score 130 50

Of course, some screenshots of the results 😉

The webview+’s results on Wirple BMark

Screen Shot 2014-10-22 at 18.34.00

The system webview after running Wirple BMark

Screen Shot 2014-10-22 at 18.34.14