Track player progression, monetization, ads, errors and custom design events from your Defold game, and change your game's behavior remotely with Remote Configs and A/B testing.
- GameAnalytics documentation for Defold
- Questions or problems: contact our support team
- What changed in each release: CHANGELOG.md
| Defold | 1.14 or newer |
| iOS | 12.0 or newer (devices and the simulator) |
| Android | 5.0 (API level 21) or newer |
| Desktop | macOS (Apple silicon and Intel), Windows (64-bit), Linux (64-bit) |
| Web | HTML5 (wasm-web) |
You need a game in your GameAnalytics account and its game key and secret key for every platform you build for.
-
Open your
game.projectand add the SDK to Project > Dependencies:https://github.com/GameAnalytics/GA-SDK-DEFOLD/archive/refs/tags/<version>.zipReplace
<version>with the release you want. -
Select Project > Fetch Libraries in the editor.
-
Add your keys to
game.project(see Configuration).
That's all: the extension starts GameAnalytics when the game starts, and the gameanalytics lua module is available in all your scripts.
Everything is set in a [gameanalytics] section of your game.project. Open the file in a text editor to add it:
[gameanalytics]
game_key_ios = <your iOS game key>
secret_key_ios = <your iOS secret key>
game_key_android = <your Android game key>
secret_key_android = <your Android secret key>
game_key_html5 = <your web game key>
secret_key_html5 = <your web secret key>
build_ios = 1.0.0
build_android = 1.0.0
build_html5 = 1.0.0
custom_dimensions_01 = ninja,samurai
resource_currencies = gold,gems
resource_item_types = boost,lives
enable_info_log = 1Each platform has its own game in GameAnalytics, so the keys and the build version are set per platform. Replace <platform> with ios, android, html5, osx, windows or linux.
| Setting | Description |
|---|---|
game_key_<platform> |
The game key of the platform's game. Required. |
secret_key_<platform> |
The secret key of the platform's game. Required. |
build_<platform> |
The build version sent with every event, e.g. 1.0.0. |
auto_detect_app_version |
1 to send the app's version (iOS, Android) as the build instead. Default 0. |
write_path_<platform> |
Desktop only (osx, windows, linux): the folder the SDK keeps its data in, instead of its default (~/GameAnalytics on macOS and Linux, %LOCALAPPDATA%\GameAnalytics on Windows). The folder must exist, the SDK only creates its own subfolder in it. $VAR, ${VAR}, %VAR% and a leading ~ are expanded, e.g. %APPDATA%/MyGame. |
Custom dimensions, resource currencies and resource item types must be declared before the SDK starts. Each setting is a comma separated list of up to 20 values.
| Setting | Used by |
|---|---|
custom_dimensions_01, custom_dimensions_02, custom_dimensions_03 |
gameanalytics.setCustomDimension01 / 02 / 03 |
resource_currencies |
the currency of resource events |
resource_item_types |
the itemType of resource events |
| Setting | Description | Default |
|---|---|---|
manual_initialize |
1 to start the SDK yourself with gameanalytics.initialize(), e.g. after asking the player for consent. |
0 |
use_custom_id |
1 to start the SDK when you set your own user id with gameanalytics.configureUserId(id). |
0 |
use_manual_session_handling |
1 to start and end sessions yourself with gameanalytics.startSession() and gameanalytics.endSession(). By default sessions follow the app going to the foreground and background. |
0 |
enable_event_submission |
0 to keep events on the device instead of sending them. |
1 |
enable_error_reporting |
1 to send an error event when the game crashes. |
0 |
enable_info_log |
1 for basic SDK logging, useful during integration. |
0 |
enable_verbose_log |
1 to also log every event and request. |
0 |
When neither manual_initialize nor use_custom_id is set, the SDK starts as soon as the game starts.
Health events report how the game performs on the players' devices: the time from launch to the SDK start, and histograms of the frame rate and memory use over the session. They are off by default and shown in GameAnalytics to Pro accounts.
| Setting | Description | Default |
|---|---|---|
enable_sdk_init_event |
1 to send the SDK init event with the app's boot time. |
0 |
enable_fps_histogram |
1 to sample the frame rate once a second and send the histogram at the end of the session. The extension measures the rate from the engine's update, values are capped at 120. |
0 |
enable_memory_histogram |
1 to sample the memory use every 5 seconds and send the histogram at the end of the session. |
0 |
enable_health_hardware_info |
1 to add the device's hardware (CPU, GPU, cores) to the health events. Experimental. |
0 |
Games with manual_initialize = 1 can also switch these at runtime with gameanalytics.enableSDKInitEvent(flag) and friends (see the API reference), before calling initialize(). On the web the four settings are one switch in the JavaScript SDK: any of them enables all health events.
Every event function takes a table of options. Calling one with a missing or wrong option raises a lua error, so mistakes show up during development.
In-app purchases. amount is in cents.
gameanalytics.addBusinessEvent({
currency = "USD",
amount = 99,
itemType = "boost",
itemId = "megaBoost",
cartType = "shop",
})currency, itemType and itemId are required. To validate the purchase, add the store receipt:
- iOS:
receipt = "<base64 receipt>", orautoFetchReceipt = trueto let the SDK read it - Android:
receipt = "<purchase data>"andsignature = "<signature>"
The flow of your in-game currencies.
gameanalytics.addResourceEvent({
flowType = "Source", -- "Source" (gained) or "Sink" (spent)
currency = "gold",
amount = 100,
itemType = "boost",
itemId = "daily_reward",
})currency, amount, itemType and itemId are required. currency and itemType must be one of the values declared in game.project, and amount must be greater than zero.
Levels, worlds and other stages of your game, with up to three levels of hierarchy.
gameanalytics.addProgressionEvent({
progressionStatus = "Complete", -- "Start", "Complete" or "Fail"
progression01 = "world1",
progression02 = "level1", -- optional
progression03 = "boss", -- optional
score = 1200, -- optional
})Anything else you want to track, as a colon separated event id with an optional value.
gameanalytics.addDesignEvent({ eventId = "tutorial:step3:completed" })
gameanalytics.addDesignEvent({ eventId = "settings:volume", value = 0.8 })gameanalytics.addErrorEvent({
severity = "Warning", -- "Debug", "Info", "Warning", "Error" or "Critical"
message = "Could not load the level data",
})gameanalytics.addAdEvent({
adAction = "Show", -- "Clicked", "Show", "FailedShow" or "RewardReceived"
adType = "Interstitial", -- "Video", "RewardedVideo", "Playable", "Interstitial", "OfferWall" or "Banner"
adSdkName = "admob",
adPlacement = "level_end",
})Add duration = <seconds> for how long a rewarded video was watched, or noAdReason for why an ad failed to show ("Unknown", "Offline", "NoFill", "InternalError", "InvalidRequest" or "UnableToPrecache").
Every event takes optional customFields, a JSON string with your own key-value pairs (strings or numbers). They are kept in the raw event data for exports.
gameanalytics.addDesignEvent({
eventId = "shop:opened",
customFields = json.encode({ source = "main_menu", coins = 120 }),
})Fields that should go with every event can be set once with gameanalytics.setGlobalCustomEventFields(json). Pass mergeFields = true with an event to combine its fields with the global ones instead of replacing them.
Segment your players, e.g. by class or by the variant of a feature they see. Each value must be declared in game.project.
gameanalytics.setCustomDimension01("ninja")Remote Configs are values you set in the GameAnalytics tool and read in your game, without releasing a new build. They are downloaded when the SDK starts.
-- called whenever the remote configs are downloaded or updated
gameanalytics.setRemoteConfigsListener(function(self)
local difficulty = gameanalytics.getRemoteConfigsValueAsNumber({ key = "difficulty", defaultValue = 1 })
local title = gameanalytics.getRemoteConfigsValueAsString({ key = "shop_title", defaultValue = "Shop" })
end)
if gameanalytics.isRemoteConfigsReady() then
-- all values as a JSON string
print(gameanalytics.getRemoteConfigsContentAsString())
endSet the listener before the SDK starts (in your first script's init, or before calling gameanalytics.initialize()) so the first download isn't missed.
When the player is part of an A/B test, gameanalytics.getABTestingId() and gameanalytics.getABTestingVariantId() return the test and the variant they are in.
gameanalytics.getUserId() -- the id GameAnalytics uses for this player
gameanalytics.setExternalUserId("1234") -- link the player to your own account system
gameanalytics.getExternalUserId()To use your own id as the GameAnalytics user id, set use_custom_id = 1 and call gameanalytics.configureUserId(id), which also starts the SDK.
| Function | Description |
|---|---|
initialize() |
Starts the SDK when manual_initialize = 1. |
configureUserId(id) |
Sets your own user id and starts the SDK when use_custom_id = 1. |
addBusinessEvent(options) |
See Business events. |
addResourceEvent(options) |
See Resource events. |
addProgressionEvent(options) |
See Progression events. |
addDesignEvent(options) |
See Design events. |
addErrorEvent(options) |
See Error events. |
addAdEvent(options) |
See Ad events. |
setCustomDimension01(value), 02, 03 |
Sets a custom dimension. |
setGlobalCustomEventFields(json) |
Custom fields added to every event. |
startSession(), endSession() |
Starts or ends a session when use_manual_session_handling = 1. |
setEnabledManualSessionHandling(flag) |
Switches manual session handling at runtime. |
setEnabledEventSubmission(flag) |
Stops or resumes sending events. |
setEnabledInfoLog(flag), setEnabledVerboseLog(flag) |
Switches SDK logging at runtime. |
setRemoteConfigsListener(function(self) end) |
Called when the remote configs are downloaded or updated. |
isRemoteConfigsReady() |
true once the remote configs are downloaded. |
getRemoteConfigsValueAsString({ key, defaultValue }) |
A remote config value as a string. |
getRemoteConfigsValueAsNumber({ key, defaultValue }) |
A remote config value as a number. |
getRemoteConfigsValueAsJson(key) |
A remote config value as a JSON string. |
getRemoteConfigsContentAsString() |
All remote configs as a JSON string. |
getABTestingId(), getABTestingVariantId() |
The player's A/B test and variant, empty when they are in none. |
getUserId() |
The GameAnalytics user id. |
setExternalUserId(id), getExternalUserId() |
Your own id for the player. |
getElapsedSessionTime() |
Length of the current session, in seconds. |
getElapsedTimeForPreviousSession() |
Length of the previous session, in seconds. |
getElapsedTimeFromAllSessions() |
Total time over all sessions, in seconds. |
enableSDKInitEvent(flag), enableFpsHistogram(flag), enableMemoryHistogram(flag), enableHealthHardwareInfo(flag) |
Switches the health events, call before initialize(). |
Android
- The SDK leaves out Google's App Set ID library, so App Set IDs are not sent. Games that already include
play-services-appset(for example through an ads or Firebase extension) send them as usual. - Error reporting (
enable_error_reporting = 1) needs theandroidx.corelibrary, which games usually get from another extension. getElapsedTimeForPreviousSession()returns 0.
iOS
- The SDK ships its privacy manifest (
PrivacyInfo.xcprivacy), which Defold adds to your app.
Web
- External user ids and session times are not available and return empty values or 0.
setEnabledEventSubmissionhas no effect.- The health events have a single switch: any of the four settings or functions enables all of them.
Desktop
- Requests go through Defold's own HTTP client, so no extra libraries are needed.
getElapsedSessionTime()is only meaningful once a session has started.
- Defold 1.14 or newer is required.
- Remove the
defold-openssldependency from yourgame.project, the SDK no longer needs it. - 32-bit Windows (
x86-win32), 32-bit iOS (armv7-ios) and thejs-webtarget are no longer supported, following Defold. - New functions:
getUserId,getExternalUserId,setExternalUserId,getABTestingId,getABTestingVariantId,getRemoteConfigsValueAsNumber,getRemoteConfigsValueAsJsonand the session time functions. - Remote Configs on iOS are now returned as JSON, like on the other platforms.