# Analytics Providers

Pinapayagan ng Analytics Providers na mag-attach ka ng **browser analytics at ads SDKs** sa public stream pages. Lilitaw ang stream views at play events sa mga tool na ginagamit mo na — hiwalay sa built-in na [Analytics](/fil/sharing/analytics/) reports ng DailyPlay at sa server-side [Connections](/fil/connections/overview/) (CRM / webhook sinks).

:::note
Public measurement IDs at project tokens lang ang sine-save. Huwag mag-paste ng secret API keys o server credentials dito.
:::

---

## Paano Ito Naiiba sa Connections at Reports

| Feature | Ano ang ginagawa nito |
| :------ | :-------------------- |
| **Analytics Providers** | Client-side SDKs sa player; pumupunta ang events sa GA4 / Mixpanel / atbp. dashboards |
| **Connections** | Server-side webhooks at CRM sync (Braze, Zapier, HubSpot, …) |
| **Reports / Analytics** | DailyPlay-hosted play metrics, sessions, leads, at exports |

---

## Mga Suportadong Provider

| Provider | Required fields | Optional fields |
| :------- | :-------------- | :-------------- |
| **Google Analytics** | Measurement ID (`G-…`) | — |
| **Mixpanel** | Project token | API host; Session Replay sample rate (0–100; blank = 100) |
| **PostHog** | Project API key, API host (hal. `https://us.i.posthog.com`) | — |
| **Amplitude** | API key | Server zone (`US` o `EU`; default US) |
| **Google Tag Manager** | Container ID (`GTM-…`) | — |
| **Meta Pixel** | Pixel ID | — |

Maaaring i-enable ang maraming provider types sa iisang stream (isang active link bawat type).

---

## Pag-set Up

Organization **owners** at **admins** lang ang maaaring mag-manage ng analytics providers.

### 1. Magdagdag ng provider (org library)

1. Pumunta sa **Connect → Analytics** (o buksan ang `/analytics`)
2. I-click ang **Add Provider**
3. Piliin ang provider type at ilagay ang display name plus required public IDs
4. I-save — reusable across streams

I-activate, i-deactivate, i-edit, o i-delete mula sa parehong page. Ang pag-delete ay nag-aalis din ng links mula sa streams.

### 2. I-enable ang tracking sa stream

1. Gumawa o mag-edit ng stream
2. Buksan ang **Tracking** step
3. I-enable ang provider type na gusto mo
4. Pumili ng:
   - **Use org provider** — piliin ang existing config, o
   - **Create new…** — maglagay ng display name at fields inline (gumagawa ng org provider at nagli-link kapag na-save ang stream)
5. I-save ang stream

I-disable ang type sa Tracking step para i-off ito sa stream nang hindi dini-delete ang org provider.

---

## Events na Ipinapadala sa Third-Party Tools

Kapag active ang naka-link na provider sa public stream, naglo-load ang DailyPlay ng SDK at nagfo-forward ng:

| Event | Kailan |
| :---- | :----- |
| Stream / page view | Sa SDK init (GA `page_view`; Mixpanel/Amplitude `stream_view`; GTM `dp_stream_view`; Meta `PageView`) |
| `play_start` | Nagsimula ang player (Meta → `ViewContent`) |
| `play_complete` | Natapos ang player (Meta → `CompleteRegistration`) |
| `share` | Nag-share ng result |
| `cta_click` | Meta → `Lead` kung supported |

Kasama madalas sa context ang `stream_id`, `stream_slug`, `stream_name`, `org_slug`, `player_uuid`, `session_id`, game/score fields, at URL query gaya ng `utm_*`, `external_id`, at `user_id`. Na-i-identify ang players sa pamamagitan ng `player_uuid` kapag mayroon.

Tumanggap ang GTM ng `dp_<event>` sa dataLayer para sa custom routing sa container.

---

## Privacy at Consent

- Lumalabas ang measurement IDs sa public stream payload by design (kailangan para sa client SDKs).
- Hindi ginagate ng DailyPlay ang mga SDK na ito sa hiwalay na cookie consent banner — tiyaking saklaw ng privacy policy at CMP mo ang third-party tags sa stream pages.
- Ang stream CTA marketing consent ay para sa lead forms, hindi para sa analytics SDK loading.
- Maaaring gumamit ang Mixpanel at PostHog ng `localStorage`. Maaaring i-record ng Mixpanel Session Replay ang canvas gameplay kapag naka-enable.

---

## Pamamahala

| Action | Effect |
| :----- | :----- |
| **Activate / Deactivate** (org) | Kontrol kung maaaring mag-load kapag naka-link |
| **Enable / Disable** (stream Tracking) | On/off tracking para sa stream na iyon |
| **Delete** (org) | Tinatanggal ang provider at lahat ng stream links |
| **Unlink** (stream) | Hihinto ang tracking sa stream; nananatili ang org provider |

Kailangang active ang org provider at stream link para mag-load ang SDK sa public player. Soft-fail ang failed SDK loads — tuloy ang play.

---

## Agents at API Keys

Magagamit ng org admins ang [MCP server](/fil/api/mcp/) gamit ang:

- `mcp:analytics_providers:read`
- `mcp:analytics_providers:write`

Tingnan ang [MCP Tools](/fil/api/mcp-tools/#analytics-providers) para sa buong listahan.

Typical flow:

1. `create_analytics_provider` with `provider` + public `config`
2. `link_stream_analytics_provider` with `stream_id` + `analytics_provider_id`
3. Optional per-stream `config_override`; unlink ay pinapanatili ang org provider

---

## Susunod na Hakbang

- Suriin ang built-in [Analytics](/fil/sharing/analytics/) at [Reports](/fil/sharing/analytics/#reports)
- Mag-wire ng CRM / webhook sinks sa [Connections](/fil/connections/overview/)
- Magpasa ng attribution params gamit ang [UTM Tracking](/fil/streams/overview/#utm-tracking)