API do Plano de Controle do Conversions API Gateway para várias contas

Integração de parceiros

Visão geral

A API do Plano de Controle do Conversions API Gateway para várias contas é um conjunto de APIs em GraphQL expostas a partir da instância do Gateway. Com ela, os desenvolvedores podem gerenciar programaticamente contas, fontes de dados e outras configurações de uma instância do Gateway. Além disso, os parceiros podem integrar a API à própria interface do usuário usada pelos anunciantes e oferecer a eles um fluxo contínuo de integração e gerenciamento.

Possíveis casos de uso:

Os anunciantes fazem a integração com o Gateway usando a interface do usuário do parceiro e executam ações de acompanhamento por meio das configurações de administração do Gateway. Esse caso exige a integração parcial da API do Plano de Controle.
Os anunciantes executam todas as ações na interface do usuário do parceiro, incluindo a integração com o Gateway e ações de acompanhamento. Isso pode ser um bom caso de uso para parceiros que não querem expor a interface do usuário do Gateway, mas ainda desejam oferecer o Gateway como um serviço para os anunciantes. Esse caso exige a integração completa da API do Plano de Controle.

Consulte a seção abaixo para obter mais detalhes sobre as etapas de integração.

Os termos API do Plano de Controle do Conversions API Gateway para várias contas e Gateway são usados como sinônimo neste documento.

Guia de integração

Dependendo do caso de uso, pode haver dois caminhos de integração (conforme mostrado no diagrama abaixo):

Integração parcial da API do Plano de Controle: Não requer a autenticação dos anunciantes.
Integração completa da API do Plano de Controle: requer a autenticação dos anunciantes via Extensão da Meta para Empresas (MBE, pelas iniciais em inglês) ou pela geração manual de tokens.

Pré-requisitos

Para os dois caminhos de integração, o parceiro precisa primeiro concluir as etapas abaixo:

Etapa 1: fazer a integração como um host da instância do Gateway

Etapa 2: gerar o nome da conta e a chave secreta da API

Acesse:

https://<Conversions API Gateway Endpoint>/hub/

Navegue até a aba Configurações do host, selecione a página Gerenciar contas da API e clique no botão da conta Adicionar API.

Insira sua senha novamente. Clique em Continuar.

Insira o nome da conta da API. Clique em Continuar.

O nome da conta deve ter apenas letras e números e não pode incluir espaços. O tamanho máximo é 20.

Copie e salve a chave secreta que foi gerada. Não será possível visualizá-la outra vez.

Para remover uma conta da API, clique em Excluir conta da API. Importante: essa ação é irreversível e pode causar interrupções em aplicativos ou serviços de anunciantes que usam a API.

Integração parcial

Caso de uso baseado na integração parcial:

O anunciante ativa o serviço do Gateway usando a interface do usuário do parceiro.
O parceiro gera um link de convite que pode ser usado pelo anunciante para definir uma senha e concluir a criação da conta do Gateway.
O anunciante usa as funcionalidades na interface do usuário do Gateway para executar ações como gerenciar domínios, roteamento, fontes de dados e usuários da conta.
O parceiro recupera os dados de uso da conta do anunciante e faz a cobrança com base nisso.

Confira uma visão geral do fluxo de usuários abaixo:

Para alcançar o resultado mostrado acima, o parceiro pode integrar um subconjunto da API do Plano de Controle, incluindo o seguinte:

Obter o token de acesso da API
Criar uma conta para anunciantes
Obter dados de uso da conta (para fins de cobrança, por exemplo)

Integração completa

Caso de uso baseado na integração completa:

O anunciante ativa o serviço do Gateway usando a interface do usuário do parceiro.
O parceiro integra a conta do Gateway do anunciante e recebe permissão para gerenciá-la. O anunciante autoriza o parceiro via MBE ou via geração manual de tokens.
O anunciante pode gerenciar fontes de dados, bem como domínios, roteamento e usuários da conta na interface do usuário do parceiro.
O parceiro recupera os dados de uso da conta do anunciante e faz a cobrança com base nisso.

Confira uma visão geral do fluxo de usuários abaixo:

Neste caminho de integração, para enviar eventos em nome dos anunciantes, os parceiros precisam pedir autorização e obter tokens de acesso do usuário do sistema via autenticação.

Autenticação

Os parceiros têm estas duas opções de autenticação para Pixels da Meta que não são gerenciados por eles:

Opção 1 - Extensão da Meta para Empresas

Antes de começar, você precisará do seguinte:

Atender a todos os requisitos para a implementação da MBE
Entrar em contato com seu representante da Meta para adicionar seu app à lista de permissão e obter uma permissão privada: open_bridge_configuration_management

A MBE fornece um ponto de extremidade para recuperar os tokens de acesso do usuário do sistema que foram criados no Gerenciador de Negócios do anunciante. Os parceiros devem seguir até a Etapa 4 do guia de integração da MBE. Além disso, faça o seguinte:

Defina o valor do parâmetro do canal no objeto de configuração da instalação como CONVERSIONS_API_GATEWAY_ADVERTISER.
Confirme que é possível receber a resposta do webhook após a conclusão da integração.
Use o token de acesso retornado via MBE e converta-o em um token de acesso do usuário do sistema fazendo uma chamada de API adicional.
Salve uma cópia de external_business_id, pixel_id, business_id e do token de acesso do usuário do sistema.

Opção 2 - Token de acesso do usuário do sistema do cliente

Com essa opção, os parceiros podem fazer com que os anunciantes:

criem manualmente um token de acesso do usuário do sistema via API de Conversões nas configurações do Gerenciador de Eventos;
compartilhem o pixel_id, o business_id e o token de acesso do usuário do sistema com o parceiro e salvem uma cópia.

Integração

Os parceiros podem integrar o conjunto completo da API do Plano de Controle. Para saber mais, consulte este documento sobre a referência da API.

Paridade entre a API e a interface do usuário

Aplicamos a paridade entre a API e a interface do usuário, expondo os mesmos pontos de extremidade da API usados na interface do usuário do Gateway. No entanto, os pontos de extremidade que não forem mencionados na referência da API estarão sujeitos a alterações de desenvolvimento. Para reduzir o impacto inesperado, os pontos de extremidade da API não incluídos na referência retornarão um código de erro 418. Ainda será possível usar a API por sua conta e risco.