Este guia explica como enviar eventos de fluxos de app e Web do Measurement Protocol do Google Analytics a um servidor do Google Analytics. Assim você pode conferir eventos do Measurement Protocol nos seus relatórios do Analytics.
Escolha a plataforma a ser retratada neste guia:
Formatar a solicitação
O Measurement Protocol do Google Analytics só oferece suporte a solicitações POST HTTP.
Para enviar um evento, use este formato:
POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
<payload_data>
É necessário informar o seguinte no URL da solicitação:
api_secret: a chave secreta da API gerada na interface do Google Analytics.Para criar uma nova chave secreta, navegue até Administrador > Fluxos de dados > escolha seu fluxo > Measurement Protocol > Criar.
measurement_id: o ID de métricas associado a um fluxo, que fica na interface do Google Analytics, em Administrador > Fluxos de dados > escolha seu fluxo > ID de métricas.O
measurement_idnão é o ID do fluxo.
Confira a referência completa nos parâmetros de consulta.
É necessário informar o seguinte no corpo da solicitação:
client_id: identificador exclusivo de um cliente. Ele é diferente de umapp_instance_iddo Firebase. Use gtag.js('get').
user_id: opcional. Identificador exclusivo de um usuário. Pode conter somente caracteres UTF-8. Para mais informações sobre esse identificador, consulte User-ID para análise multiplataforma.consent: opcional. Saiba como definir as configurações de consentimento.timestamp_micros: opcional. O tempo da época Unix, em microssegundos, para os eventos e as propriedades do usuário na solicitação. Se não for especificado, o padrão será o horário da solicitação.events: matriz de itens de evento. É possível incluir vários eventos em uma solicitação.Para que a atividade do usuário seja mostrada em relatórios como o Relatório de tempo real, é necessário enviar
engagement_time_msecesession_idcomo parte dosparamspara umevent. O parâmetroengagement_time_msecprecisa refletir o tempo de engajamento do evento em milissegundos.Veja um exemplo:
{
"client_id": "123456.7654321",
"events": [
{
"name": "campaign_details",
"params": {
"campaign_id": "google_1234",
"campaign": "Summer_fun",
"source": "google",
"medium": "cpc",
"term": "summer+travel",
"content": "logolink",
"session_id": "123",
"engagement_time_msec": 100
}
}
]
}
Embora session_start seja um nome de evento reservado, criar um novo session_id gera uma nova sessão sem a necessidade de enviar session_start. Saiba como as sessões são contabilizadas.
Testar
Confira um exemplo que você pode usar para enviar vários eventos de uma só vez. Este exemplo
envia um evento tutorial_begin e um evento
join_group ao servidor do Google Analytics.
const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
method: "POST",
body: JSON.stringify({
client_id: "XXXXXXXXXX.YYYYYYYYYY",
events: [
{
name: "tutorial_begin",
params: {
"session_id": "123",
"engagement_time_msec": 100
}
},
{
name: "join_group",
params: {
"group_id": "G_12345",
"session_id": "123",
"engagement_time_msec": 150
}
}
]
})
});
Carimbo de data/hora de substituição
O Measurement Protocol usa o primeiro carimbo de data/hora encontrado na lista a seguir para cada evento na solicitação:
- O
timestamp_microsdo evento. - O
timestamp_microsda solicitação. - O horário em que o Measurement Protocol recebe a solicitação.
O exemplo a seguir envia um carimbo de data/hora no nível da solicitação que se aplica a todos os
eventos na solicitação. Como resultado, o Measurement Protocol atribui aos eventos tutorial_begin e join_group um carimbo de data/hora de requestUnixEpochTimeInMicros.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin"
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
]
}
O exemplo a seguir envia um carimbo de data/hora no nível da solicitação e um no nível do evento. Como resultado, o Measurement Protocol atribui ao evento tutorial_begin
um carimbo de data/hora de tutorialBeginUnixEpochTimeInMicros e ao evento join_group
um carimbo de data/hora de requestUnixEpochTimeInMicros.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin",
"timestamp_micros": tutorialBeginUnixEpochTimeInMicros
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
]
}
Limitações
As limitações a seguir são válidas para o envio de eventos do Measurement Protocol ao Google Analytics:
- As solicitações podem ter no máximo 25 eventos.
- Os eventos podem ter no máximo 25 parâmetros.
- Os eventos podem ter até 25 propriedades do usuário.
- Os nomes das propriedades do usuário podem ter, no máximo, 24 caracteres.
- Os valores de propriedade do usuário precisam ter no máximo 36 caracteres.
- Os nomes dos eventos precisam ter no máximo 40 caracteres alfanuméricos e sublinhados, além de começar com um caractere alfabético.
- Os nomes dos parâmetros (incluindo os parâmetros de item) precisam ter no máximo 40 caracteres alfanuméricos e sublinhados, além de começar com um caractere alfabético.
- Os valores de parâmetros, incluindo os valores de parâmetros de itens, precisam ter no máximo 100 caracteres para uma propriedade padrão do Google Analytics e 500 caracteres para uma propriedade do Google Analytics 360.
- Os parâmetros de itens podem ter no máximo 10 parâmetros personalizados.
- O corpo da postagem precisa ter menos de 130 KB.
- Os eventos do Measurement Protocol do app enviados ao Google Analytics não preenchem os públicos-alvo de pesquisa no Google Ads para usuários de apps.
Para ver outros requisitos de cada caso de uso, consulte casos de uso comuns.