Repository files navigation

Easy Google Analytics event tracking for all your PICO-8 games.

It's very important to understand what's going on in your games and how players actually play your game. With this simple integration you can use Google Analytics with all your PICO-8 games (HTML export version) and track events according to your reporting needs.

1. Add the code fromevent.lua to your PICO-8 source code. This will expose theevent() function for tracking. The code uses 144 tokens in PICO-8.

2. Add a Google Analytics snippet to your exported game HTML file, refer to thislink.

Note: The snippet should be placed near the top of the head section and should look like the one inexample-analytics-snippet.js. Don't forget to enter your personal tracking ID of your analytics property.

3. Find the game's<script> tag in the exported HTML file with the form:

<scriptasynctype="text/javascript"src="game_title.js"></script>

and add the script frompico8-google-analytics.js right before it.

You can check outexample.html for a working example (add a tracking ID to test with your Analytics account).

Having added the code fromevent.lua to your game will expose a singleevent() function which can be used like this:

API:event(category,action,label?,value?)examples:event('got item','pick-axe')event('level 12','clear','found treasure')event('level 1','win','perfect',64)

Theevent() function is modelled after the Google Analytics send event method, i.e. event category and action are required and event label and value are optional.

• The data to be sent via theevent() function cannot exceed 128 bytes.
• Obviously, event tracking will only work with the HTML version of your games.
• If you host your game on pages like itch.io (i.e. where your game is embedded via iFrame) you should:
  • set the cookie option of the analytics snippet to 'none' (as inexample-analytics-snippet.js.
  • use a separate Google Analytics property, because otherwise you will get a duplicate user count from your itch game page (if you use tracking there) and the actual iFrame of the game.
  • be aware that with some browsers (Safari) tracking via an embedded iFrame might not work.

• Testing from a local html file (e.g. your-game.html) won't work since Google Analytics will block such requests.
• Instead, either
  • upload the game files to a server (or itch page) and test from there
  • or run a local webserver. A simple solution can belocal-web-server (installed via npm).
• You can use this excellentGoogle Analytics Debugger with Google Chrome to check for problems with your analytics snippet and to see if the event hits are fired correctly.Here is a short video of the example cart with the Analytics Debugger in action.

You can use theissue tracker for feedback and requests.