> For the complete documentation index, see [llms.txt](https://wiki.playgama.com/playgama/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.playgama.com/playgama/bridge-sdk/api/analytics.md).

# Analytics

Send your own game events to Playgama analytics — level results, shop visits, tutorial steps, economy changes. Use them to see where players drop off and what they do in the game.

{% embed url="<https://youtu.be/11IjPxjoEnc>" %}

Some events reach analytics without extra code. When your game sends a [platform message](/playgama/bridge-sdk/api/platform.md#sending-a-message-to-the-platform) such as `game_ready` or `level_completed`, Bridge records a matching analytics event along with it. The same happens for SDK initialization, ads, purchases, and session start and end.

{% hint style="info" %}
This doesn't replace platform messages — keep sending them with `platform.sendMessage`, `game_ready` above all. Just don't send the same events a second time through `analytics.send`. The analytics module is for events only your game knows about.
{% endhint %}

The event name and data are up to you — any name is safe to use, it never conflicts with the system events.

{% hint style="warning" %}
Keep event names stable and short, in `snake_case`: `level_completed`, not `Level 3 completed!`. Put variable values (level number, score, item id) into the data, not into the name — otherwise every value becomes a separate event and the stats are hard to read.
{% endhint %}

## Send Event

Takes the event name (a non-empty string) and optional data — a flat object with string, number or boolean values.

{% tabs %}
{% tab title="Plain JS" %}

```javascript
// event without data
bridge.analytics.send('tutorial_completed')

// event with data
bridge.analytics.send('level_completed', {
    level: 3,
    score: 1250,
    stars: 2,
    first_try: true,
})
```

{% endtab %}

{% tab title="Unity" %}

```csharp
using System.Collections.Generic;

// event without data
Bridge.analytics.Send("tutorial_completed");

// event with data
Bridge.analytics.Send("level_completed", new Dictionary<string, object>
{
    { "level", 3 },
    { "score", 1250 },
    { "stars", 2 },
    { "first_try", true }
});
```

Nothing is sent from the Unity Editor — test in a WebGL build.
{% endtab %}

{% tab title="Construct 3" %}
Add data with the **Add Action Parameter** / **Add Bool Action Parameter** actions, then run **Send Analytics Event** with the event name. The parameters are cleared after each send. To send an event without data, use **Send Analytics Event** alone.

<details>

<summary>Copy This Example</summary>

```
{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[{"id":"on-clicked","objectClass":"Button"}],"actions":[{"id":"add-action-parameter","objectClass":"PlaygamaBridge","parameters":{"key":"\"level\"","value":"3"}},{"id":"add-action-parameter","objectClass":"PlaygamaBridge","parameters":{"key":"\"score\"","value":"1250"}},{"id":"add-action-parameter","objectClass":"PlaygamaBridge","parameters":{"key":"\"stars\"","value":"2"}},{"id":"send-analytics-event","objectClass":"PlaygamaBridge","parameters":{"event-name":"\"level_completed\""}}]}]}
```

</details>
{% endtab %}

{% tab title="GDevelop" %}
Add data with the **Add Action Parameter** / **Add Bool Action Parameter** actions, then run **Send Analytics Event** with the event name. Numeric strings passed to **Add Action Parameter** are sent as numbers. The parameters are cleared after each send. To send an event without data, use **Send Analytics Event** alone.

<details>

<summary>Copy This Example</summary>

```
{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[{"type":{"value":"PanelSpriteButton::PanelSpriteButton::IsClicked"},"parameters":["Button",""]}],"actions":[{"type":{"value":"PlaygamaBridge::AddActionParameter"},"parameters":["","\"level\"","\"3\"",""]},{"type":{"value":"PlaygamaBridge::AddActionParameter"},"parameters":["","\"score\"","\"1250\"",""]},{"type":{"value":"PlaygamaBridge::AddActionParameter"},"parameters":["","\"stars\"","\"2\"",""]},{"type":{"value":"PlaygamaBridge::AddBoolActionParameter"},"parameters":["","\"first_try\"","True",""]},{"type":{"value":"PlaygamaBridge::SendAnalyticsEvent"},"parameters":["","\"level_completed\"",""]}]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}
```

</details>
{% endtab %}

{% tab title="Godot" %}

```gdscript
# event without data
Bridge.analytics.send("tutorial_completed")

# event with data
Bridge.analytics.send("level_completed", {
	"level": 3,
	"score": 1250,
	"stars": 2,
	"first_try": true
})
```

The same code works in Godot 3 and Godot 4. Nothing is sent from the editor — test in a Web export.
{% endtab %}

{% tab title="GameMaker" %}
Pass the data as a JSON string. Use an empty string when there is no data.

```javascript
// event without data
playgama_bridge_analytics_send("tutorial_completed", "")

// event with data
playgama_bridge_analytics_send("level_completed", json_stringify({
    level: 3,
    score: 1250,
    stars: 2,
    first_try: true
}))
```

{% endtab %}

{% tab title="Defold" %}

```lua
-- event without data
bridge.analytics.send("tutorial_completed")

-- event with data
bridge.analytics.send("level_completed", {
    level = 3,
    score = 1250,
    stars = 2,
    first_try = true
})
```

Events are sent only in HTML5 builds; on other targets the call does nothing.
{% endtab %}

{% tab title="Cocos Creator" %}

```typescript
// event without data
bridge.analytics.send('tutorial_completed')

// event with data
bridge.analytics.send('level_completed', {
    level: 3,
    score: 1250,
    stars: 2,
    first_try: true,
})
```

{% endtab %}

{% tab title="Scratch" %}
Use the `send analytics event [EVENT_NAME] with data [DATA]` block. Pass the data as a JSON string, for example `{"level": 3, "score": 1250, "stars": 2, "first_try": true}`, or leave it empty. If the JSON is invalid, the event is sent without data.
{% endtab %}
{% endtabs %}

## Examples

A few events that are useful in most games. Names and fields are only suggestions — pick what fits your game and keep it consistent.

| Event                | When to send                        | Data                                      |
| -------------------- | ----------------------------------- | ----------------------------------------- |
| `tutorial_step`      | The player finishes a tutorial step | `step`                                    |
| `tutorial_completed` | The tutorial is finished            | —                                         |
| `level_started`      | A level starts                      | `level`                                   |
| `level_completed`    | A level is won                      | `level`, `score`, `stars`, `duration_sec` |
| `level_failed`       | A level is lost                     | `level`, `reason`                         |
| `shop_opened`        | The player opens the shop           | `source` (e.g. `main_menu`, `level_end`)  |
| `item_bought`        | The player spends soft currency     | `item_id`, `price`, `currency`            |
| `currency_earned`    | The player gets soft currency       | `amount`, `currency`, `source`            |
| `upgrade_purchased`  | An upgrade is bought                | `upgrade_id`, `level`                     |
| `settings_changed`   | A setting is changed                | `setting`, `value`                        |