{"id":15723216,"url":"https://github.com/britzl/defold-googleanalytics","last_synced_at":"2025-10-23T19:59:00.123Z","repository":{"id":46168985,"uuid":"74751671","full_name":"britzl/defold-googleanalytics","owner":"britzl","description":"Google Analytics implementation for the Defold game engine","archived":false,"fork":false,"pushed_at":"2022-10-16T20:48:42.000Z","size":2176,"stargazers_count":21,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-20T22:32:36.599Z","etag":null,"topics":["defold","defold-library","google-analytics","lua"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/britzl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-25T11:07:18.000Z","updated_at":"2024-08-31T10:30:23.000Z","dependencies_parsed_at":"2023-01-20T04:33:52.957Z","dependency_job_id":null,"html_url":"https://github.com/britzl/defold-googleanalytics","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fdefold-googleanalytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fdefold-googleanalytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fdefold-googleanalytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fdefold-googleanalytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/britzl","download_url":"https://codeload.github.com/britzl/defold-googleanalytics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253870863,"owners_count":21976613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-library","google-analytics","lua"],"created_at":"2024-10-03T22:10:43.093Z","updated_at":"2025-10-23T19:58:59.453Z","avatar_url":"https://github.com/britzl.png","language":"Lua","readme":"![](logo.png)\n\n[![Build Status](https://travis-ci.org/britzl/defold-googleanalytics.svg?branch=master)](https://travis-ci.org/britzl/defold-googleanalytics)\n\n# Google Analytics for Defold\nThis is a Lua implementation of [Google Analytics](https://www.google.com/analytics) for the [Defold game engine](http://www.defold.com). The project is provided as a Defold library project for easy integration into Defold games. The implementation is loosely based on the design of the Google Analytics Android SDK, but with several simplifications thanks to the dynamic and flexible nature of Lua.\n\nThis Lua implementation uses the [Google Analytics Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/v1/) to make direct calls to the Google Analytics servers. On top of these raw calls the implementation also adds support for offline tracking, automatic crash/exception reporting and automatic retrieval of relevant tracking parameters such as app name, app id, language, screen resolution and so on.\n\n## Installation\nYou can use Google Analytics in your own project by adding this project as a [Defold library dependency](http://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add:\n\n\thttps://github.com/britzl/defold-googleanalytics/archive/master.zip\n\nOr point to the ZIP file of a [specific release](https://github.com/britzl/defold-googleanalytics/releases).\n\n## Configuration\nBefore you can use Google Analytics in your project you need to add your analytics tracking ID to game.project (`*`). Open game.project as a text file and create a new section:\n\n\t[googleanalytics]\n\ttracking_id = UA-1234567-1\n\nAdditional optional values are:\n\n\t[googleanalytics]\n\tdispatch_period = 1800\n\tqueue_save_period = 60\n\tverbose = 1\n\n`dispatch_period` is the interval, in seconds, at which tracking data is sent to the server.\n\n`queue_save_period` is the minimum interval, in seconds, at which tracking data is saved to disk.\n\n`verbose` set to 1 will print some additional data about when and how many hits are sent to Google Analytics. Set to 0 or omit the value to not print anything.\n\n`*` = Google has changed the way you set up analytics and now make a clear distinction between mobile apps and websites. Mobile apps should use [Firebase Analytics](https://www.github.com/defold/extension-firebase-analytics) and websites should use Google Analytics. This is actually not strictly necessary and it is possible to use Google Analytics for a mobile apps and games. To get a tracking id you need to create a web property.\n\n## Data processing latency\nKeep in mind that there is a data processing latency of one or two days which means that you will not be able to see the data you generate in your application straight away. You should be able to see data in the realtime view with only a very slight delay though. \n\nMore information: https://support.google.com/analytics/answer/1070983?hl=en\n\n## Usage\nOnce you have added your tracking ID to game.project you're all set to start sending tracking data:\n\n\tlocal ga = require \"googleanalytics.ga\"\n\n\tfunction init(self)\n\t\tga.get_default_tracker().screenview(\"my_cool_screen\")\n\tend\n\n\tfunction update(self, dt)\n\t\tga.update()\n\tend\n\n\tfunction on_input(self, action_id, action)\n\t\tif gui.pick_node(node1, action.x, action.y) and action.pressed then\n\t\t\tga.get_default_tracker().event(\"category\", \"action\")\n\t\tend\n\n\t\tif gui.pick_node(node2, action.x, action.y) and action.pressed then\n\t\t\tlocal time = socket.gettime()\n\t\t\thttp.request(\"http://d.defold.com/stable/info.json\", \"GET\", function(self, id, response)\n\t\t\t\tlocal millis = math.floor((socket.gettime() - time) * 1000)\n\t\t\t\tga.get_default_tracker().timing(\"http\", \"get\", millis)\n\t\t\tend)\n\t\tend\n\tend\n\nNote that all tracking arguments of type string will be automatically URL encoded by the library.\n\n## Supported hit types\nThis implementation supports the following hit types:\n\n* Event - `ga.get_default_tracker().event(category, action, label, value)`\n* Screen View - `ga.get_default_tracker().screenview(screen_name)`\n* Timing - `ga.get_default_tracker().timing(category, variable, time, label)`\n* Exception - `ga.get_default_tracker().exception(description, is_fatal)`, also see section on automatic crash/exception tracking\n\nYou can also register a raw hit where you specify all parameters yourself:\n\n\tga.get_default_tracker().raw(\"v=1\u0026tid=UA-123456-1\u0026cid=5555\u0026t=pageview\u0026dp=%2Fpage\")\n\nA set of base parameters such as screen dimensions, uuid, application name etc are provided in `base_params` on the tracker instance. These can be useful when creating the params for a raw hit:\n\n\tprint(ga.get_default_tracker().base_params)\n\n\tv=1\u0026ds=app\u0026cid=b80e6164-fc1f-4d76-cdae-dfb7e9a9507c\u0026tid=UA-87977671-1\u0026vp=1280x720\u0026ul=en\u0026an=Google_Analytics\u0026aid=Google_AnalyticsDarwin\u0026av=0.9\n\n## Automatic crash/exception tracking\nYou can let Google Analytics automatically send tracking data when your app crashes. The library can handle soft crashes (ie when your Lua code crashes) using [sys.set_error_handler](http://www.defold.com/ref/sys/#sys.set_error_handler:error_handler) and hard crashes (ie when the Defold engine crashes) using [crash API](http://www.defold.com/ref/crash/). Enable automatic crash tracking like this:\n\n\tlocal ga = require \"googleanalytics.ga\"\n\n\tfunction init(self)\n\t\tga.get_default_tracker().enable_crash_reporting(true)\n\tend\n\nIn order to see crashes in Google Analytics you need to [create a new Dashboard with a Table Widget](https://support.google.com/analytics/answer/1068218?hl=en) showing the `Exception Description` column and the `Exception` metric:\n\n![](analytics_exception_setup.png)\n\n## Third party tools and modules used\nThe library uses the following modules:\n\n* [json.lua by rxi](https://github.com/rxi/json.lua) (MIT License)\n* [uuid.lua by Tieske](https://github.com/Tieske/uuid) (Apache 2.0)\n* [url_encode() from Lua String Recipes](http://lua-users.org/wiki/StringRecipes)\n\nThe example project uses:\n\n* [Dirty Larry UI library](https://github.com/andsve/dirtylarry)\n* [Spineboy animation from the Spine animation tool](https://github.com/EsotericSoftware/spine-superspineboy).\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbritzl%2Fdefold-googleanalytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbritzl%2Fdefold-googleanalytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbritzl%2Fdefold-googleanalytics/lists"}