Obter IDs e tokens de acesso de ativos

Depois que o usuário instalar a Extensão do Facebook para Empresas (FBE, pelas iniciais em inglês) e você tiver o token de acesso associado (usado para fazer chamadas de API), será preciso obter a identificação do pixel, da conta de anúncios ou da Página ou o ID do Instagram para Empresas, do Gerenciador de Negócios ou do catálogo (opcional) para configurar os recursos relevantes. Esses IDs serão usados para pontos de extremidade da API e configurações da empresa.

Com a solução Business On Behalf Of, o cliente pode obter o token de acesso, usando também o token de acesso do usuário administrador do sistema do Gerenciador de Negócios do parceiro, em vez de apenas o token de acesso do administrador do Gerenciador de Negócios do cliente.

Reunir IDs para pontos de extremidade da API e configurações da empresa

Veja como obter essas informações:

• Webhook: obrigatório para todos os parceiros da plataforma que querem anunciar na App Store
• Ponto de extremidade da API de Instalação da FBE: recomendado para empresas auto-hospedadas

Criação do usuário do sistema

Após a instalação da FBE, a extensão gera um usuário do sistema para o funcionário no Gerenciador de Negócios do cliente. A nomenclatura para esse novo usuário do sistema segue o esquema {App Name} System User (FBE).

Os usuários do sistema representam servidores ou softwares que fazem chamadas de API para ativos que pertencem a um Gerenciador de Negócios ou que são gerenciados por ele.

Esse usuário do sistema tem permissões para todos os ativos da FBE associados com as seguintes permissões de tarefas:

1. Página: 'MANAGE'
2. Conta de anúncios: 'MANAGE'
3. Catálogo: 'MANAGE'
4. Pixel: 'EDIT'

Obter um token de usuário do sistema com a API

Se você receber um token de acesso do usuário por meio de um webhook ou do Login de Empresa após a instalação da FBE, será possível usar essa chave para obter o token de acesso do usuário do sistema no Gerenciador de Negócios. Para isso, faça a seguinte chamada de API:

curl -X POST \
  -F 'app_id={app_id}' \
  -F 'scope={permissions}' \ 
  -F 'access_token={access_token}' \
  -F 'fbe_external_business_id={fbe_external_business_id}' \
  https://graph.facebook.com/<API_VERSION>/<client_business_manager_id>/access_token

Para o campo scope, use a permissão manage_business_extension. Porém, dependendo do seu caso de uso, ads_management ou catalog_management também podem ser necessárias.

Para o campo access_token, você pode transmitir um token de acesso do usuário (user_access_token) ou um token de acesso do usuário administrador do sistema do Gerenciador de Negócios do parceiro (partner_bm_admin_system_user_token). Saiba mais sobre o token de acesso da empresa.

Webhook

Para receber atualizações imediatas sobre instalações, desinstalações e reconfigurações da FBE, disparamos eventos de Webhook toda vez que uma das suas empresas instala, modifica ou desinstala a extensão.

Quando um usuário instalar ou modificar a FBE, será necessário inspecionar a configuração do Webhook para entender quais ativos foram modificados, adicionados ou removidos da conexão com o seu app. O comportamento do app deve ser atualizado com base nos ativos conectados mais atuais.

Requisitos de configuração

1. Crie um ponto de extremidade em um servidor seguro que pode processar solicitações do Facebook: solicitações de verificação (GET) e notificações de eventos (POST).
2. Configure a assinatura de webhooks da FBE no Painel de Apps:
   • Na seção Extensão do Facebook para Empresas do Painel de Apps, acesse a aba Configuração, role a tela para baixo até o cartão Webhooks e clique em Editar URL de retorno.
   • Digite a URL do ponto de extremidade no campo URL de retorno de chamada e insira uma string no campo Verificar token. Incluiremos essa string em todas as solicitações de verificação.
   • Depois que você clicar em Verificar e salvar, enviaremos uma solicitação de verificação ao seu ponto de extremidade, que precisará ser validada.
   • O webhook fbe_install será assinado automaticamente. O cartão também exibirá um botão para desativar a assinatura, se necessário.

Analisar eventos de Webhook

Seu app precisará executar as ações a seguir toda vez que um webhook de instalação for recebido.

Para novas instalações

1. Armazene o token de acesso e o tipo dele. Depois, registre os ativos aos quais o app recebeu acesso.
2. Habilite o conjunto de recursos com base nos ativos que foram concedidos.
3. Se um ativo necessário para um recurso específico não for encontrado, desabilite apenas o recurso em questão. Por exemplo, se o app tiver recebido acesso a um catálogo, mas não a um pixel, implemente apenas o recurso com tecnologia de catálogo, não o de pixel.
4. Informe o usuário com uma atualização sobre como o app está se comportando com base em quais ativos ele pode acessar.

Para instalações atuais

1. Atualize o token de acesso, o tipo dele e o registro de ativos aos quais o app recebeu acesso.
2. Atualize o conjunto de recursos que será implementado pelo app para a empresa com base nos ativos concedidos.
3. Informe o usuário com uma atualização sobre como o app está se comportando com base em quais ativos ele pode acessar.

Analisar o webhook na desinstalação

Conclua as seguintes etapas na desinstalação:

1. Desabilite os recursos que o app implementa para a empresa.
2. Informe a empresa sobre a alteração na configuração.

O que está incluído na carga do webhook

Campos da resposta

Exemplo: carga com o campo booliano onsite_commerce_eligible

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    "instagram_profiles": [
      "<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            "feature_name" : string, 
            "feature_type": enum,
            "connected_assets": {
                "ad_account_id": "<ad_account_id>",
                "business_manager_id": "<business_manager_id>",
                "catalog_id": "<catalog_id>",
                "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
                "ig_profile_id": "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

API de Instalação da FBE

Para empresas que tenham instalado a FBE, você pode consultar as informações básicas de instalação (pixel_id e uma lista de perfis com IG Business ID and/or Page ID) usando este ponto de extremidade:

Exemplo

CURL -X GET 'https://graph.facebook.com/<API_VERSION>/fbe_business/fbe_installs?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Resposta

{
  "data": [{
    "token_type": "<token_type>"
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

A resposta inclui os campos a seguir. Agora, estes são a fonte da verdade nos ativos conectados da lista "installed_features":

Resposta da API de Configuração de Recursos

O modelo inclui a identificação da instância de cada recurso e campos que consistem em uma matriz de todos os recursos do mesmo tipo instalados pela empresa (exemplo: CTAs em várias páginas).

Para recursos que não podem ser personalizados, você verá apenas uma identificação da instância do recurso e uma sinalização com o status de habilitado. É possível atualizar somente os recursos personalizáveis com uma solicitação POST.

Esse modelo é diferente da API de Instalação da FBE porque fornece informações de outros recursos além dos ativos conectados, incluindo o status Ativado e personalizações específicas. Depois de chamar a API de Instalação da FBE, você poderá usá-la para ver mais informações sobre o status Ativado ou as configurações do recurso.

Leitura

É possível ler o status atual de configuração do recurso de qualquer empresa com a seguinte solicitação:

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Atualização

Para atualizar todos os recursos, use esta solicitação POST:

CURL -i -X POST \   
  -F 'fbe_external_business_id=<fbe_external_business_id>' \
  -F 'business_config={business_config object}' \
  -F 'access_token=<access_token>' 
  "https://graph.facebook.com/<API_VERSION>/fbe_business"

Resposta

{
  "page_cta": {
     "feature_instance_id": id1,
     "enabled": true,
     "cta_button_text": "Book Now",
     "cta_button_url": "https://partner-site.com/foo-business1",
     "below_button_text": "Powered by FBE Partner"
  },
  "page_ctas": [
    {
        "feature_instance_id": id1,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business1",
        "below_button_text": "Powered by FBE Partner"
    },
    {
        "feature_instance_id": id2,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business2",
        "below_button_text": "Powered by FBE Partner"
    }
  ],
  “ig_cta”: {...}
  "ig_ctas": [{...}, {...}],
  “ads”: [
    {
      "feature_instance_id": id3,
      “enabled”: true,
    },
    {
      "feature_instance_id": id4,
      “enabled”: true,
    },
  ],
  ...
}

Próximas etapas

• Configurar recursos da empresa
• Disparar eventos de pixel
• Atualizar seu catálogo