API de Conversões Offline

Use a API de Conversões Offline para enviar eventos de conversão offline e ver quantos clientes visualizaram ou clicaram em anúncios da Meta antes de converter.

Antes de começar

Para usar esta API, você precisará do seguinte:

1. Gerenciador de Negócios da Meta

Caso ainda não tenha, crie um.

2. ID do app da Meta

Para acessar a API de Marketing. Para criar um app da Meta:

• Acesse Gerenciador de Negócios > Configurações do negócio.
• Selecione Aplicativos.
• Clique em Adicionar novo aplicativo e siga as instruções.

3. Análise do app e permissões

As regras relativas à análise do app e às permissões dependem de como você implementa nossa API:

4. Usuário do sistema e token do Gerenciador de Negócios

Com o acesso de usuário do sistema, seu app pode enviar dados para a Meta usando a API. Para criar isso:

• Acesse Gerenciador de Negócios > Configurações do negócio.
• Selecione Usuários do sistema.
• Clique em Adicionar novo usuário do sistema.
• Selecione Usuário administrador do sistema como a função do usuário do sistema.

Um token de acesso fornece acesso aos dados da Meta. Siga estas etapas para criar tokens de acesso do usuário do sistema:

• Acesse Gerenciador de Negócios > Configurações do negócio.
• Selecione Usuários do sistema.
• Selecione o usuário do sistema e clique em Gerar novo token.
• Selecione o app > selecione ads_management como o escopo.

5. Conta de anúncios

É necessário ter uma conta de anúncios para veicular campanhas publicitárias na Meta. Para criar uma, consulte API de Marketing ou Central de Ajuda para Empresas: Sobre as configurações do negócio no Gerenciador de Negócios da Meta.

6. Conceder ao usuário do sistema o acesso à conta de anúncios

Conceda ao usuário do sistema o acesso à sua conta de anúncios.

• Acesse Gerenciador de Negócios > Configurações do negócio.
• Selecione Usuários do sistema.
• Selecione o usuário do sistema e clique em Atribuir ativos.
• Selecione sua conta de anúncios.

7. Conjunto de eventos offline

Estes são arquivos carregados com dados de conversão offline. Ao criar um anúncio, defina tracking_spec para a identificação do conjunto de eventos offline de modo a atribuir os eventos corretamente. Você poderá então criar conjuntos de eventos, visualizar estatísticas das suas importações, excluir e modificar esses dados no Gerenciador de Negócios.

Com implementações mais antigas, era possível fazer operações CRUD do conjunto de eventos offline no nível do Gerenciador de Negócios para compartilhar conjuntos de eventos com outros objetos e entidades.

Carregar dados do evento

Você precisa de acesso específico para criar conjuntos de eventos offline, carregar ou visualizar dados de um conjunto de eventos. Você também precisará desse acesso para atribuir essas permissões a uma conta de anúncios. Você deve ser uma destas opções:

• Administrador do Gerenciador de Negócios
• Usuário administrador do sistema que criou o conjunto de eventos offline
• Administrador da ad_account conectada ao conjunto de eventos offline

Consulte a referência sobre conjunto de eventos de conversão offline.

1. Criar um conjunto de eventos offline

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Faça uma chamada HTTP POST:

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

A resposta inclui o id de um conjunto de eventos:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parâmetros

2. Atribuir permissões da conta de anúncios

Para atribuir permissões de rastreamento e leitura para uma conta de anúncios:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parâmetros

3. Definir o rastreamento de anúncios

Quando você atualizar tracking_spec, faremos a substituição. Faça uma chamada GET primeiro. Depois, anexe a String associada ao conjunto de eventos offline às tracking_spec existentes. Consulte Gerenciamento de anúncios ou use o Gerenciador de Anúncios. Por exemplo, forneça uma especificação de rastreamento adequada:

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

Para atualizar as especificações de rastreamento dos anúncios:

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Parâmetros

4. Carregar eventos offline

Você deve carregar a transação no prazo de 62 dias após a conversão. Carregue os dados de conversão:

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

Para enviar conversões, faça uma chamada HTTP POST:

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

Parâmetros

Use a mesma upload_tag para agrupar todas as chamadas de API de carregamento de eventos de um lote. Isso ajuda a depurar os carregamentos de eventos. Use esse recurso para carregamentos feitos em mais de uma chamada de API.

Os parâmetros em data incluem:

Por exemplo, você pode carregar informações com o campo data:

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

Use a mesma upload_tag para agrupar todas as chamadas de API de carregamento de eventos de um lote. Isso ajuda a depurar os carregamentos de eventos. Use esse recurso para carregamentos feitos em mais de uma chamada de API.

Chaves de correspondência

O match_keys é um conjunto de identificadores usados para fazer a correspondência de pessoas para atribuição. Consulte Públicos Personalizados de dados de CRM para normalizar e converter os dados em hash. Somente o SHA256 é compatível, e não são aceitos dados não convertidos em hash.

A resposta:

Nos erros, você vê uma exceção com entradas inválidas e o motivo. Corrija os erros ou ignore as linhas de dados com erros e tente a chamada de API novamente.

Visualizar estatísticas de carregamento

Um administrador do Gerenciador de Negócios ou o usuário do sistema que criou o conjunto de eventos offline pode recuperar as estatísticas de carregamento. Além disso, qualquer administrador da ad_account conectada ao conjunto de eventos offline pode ler esses dados.

Para visualizar as estatísticas sobre conjuntos de eventos offline, como entradas válidas e entradas com correspondência:

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

Visualize os detalhamentos diários dos eventos offline em Offline Events Manager no Gerenciador de Negócios. Para detalhamentos mais precisos, faça esta chamada:

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

Parâmetros

Criar conversões personalizadas offline

As conversões personalizadas offline não têm veiculação secundária no momento. Não atribuímos dados de carregamentos de eventos feitos antes da criação da conversão personalizada. Você não pode usar dados de conversão personalizada offline para otimização de veiculação de anúncios. Consulte a referência sobre conversão personalizada.

Para criar uma conversão personalizada usando eventos offline, faça uma chamada POST:

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

Parâmetros:

Se a operação for bem-sucedida, a resposta será a seguinte:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Mensurar com dados personalizados

Use o campo custom_data para criar regras que determinarão se uma conversão conta ou não. Isso é semelhante aos Públicos Personalizados offline. Você pode ter no máximo 40 conversões personalizadas por conta de anúncios.

Por exemplo, inclua a categoria do produto em carregamentos com custom_data:

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

Depois, use custom_data.{YOUR_CUSTOM_PARAM} para criar uma regra de conversão personalizada:

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

Conversões offline para parceiros

Para atribuir eventos de conversão offline ao anúncio do seu cliente, siga estas etapas. As chamadas de API para a maioria destas etapas são iguais a quando alguém gerencia o próprio conjunto de eventos offline e o gerenciamento de campanhas.

1. Parceiro – Criar conjunto de eventos offline
2. Parceiro – Compartilhar um conjunto de eventos com o Gerenciador de Negócios do cliente
3. Cliente – Atribuir permissão de rastreamento offline à conta de anúncios
4. Cliente – Definir o rastreamento offline nos anúncios
5. Parceiro – Carregar eventos offline e visualizar estatísticas
6. Parceiro – Exibir insights sobre anúncios para o cliente

Essas etapas variam dependendo de como suas permissões de parceiro ou agência estão configuradas nas contas de anúncios do cliente:

• Você pode ter todas as contas de anúncios, conjuntos de eventos ou quaisquer outros ativos do seu cliente.
• Você pode ter permissão para os ativos do seu cliente de modo a executar determinadas ações.

Para configurar essas permissões, consulte Ativos do Gerenciador de Negócios.

Parceiro - Compartilhar conjunto de eventos

Compartilhe o conjunto de eventos no Gerenciador de Negócios do seu cliente. Seu cliente poderá então usar o conjunto de eventos para o rastreamento de anúncios.

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

Parâmetros

Cliente – Atribuir permissão de rastreamento offline à conta de anúncios

Compartilhe conjuntos de eventos offline criados por um parceiro com o respectivo cliente. Você precisa ser o administrador do Gerenciador de Negócios ou o usuário administrador do sistema que criou o conjunto de eventos offline para habilitar o rastreamento de anúncios em uma conta de anúncios. Se você for um administrador na conta de anúncios conectada ao conjunto de eventos offline, também poderá fazer isso. Para fazer essa chamada de API, a empresa na chamada deve ter acesso ao conjunto de eventos offline.

É possível atribuir o rastreamento de eventos offline e as permissões de visualização a uma conta de anúncios com esta chamada:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parâmetros

Fornecer identificações externas

Pode haver cenários onde você fornece sua própria identificação externa para representar um cliente e fazer a correspondência com alguém. Para fazer isso, use extern_id de acordo com as diretrizes a seguir.

Os parceiros de dados que passaram pelo processo de correspondência podem usar a identificação do parceiro como a identificação do namespace. Ainda, podem usar o extern_id como o tpid que pertencem a você.

Fornecer somente match_keys

Usamos match_keys para tentar determinar se é possível fazer a correspondência dos dados de conversão compartilhados por você com um usuário da Meta. Caso você forneça match_keys, não poderá fornecer também um parâmetro namespace_id.

Fornecer match_keys e extern_id

Usamos match_keys para tentar encontrar pessoas na Meta e encaminhar mapeamentos de {dataset_id, extern_id} para {facebook_user_id}. Caso você forneça match_keys e extern_id, não poderá fornecer também um parâmetro namespace_id.

Fornecer somente extern_id

Caso você já tenha enviado dados com match_keys e extern_id, a Meta usará {dataset_id, extern_id} para recuperar um {facebook_user_id}.

Fornecer namespace_id

O parâmetro namespace_id é aplicado a toda a chamada de API. Você pode usá-lo para fazer referência a outro conjunto de eventos offline que seja acessível ou pertença a uma empresa ou a uma identificação de perfil de parceiro. Se você já tiver enviado dados com match_keys e extern_id, a Meta usará {namespace_id, extern_id} para recuperar um {facebook_user_id}. Você só deve fornecer uma extern_id por linha de dados.

Insights e atribuição

Consulte os eventos offline atribuídos a um anúncio visto ou clicado por alguém. Atribuímos conversões offline após mais de um dia. Isso significa que é preciso configurar sua janela de atribuição para 28d_view ou action_attribution_windows=['28d_view']'. Caso contrário, você não verá conversões em relatórios. Consulte API de Insights e o Guia de Insights.

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

Parâmetros

Os resultados têm esta aparência:

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

Por exemplo, para visualizar a atribuição:

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

O resultado fica assim:

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Opções de processamento de dados para usuários nos EUA

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

Saiba mais sobre as opções de processamento de dados.