Better support for handling quit events for web and mobile games.

Author: agmathew

README.md

@@ -1,4 +1,5 @@
 
+
 # Quiver Analytics
 [Quiver Analytics](https://quiver.dev/analytics/) allows you to collect analytics for games made with the [Godot engine](https://godotengine.org) in a privacy-friendly way. In just a few minutes, you can integrate Analytics in your game through this open source plugin and gain valuable insight into how players are interacting with your game. You also have fine-grained control over how your players' privacy is handled.
 
@@ -36,44 +37,48 @@ By default, player consent isn't required for anonymous data collection, but if
 
 ### Cleaning up before exiting the game
 
-Before you quit the game, you have to tell the plugin to send a configurable "Quit game event" and flush any outstanding events. To do that, write this code anywhere you are exiting the game:
+Before you quit the game, you can tell the plugin to send a configurable "Quit game" event and flush any outstanding events. To do that, write this code anywhere you are exiting the game:
 
 `await Analytics.handle_exit()`
 
 Note that SceneTree.quit() will immediately exit the game so you want to make sure you wait for the above call to finish before calling the quit() function.
 
+#### _Note for web and mobile games:_
+
+If you are developing a web or mobile game, it might be difficult to call `handle_exit()` since you don't always have the option to run operations when a player backgrounds the app or closes the tab. To work around this, we have added some special logic to automatically add 'Quit game' events. Note that the timing of this event is an estimate and might be up to a minute off the actual quit time. 
+
 ## Advanced Usage
 The following is not required, but you do have additional functionality if you need it.
 
 ### Managing consent
 
 By default, the plugin won't ask for consent since no personally-identifying information is collected. However, you can enable opt-in data collection by going to Project Settings -> Quiver -> Analytics and set "Player Consent Required" to true. Now calls to `add_event()` will be ignored until you obtain consent. To manage consent, you can either use the built-in UI:
 
-    if Analytics.should_show_consent_dialog():
-      Analytics.show_consent_dialog(parent_node)
+	if Analytics.should_show_consent_dialog():
+	  Analytics.show_consent_dialog(parent_node)
 
  This will decide whether consent has already been granted or denied and, if not, will spawn a consent dialog as a child of the parent_node.
 
 If you'd like to use your own UI and manually handle consent management, you can use the following functions:
 
-    # Variable storing whether consent has been requested
-    Analytics.consent_requested
-    # Variable storing consent status
-    Analytics.consent_granted
-    # Function to call if consent was granted
-    Analytics.approve_data_collection()
-    # Function to call if consent was denied
-    Analytics.deny_data_collection()
+	# Variable storing whether consent has been requested
+	Analytics.consent_requested
+	# Variable storing consent status
+	Analytics.consent_granted
+	# Function to call if consent was granted
+	Analytics.approve_data_collection()
+	# Function to call if consent was denied
+	Analytics.deny_data_collection()
 
 ### Customizing consent UI
 By default, the built-in consent UI will use whatever UI theme that has been set for your project. You can modify this by changing the properties of the ConsentDialog found in `/addons/quiver_analytics/consent_dialog.tscn`.
 
 ### Advanced Properties
 If you turn on Advanced Settings for Project Settings -> Quiver -> Analytics, you'll find the following properties:
 
-Config File Path: where the config file is stored
-Auto Add Event on Launch: whether a "Launched game" event is sent automatically when the game starts
-Auto Add Event on Quit: whether a "Quit game" event is sent automatically after calling the `Analytics.handle_exit()` function.
+* "Config File Path": where the config file is stored
+* "Auto Add Event on Launch": whether a "Launched game" event is sent automatically when the game starts
+* "Auto Add Event on Quit": whether a "Quit game" event is sent automatically.
 
 ### Notes and Limitations
 

addons/quiver_analytics/analytics.gd

@@ -15,19 +15,18 @@ extends Node
 ## Use this to pick a random player identifier
 const MAX_INT := 9223372036854775807
 
-## The maximum rate of requests we can send to the server per minute.
-## If this limit is exceeded, requests will be dropped
-const MAX_REQUEST_RATE_PER_MINUTE := 50
+## The maximum rate we can add events to the queue.
+## If this limit is exceeded, requests will be dropped.
+const MAX_ADD_TO_EVENT_QUEUE_RATE := 50
 
 ## This controls the maximum size of the request queue that is saved to disk
-## in the situation the events weren't able to 
-## In pathological cases, we may 
+## in the situation the events weren't able to be successfully sent
+## In pathological cases, we may drop events if the queue grows too long.
 const MAX_QUEUE_SIZE_TO_SAVE_TO_DISK := 200
 
 ## The file to store queue events that weren't able to be sent due to network or server issues
 const QUEUE_FILE_NAME := "user://analytics_queue"
 
-# XXX TODO CHANGEME
 ## The server host
 const SERVER_PATH := "https://quiver.dev"
 
@@ -37,6 +36,18 @@ const ADD_EVENT_PATH := "/analytics/events/add/"
 ## Event names can't exceed this length
 const MAX_EVENT_NAME_LENGTH := 50
 
+# The next two parameters guide how often we send artifical quit events.
+# We send these fake quit events because on certain platfomrms (mobile and web),
+# it can be hard to determine when a player ended the game (e.g. they background the app or close a tab).
+# So we just send periodic quit events with session IDs, which are reconciled by the server.
+
+# We send a quit event this many seconds after launching the game. 
+# We set this fairly low to handle immediate bounces from the game.
+const INITIAL_QUIT_EVENT_INTERVAL_SECONDS := 10
+
+# This is the max interval between sending quit events
+const MAX_QUIT_EVENT_INTERVAL_SECONDS := 60
+
 ## Emitted when the sending the final events have been completed
 signal exit_handled
 
@@ -61,10 +72,12 @@ var current_retry_time_seconds := min_retry_time_seconds
 var max_retry_time_seconds := 120.0
 var auto_add_event_on_launch := ProjectSettings.get_setting("quiver/analytics/auto_add_event_on_launch", true)
 var auto_add_event_on_quit := ProjectSettings.get_setting("quiver/analytics/auto_add_event_on_quit", true)
+var quit_event_interval_seconds := INITIAL_QUIT_EVENT_INTERVAL_SECONDS
+var session_id = abs(randi() << 32 | randi())
 
 @onready var http_request := $HTTPRequest
 @onready var retry_timer := $RetryTimer
-
+@onready var quit_event_timer := $QuitEventTimer
 
 func _ready() -> void:
 	# We attempt to load the saved configuration, if present
@@ -96,6 +109,8 @@ func _ready() -> void:
 
 	if auto_add_event_on_launch:
 		add_event("Launched game")
+	if auto_add_event_on_quit:
+		quit_event_timer.start(quit_event_interval_seconds)
 
 #	if auto_add_event_on_quit:
 #		get_tree().set_auto_accept_quit(false)
@@ -156,12 +171,13 @@ func add_event(name: String, properties: Dictionary = {}) -> void:
 		requests_in_batch_count = 0
 	else:
 		requests_in_batch_count += 1
-	if requests_in_batch_count > MAX_REQUEST_RATE_PER_MINUTE:
+	if requests_in_batch_count > MAX_ADD_TO_EVENT_QUEUE_RATE:
 		printerr("[Quiver Analytics] Event tracking was disabled temporarily because max event rate was exceeded.")
 		return
 
 	# Auto-add the platform
 	properties["$platform"] = OS.get_name()
+	properties["$session_id"] = session_id
 
 	# Add the request to the queue and process the queue
 	var request := {
@@ -273,6 +289,11 @@ func _on_retry_timer_timeout() -> void:
 	_process_requests()
 
 
+func _on_quit_event_timer_timeout() -> void:
+	add_event("Quit game")
+	quit_event_interval_seconds = min(quit_event_interval_seconds + 10, MAX_QUIT_EVENT_INTERVAL_SECONDS)
+	quit_event_timer.start(quit_event_interval_seconds)
+
 #func _notification(what):
 #	if what == NOTIFICATION_WM_CLOSE_REQUEST:
 #		handle_exit()

addons/quiver_analytics/analytics.tscn

@@ -12,5 +12,8 @@ timeout = 5.0
 [node name="RetryTimer" type="Timer" parent="."]
 one_shot = true
 
+[node name="QuitEventTimer" type="Timer" parent="."]
+
 [connection signal="request_completed" from="HTTPRequest" to="." method="_on_http_request_request_completed"]
 [connection signal="timeout" from="RetryTimer" to="." method="_on_retry_timer_timeout"]
+[connection signal="timeout" from="QuitEventTimer" to="." method="_on_quit_event_timer_timeout"]

addons/quiver_analytics/plugin.cfg

@@ -3,5 +3,5 @@
 name="Quiver Analytics"
 description="Get key insights into how players are interacting with your game while still respecting their privacy."
 author="Quiver"
-version="0.1"
+version="0.2"
 script="plugin.gd"