Event Tracking

GameAnalytics features the following event types:

Event	Description
Ad	Ads shown and clicked, fill rate.
Business	In-App Purchases supporting receipt validation on GA servers.
Design	Submit custom event id’s. Useful for tracking metrics specifically needed for your game.
Error	Submit exception stack traces or custom error messages.
Health	Automatically submits health metrics related to your game such as FPS.
Impression	Impression data from different ad networks
Progression	Level attempts with Start, Fail & Complete event.
Resource	Managing the flow of virtual currencies - like gems or lives

tip

Read more about events here

Business Events

Business events are used to track IAP (real money transactions inside your game). With GameAnalytics for Godot you can send events using GDScript.

GameAnalytics supports 2 types of business events:

• without store validation
• with store validation (only available for iOS and Android)

You can add a business event as shown below:

# send a business event (value in cents, e.g: 100 = $1)
gameAnalytics.addBusinessEvent("USD", 100, "gold_pack_500", "gold_premium_pack", "shop", {})

Optional arguments can be passed as a dictionary:

# set optional arguments
var optArgs = {
    "autoFetchReceipt": false, # only available for iOS
    "receipt": "add your receipt here", # if available
    "fields": JSON.stringify({"my_custom_key": "my_custom_value"}) # custom fields can be appended to the event
}

# send a business event (value in cents, e.g: 100 = $1)
gameAnalytics.addBusinessEvent("USD", 100, "gold_pack_500", "gold_premium_pack", "shop", optArgs)

Field	Type	Description	Example
currency	string	Currency code in ISO 4217 format.	USD
amount	integer	Amount in cents.	99 is 0.99$
itemType	string	The type / category of the item.	GoldPacks
itemId	string	Specific item bought.	1000GoldPack
cartType	string	The game location of the purchase. Max 10 unique values.	EndOfLevel
receipt	base64 string	Optional. The transaction receipt. Can be empty.
autoFetchReceipt	bool	Optional. Automatically fetch the receipt, available only on iOS. (no effect on other platforms)	true

tip

Find more information on Custom Event Fields and Data Export following the links.

tip

For more information about the business event go here.

Ad Events

warning

Ad events will only work on mobile platforms: iOS and Android

gameAnalytics.addAdEvent("clicked", "banner", "admob", "level_complete_ad", {})

Optional arguments can be passed as a dictionary:

var optArgs = {
    "noAdReason": "offline", # optional reason if the ad has failed to load
    "duration": 10, # ad duration in seconds
    "fields": JSON.stringify({"my_key": "my_value"}) # custom fields
}

gameAnalytics.addAdEvent("clicked", "banner", "admob", "level_complete_ad", optArgs)

Field	Type	Description	Example
adAction	enum	A defined enum for ad action (for example clicked).	clicked show failed_show reward_received
adType	enum	A defined enum for ad type (for example interstitial).	video rewarded_video playable interstitial offer_wall banner
adSdkName	string	Name of the Ad/Ad mediation SDK.	admob
adPlacement	string	Identifier of ad in the game or the placement of it.	level_complete_ad
duration	int	Optional. Only used for video ads to track how long the user watched the video for.	10
noAdReason	enum	Optional. Used to track the reason for not being able to show an ad when needed (for example no fill).	unknown offline no_fill internal_error invalid_request unable_to_precache

tip

For more information about Ad Events go here.

Impression Events

Not all Ad SDKs will offer Godot support (while support for iOS, Android and Unity is much more common).

The GameAnalytics Godot SDK does not provide explicit support for impression events. Impression events are only supported on Android and iOS platforms.

tip

For more information about the iOS impression events go here.

For more information about the Android impression events go here

tip

Read more about Impression Events here

Resource Events

Resources events are used to track your in-game economy. From setting up the event you will be able to see three types of events in the tool. Flow, the total balance from currency spent and rewarded. Sink is all currency spent on items, and lastly source, being all currency rewarded in game.

# earning in-game currency (source)
gameAnalytics.addResourceEvent("source", "gold", 100, "quest", "kill_dragon_quest", {})

# spending in-game currency (sink)
gameAnalytics.addResourceEvent("sink", "gold", 100, "shop", "fire_sword", {})

Optional arguments can be passed as a dictionary:

var optArgs = {
    "fields": JSON.stringify({"my_key": "my_value"}) # custom fields
}

gameAnalytics.addResourceEvent("source", "gold", 100, "quest", "kill_dragon_quest", optArgs)

Field	Type	Required	Description
flowType	enum	yes	Add (source) or subtract (sink) resource.
currency	string	yes	One of the available currencies set in GA_Settings (Setup tab).This string can only contain [A-Za-z] characters.
amount	float	yes	Amount sourced or sunk.
itemType	string	yes	One of the available item types set in GA_Settings (Setup tab).
itemId	string	yes	Item id (string max length = 32)

danger

Be careful to not call the resource event too often! In a game where the user collect coins fairly fast you should not call a Source event on each pickup. Instead you should count the coins and send a single Source event when the user either complete or fail the level.

tip

For more information on Resource Events go here.

Progression Events

Progression events are used to measure player progression in the game. They follow a 3 tier hierarchy structure (world, level and phase) to indicate a player’s path or place.

# send a progression event with a score value
gameAnalytics.addProgressionEventWithScore("start", "act2", "zone2", "level4", 1000)

Alternatively you can send additional optional arguments as a dictionary:

var optArgs = {
    "score": 1000,
    "fields": JSON.stringify({"my_key": "my_value"}) # custom fields
}

# append optional arguments
gameAnalytics.addProgressionEvent("start", "act2", "zone2", "level4", optArgs)

Field	Type	Required	Description
progressionStatus	enum	yes	start, complete or fail
progression01	string	yes	1st progression (e.g. world01).
progression02	string	no	2nd progression (e.g. level01).
progression03	string	no	3rd progression (e.g. phase01).
score	int	no	Score of the attempt

caution

At least progression01 must be set for such events (an empty value is not allowed).

info

Progressions need to be set in order (e.g: you cannot have only progression01 and progression03, nor progression02 and progression03, you are required to start from 01 and continue)

Error Events

Used to track custom error events in the game. This event should be used when something goes wrong inside the game's logic (also note that unhandled exceptions & crashes will be automatically sent over as error events). It is possible to group the events by severity level and attach a message.

Error events will automatically provide (if available):

• filename
• function name
• line number

gameAnalytics.addErrorEvent("critical", "Failed to load level", {})

Optional arguments can be passed as a dictionary:

var optArgs = {
    "fields": JSON.stringify({"my_key": "my_value"}) # custom fields
}

gameAnalytics.addErrorEvent("critical", "Failed to load level", optArgs)

Field	Type	Required	Description
severity	enum	yes	debug, info, warning, error or critical
message	string	yes	Custom error message

tip

Find more information on Custom Event Fields and Data Export following the links.

tip

Read more about Error Events here

Design Events

Design events are custom events that can be used to track any other type of event not found in one of the previous categories.

info

The event name is a String which can consist of 1 to 5 segments. Segments are separated by ':' and segments can have a max length of 64 characters. (e.g. "segment1:anotherSegment:gold").

gameAnalytics.addDesignEventWithValue("kill:boss:dragon", 5000)

Optional arguments can be passed as a dictionary:

var optArgs = {
    "value": 5000,
    "fields": JSON.stringify({"my_key": "my_value"}) # custom fields
}

gameAnalytics.addDesignEvent("kill:boss:dragon", optArgs)

Field	Type	Required	Description
eventId	string	yes	Event id
value	float	no	Optional custom value

tip

Find more information on Custom Event Fields and Data Export following the links.

tip

For more information on the design event go here.

Custom Fields

GameAnalytics allows you to setup up to 50 custom key-value pairs for any type of event. The following value types are supported:

• number (64-bit floating point)
• string
• boolean

All events also support passing optional arguments as a dictionary, as shown in the examples above. Custom fields must be added with a fields and in json format.

var fields = {
    "key_str": "my_string",
    "key_bool": true,
    "key_num": 5000.0
}

# add custom fields to a design events
gameAnalytics.addDesignEvent("my:design:event", {"fields": JSON.stringify(fields), "value": 1000})