# Google Analytics


> **Информация:**

Esta integração tem status `@beta`. Acompanhe o [histórico de alterações do player](https://docs-br.kinescope.com/player-docs/changelog/).



O player pode enviar eventos de visualização ao Google Analytics 4. Escolha como conectar a ferramenta de análise ao seu site:

| Método | Recomendado para |
| :--- | :--- |
| [Google Tag](#configuracao-do-google-tag) | Você conecta a gtag diretamente às suas páginas |
| [Google Tag Manager](#configuracao-do-google-tag-manager) | Você já usa o GTM |

## Visão geral da configuração

1. Conecte o [Google Tag](#configuracao-do-google-tag) ou o [GTM](#configuracao-do-google-tag-manager) ao seu site.
2. Se o player é executado em um `<iframe>` por [incorporação simples](https://docs-br.kinescope.com/player-docs/embedding/simple-iframe-embed/) ou pela [IFrame API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api/), adicione o [script de integração](#script-de-integracao-para-iframe).
3. [Crie dimensões personalizadas](#definicoes-personalizadas-no-ga4) no GA4 para filtrar relatórios por vídeo.

## Script de integração para iframe {#script-de-integracao-para-iframe}

Os eventos do player ocorrem dentro do iframe. Adicione este script para que a página possa recebê-los:

`https://player.kinescope.io/latest/iframe.ga.js`

Insira o script **depois** do Google Tag ou do GTM. Sem ele, os eventos do iframe não chegam à ferramenta de análise.

## Google Tag {#configuracao-do-google-tag}

```html
<!-- 1. Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || []
  function gtag() {
    dataLayer.push(arguments)
  }
  gtag('js', new Date())
  gtag('config', 'G-XXXXXXXXXX')
</script>

<!-- 2. Script de integração após o Google Tag. Obrigatório quando o player está em um iframe -->
<script src="https://player.kinescope.io/latest/iframe.ga.js"></script>
```

Substitua `G-XXXXXXXXXX` pelo ID do fluxo de dados do GA4.

## Google Tag Manager {#configuracao-do-google-tag-manager}

1. Baixe o [arquivo de configuração](https://player.kinescope.io/latest/gtm/workspace.json).
2. Importe o arquivo no GTM. Selecione **Mesclar** para manter seu contêiner atual.
3. Na tag `GA4 – Event – Kinescope Video`, informe o ID do fluxo de dados (`G-…`) usado no Google Analytics.
4. Publique o contêiner.
5. [Adicione definições personalizadas](#definicoes-personalizadas-no-ga4) no Google Analytics.

O arquivo inclui a tag `GA4 – Event – Kinescope Video`. Ela envia ações do player, como `Play` e `Ended`, junto com os [parâmetros do vídeo](#eventos-enviados-ao-ga4).

### Exemplo de código da página {#exemplo-de-codigo-da-pagina}

```html
<!-- 1. Google Tag Manager -->
<script>
  ;(function (w, d, s, l, i) {
    w[l] = w[l] || []
    w[l].push({ 'gtm.start': new Date().getTime(), event: 'gtm.js' })
    var f = d.getElementsByTagName(s)[0],
      j = d.createElement(s),
      dl = l != 'dataLayer' ? '&l=' + l : ''
    j.async = true
    j.src = 'https://www.googletagmanager.com/gtm.js?id=' + i + dl
    f.parentNode.insertBefore(j, f)
  })(window, document, 'script', 'dataLayer', 'GTM-XXXXXXX')
</script>

<!-- 2. Script de integração após o GTM. Obrigatório quando o player está em um iframe -->
<script src="https://player.kinescope.io/latest/iframe.ga.js"></script>
```

Substitua `GTM-XXXXXXX` pelo ID do seu contêiner. Você não precisa de uma gtag separada se o GTM já envia dados ao GA4, como no arquivo importado.

Copie no Tag Manager o trecho destinado a usuários sem JavaScript. Cole-o no início de `<body>`.

## Eventos enviados ao GA4 {#eventos-enviados-ao-ga4}

Por padrão, o player envia estes eventos:

| Evento | Quando é disparado |
| :--- | :--- |
| `Play` | A reprodução começa |
| `Ended` | A reprodução chega ao fim |

Se `settings.googleAnalytics.trigger` contém pontos de progresso, o player também envia eventos como:

| Evento | Quando é disparado |
| :--- | :--- |
| `10 Percent Played`, `25 Percent Played`, … | O espectador chega a N por cento |
| `60 Seconds Played`, `120 Seconds Played`, … | O espectador chega a N segundos |

Exemplo com a [IFrame API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-create-player/#create):

```js
playerFactory.create('player', {
  url: 'https://kinescope.io/VIDEO_ID',
  settings: {
    googleAnalytics: {
      // Opcional se a página já fornece o ID de medição por gtag ou GTM
      // measurementId: 'G-XXXXXXXXXX',
      trigger: {
        percentages: [10, 25, 50, 75, 95], // → 10 Percent Played, 25 Percent Played, …
        timePoints: [60, 120, 300, 600], // → 60 Seconds Played, 120 Seconds Played, …
      },
    },
  },
})
```

Você pode definir apenas `percentages`, apenas `timePoints` ou os dois arrays. Sem `trigger`, o player envia somente `Play` e `Ended`.

Parâmetros dos eventos:

| Parâmetro | Valor |
| :--- | :--- |
| `video_id` | ID do vídeo no Kinescope |
| `video_title` | Título do vídeo |
| `video_url` | URL do vídeo |
| `video_duration` | Duração em segundos |
| `video_percent` | Progresso da visualização em percentual |
| `video_current_time` | Posição atual em segundos |
| `video_seconds_played` | Quantidade de segundos realmente assistidos |
| `event_category` | Sempre `Video` |
| `external_id` | ID externo, se definido com `externalid` ou `externalId` |

## Definições personalizadas no GA4 {#definicoes-personalizadas-no-ga4}

Crie **dimensões personalizadas** para filtrar relatórios por vídeo.

> **Внимание:**

No campo **Parâmetro do evento**, informe o nome técnico da tabela, como `video_id`. Não informe um rótulo como “ID do vídeo”.



1. No Google Analytics, acesse **Administrador** → **Definições personalizadas**.
2. Crie dimensões com escopo de evento:

| Nome da dimensão | Parâmetro do evento |
| :--- | :--- |
| ID do vídeo | `video_id` |
| Título do vídeo | `video_title` |
| URL do vídeo | `video_url` |
| ID externo | `external_id` |

Adicione parâmetros numéricos, como `video_duration` e `video_percent`, quando necessário.

## Próximos passos

- [Yandex Metrica](https://docs-br.kinescope.com/player-docs/yandex-metrika/) — envie eventos do player à Metrica
- [Incorporação simples com iframe](https://docs-br.kinescope.com/player-docs/embedding/simple-iframe-embed/) — configure `externalid`
- [IFrame API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api/) — controle o player e configure `settings.externalId`

