API de Qualidade da Integração

Esta API está em fase de testes beta. Para obter acesso, entre em contato com seu representante da Meta.

Os anunciantes que compartilham eventos do servidor usando a API de Conversões podem conferir a qualidade da correspondência de cada evento no Gerenciador de Eventos. No entanto, isso só funciona individualmente e é difícil de escalar nos casos em que um parceiro provedor de tecnologia, parceiro de agência ou anunciante gerencia uma grande quantidade de Pixels da Meta para seus negócios. A API de Qualidade da Integração pode ajudar a resolver esse problema consolidando métricas de qualidade da integração de modo programático em escala.

Sobre a qualidade da correspondência de eventos

Qualidade da correspondência de eventos

A qualidade da correspondência de eventos (EMQ, pelas iniciais em inglês) é uma pontuação de 0 a 10 que indica a eficácia da correspondência das informações do cliente enviadas pelo seu servidor com as instâncias de eventos de uma conta do Facebook. A correspondência de eventos de alta qualidade pode melhorar a atribuição e o desempenho dos anúncios. Importante: essa métrica está em desenvolvimento.

Como o cálculo é feito

A qualidade da correspondência de eventos é calculada com base na observação dos seguintes aspectos: 1) quais parâmetros de informações do cliente são recebidos do seu servidor por meio de uma integração da API de Conversões; 2) a qualidade das informações recebidas; e 3) a porcentagem de instâncias de eventos associadas a uma conta da Meta.

Como essa métrica é usada

A qualidade da correspondência de eventos (EMQ, pelas iniciais em inglês) é usada para avaliar se a API de Conversões está enviando as informações corretas do cliente para associar seus eventos a uma conta da Meta e para verificar se você configurou os parâmetros de informações do cliente da forma adequada. Os parâmetros de informações do cliente ajudam a associar os eventos a uma conta da Meta. Assim, você pode atribuir conversões aos seus anúncios e exibi-los às pessoas que têm maior probabilidade de gerar uma conversão.

A qualidade da correspondência de eventos é calculada em tempo real. Saiba mais sobre as boas práticas da EMQ.

No momento, a EMQ está disponível apenas para eventos da web. Para outros tipos (como eventos de loja física e offline, eventos do app, leads convertidos ou qualquer integração em etapas alfa ou beta), entre em contato com um representante da Meta para saber como aprimorar a qualidade da correspondência.

Casos de uso comuns

Parceiros e agências podem usar a API de Qualidade da Integração para fornecer um painel de qualidade e insights, ao mesmo tempo em que ajudam os anunciantes a aprimorar e otimizar as integrações. Os parceiros também podem usar esse recurso para monitorar a estabilidade da integração da API de Conversões. Com esse ponto de extremidade, os anunciantes podem agregar dados de qualidade da integração para incorporar no processo de monitoramento.

Autenticação

Autenticação do anunciante via Gerenciador de Negócios

No Gerenciador de Negócios, vá até a seção Usuários e selecione a aba Usuário do sistema. Clique no usuário específico do sistema que você está usando para a API de Conversões.
Acesse o diálogo Atribuir ativo e escolha Pixels. Depois, selecione os pixels em nome dos quais você quer enviar eventos.
Para cada pixel, selecione a permissão Gerenciar pixel e clique em Salvar alterações.
Volte para a página de detalhes do seu usuário do sistema. Verifique se os pixels selecionados aparecem lá.
Para gerar o token de acesso, siga estas instruções.

Autenticação da plataforma do parceiro

O primeiro passo é solicitar uma autorização para enviar eventos em nome dos seus clientes. Existem as seguintes opções de autenticação:

Login do Facebook para Empresas (recomendado)

O Login do Facebook para Empresas é a solução de autenticação e autorização mais usada entre provedores de tecnologia e desenvolvedores de apps de negócios que precisam acessar os ativos dos clientes. Esse recurso permite especificar o tipo de token de acesso, os tipos de ativos, bem como as permissões necessárias ao seu app, e salvar essas escolhas como um conjunto (configuração). Dessa forma, você pode apresentar o conjunto aos clientes para que eles concluam o fluxo e concedam ao seu app acesso aos respectivos ativos de negócios.

Extensão da Meta para Empresas (recomendado)

A Extensão da Meta para Empresas (MBE, pelas iniciais em inglês) retorna todas as informações necessárias para enviar eventos em nome do cliente. Ela fornece um ponto de extremidade para recuperar tokens de acesso do usuário do sistema criados no Gerenciador de Negócios do cliente. Esse processo inclui as permissões para enviar eventos do servidor e é feito de forma automática e segura. A MBE está atualmente em fase de testes beta. Para obter acesso, entre em contato com seu representante da Meta.

O ponto de extremidade requer um token de acesso do usuário como parâmetro de entrada. Caso você nunca tenha usado a MBE, faça uma chamada para o ponto de extremidade a fim de buscar o token de acesso do usuário do sistema quando terminar de configurar a extensão. Os usuários existentes precisarão solicitar outra autenticação antes de fazer chamadas para o novo ponto de extremidade da API.

Compartilhamento de um Pixel da Meta do cliente com o Gerenciador de Negócios do parceiro

O cliente compartilha o próprio Pixel da Meta com o parceiro através das configurações do Gerenciador de Negócios ou via API. Depois, o parceiro pode atribuir o usuário do sistema ao pixel do cliente e gerar um token de acesso para enviar eventos do servidor.

Como recuperar informações de qualidade da integração usando um pixel

É possível monitorar a pontuação de qualidade da correspondência por evento, além das chaves de correspondência enviadas, usando o ponto de extremidade, os parâmetros e os campos da API listados abaixo:

Ponto de extremidade

https://graph.facebook.com/v21.0/<pixel_id>/integration_quality

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`agent_name` string	Opcional. O valor normalizado do campo partner_agent é usado para filtrar apenas eventos enviados com o parâmetro partner_agent na solicitação POST /{pixel_id}/events. Veja as boas práticas de atribuição de eventos em Implementação de ponta a ponta da API de Conversões e Boas práticas da API de Conversões. Por exemplo, se o valor de partner_agent for `[partner_name]_[majorversion]_[minorVersion]`, o valor da string do agente normalizado será `partner_name` em minúsculas. O `agent_name` permite que você defina o identificador da sua plataforma ao enviar eventos em nome de um cliente. Caso você seja uma agência ou um parceiro gerenciado, trabalhe com o representante da Meta para definir o identificador. Se você for um anunciante, provavelmente não será preciso se preocupar com a atribuição de `agent_name`. Lembre-se de que, se `agent_name` não for fornecido, todos os eventos serão incluídos no cálculo da EMQ, independentemente de terem sido enviados por um agente ou não.

agent_name

string

Opcional.
O valor normalizado do campo partner_agent é usado para filtrar apenas eventos enviados com o parâmetro partner_agent na solicitação POST /{pixel_id}/events. Veja as boas práticas de atribuição de eventos em Implementação de ponta a ponta da API de Conversões e Boas práticas da API de Conversões.

Por exemplo, se o valor de partner_agent for [partner_name]_[majorversion]_[minorVersion], o valor da string do agente normalizado será partner_name em minúsculas.

O agent_name permite que você defina o identificador da sua plataforma ao enviar eventos em nome de um cliente. Caso você seja uma agência ou um parceiro gerenciado, trabalhe com o representante da Meta para definir o identificador.

Se você for um anunciante, provavelmente não será preciso se preocupar com a atribuição de agent_name.

Lembre-se de que, se agent_name não for fornecido, todos os eventos serão incluídos no cálculo da EMQ, independentemente de terem sido enviados por um agente ou não.

Campos

Campo	Descrição
`event_name` string	O nome de um evento padrão ou personalizado.
`event_match_quality` AdsPixelCAPIEMQ	A qualidade da correspondência de eventos indica o quanto as informações do cliente enviadas pelo seu servidor correspondem com as instâncias de eventos de uma conta do Facebook.

Exemplo

Explorador da Graph API

GET/v21.0/<PIXEL_ID>/integration_quality?fields=event_match_quality,event_name&agent_name=<AGENT_NAME>&access_token=<ACCESS_TOKEN>

cURL

curl -X GET -G \
  -d 'fields="event_match_quality,event_name"' \
  -d 'agent_name="&lt;AGENT_NAME&gt;"' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<LATEST_VERSION>/<PIXEL_ID>/integration_quality

Resposta da API

{
  "data": [
    {
      "event_match_quality": {
        "composite_score": 5.1,
        "match_key_feedback": [
          {
            "identifier": "email",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "user_agent",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "external_id",
            "coverage": {
              "percentage": 100
            }
          }
        ]      
      },
      "event_name": "pLTVPurchase"
    },
    {
      "event_match_quality": {
        "composite_score": 7.2,
        "match_key_feedback": [
          {
            "identifier": "email",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "user_agent",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "phone",
            "coverage": {
              "percentage": 69.1
            }
          },
          {
            "identifier": "fbp",
            "coverage": {
              "percentage": 96.7
            }
          },
          {
            "identifier": "external_id",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "fbc",
            "coverage": {
              "percentage": 3.2
            }
          }
        ]
      },
      "event_name": "CompleteRegistration"
    }
  ]
}

Perguntas frequentes

What is the access token used for?

The access token is used when partners send signal events or access the Setup Quality API on behalf of advertisers. The client system user access token onboarding method is not compatible with the EMQ API at the moment.

Link permanente

How should the partner_agent field be formatted?

The partner_agent value in your API GET request should be a normalized lowercase format. This field is now optional.

Link permanente

Saiba mais

Boas práticas da API de Conversões
Driving performance with an optimized Conversions API setup
Conversions API Resources
Orientações sobre a qualidade de configuração da API de Conversões na Central de Ajuda para Empresas da Meta:

Boas práticas para a API de Conversões para ajudar a melhorar o desempenho do anúncio. As boas práticas da API de Conversões podem ajudar as empresas a melhorar o desempenho dos anúncios reduzindo o custo por ação. Sugerimos que você siga essas recomendações na configuração inicial, mas também é possível usá-las para atualizar configurações existentes.

Como visualizar detalhes de eventos do servidor no Gerenciador de Eventos da Meta. Depois de configurar a API de Conversões, as empresas podem usar esse artigo para aprender a monitorar eventos e parâmetros. Isso permitirá que elas verifiquem se a configuração funciona conforme esperado e identifiquem oportunidades de melhoria. As empresas também podem descobrir como usar os detalhes de eventos do servidor – Correspondência de eventos (Qualidade da correspondência de eventos/EMQ), Atualização de dados, Visão geral de eventos e Desduplicação de eventos – no Gerenciador de Eventos para aprimorar a configuração da API de Conversões.