> 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.

Bridge already sends system events on its own — SDK initialization, [platform messages](/playgama/bridge-sdk/api/platform.md#sending-a-message-to-the-platform) such as `game_ready`, ads, purchases, session start and end. You don't need to duplicate them. The analytics module is for events only your game knows about.

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`                        |