Offline Conversions API

Offline Conversions API позволяет отправлять события офлайн-конверсий, чтобы следить, сколько клиентов перед конверсией посмотрели рекламу Meta или нажали ее.

Прежде чем начать

Чтобы использовать этот API, вам понадобятся:

1. Meta Business Manager

Если у вас ещё нет аккаунта, создайте его.

2. ID приложения Meta

Требуется для доступа к Marketing API. Чтобы создать приложение Meta, выполните следующие действия.

• Откройте Business Manager и выберите Настройки компании.
• Выберите Приложения.
• Нажмите Добавить новое приложение и следуйте инструкциям.

3. Проверка приложения и разрешения

Правила проверки приложения и необходимые разрешения зависят от способа реализации API.

4. Системный пользователь и маркер в Business Manager

Имея права доступа системного пользователя, ваше приложение сможет отправлять в Meta данные через API. Чтобы ее создать, выполните перечисленные ниже действия.

• Откройте Business Manager и выберите Настройки компании.
• Выберите Системные пользователи.
• Нажмите Добавить нового системного пользователя.
• Выберите роль Системный пользователь-администратор.

Маркер доступа предоставляет доступ к данным Meta. Чтобы создать маркеры доступа системного пользователя, выполните перечисленные далее действия.

• Откройте Business Manager и выберите Настройки компании.
• Выберите Системные пользователи.
• Выберите системного пользователя и нажмите Сгенерировать маркер.
• Выберите приложение и задайте для настройки Область действия значение ads_management.

5. Рекламный аккаунт

Для проведения рекламных кампаний на Meta необходим рекламный аккаунт. Инструкции по его созданию см. в статье Marketing API или Справочный центр для бизнеса: О настройках компании в Meta Business Manager.

6. Доступ системного пользователя к рекламному аккаунту

Предоставьте системному пользователю доступ к рекламному аккаунту.

• Откройте Business Manager и выберите Настройки компании.
• Выберите Системные пользователи.
• Выберите системного пользователя и нажмите Назначить объекты.
• Выберите свой рекламный аккаунт.

7. Группа офлайн-событий

Это загружаемые файлы, которые содержат данные об офлайн-конверсиях. Чтобы настроить атрибуцию событий, при создании рекламы задайте в параметре tracking_specID группы офлайн-событий. Затем вы сможете создавать группы событий, просматривать статистику импортируемых данных, удалять и изменять эти данные в Business Manager.

В старых версиях в Business Manager можно было выполнять операции создания, чтения, изменения и удаления данных для групп офлайн-событий, чтобы делиться такими группами с другими объектами.

Загрузка данных событий

Чтобы создавать группы офлайн-событий и загружать или просматривать данные по ним, нужны определенные права доступа. Они также позволяют назначать разрешения на эти действия рекламному аккаунту. Необходимые права есть у следующих пользователей:

• администратор Business Manager;
• системный пользователь-администратор, создавший соответствующую группу офлайн-событий;
• администратор рекламного аккаунта ad_account, связанного с этой группой офлайн-событий.

Подробнее см. в справке по группам офлайн-событий конверсии.

1. Создание группы офлайн-событий

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

Выполните запрос 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

Ответ будет содержать id группы событий:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Параметры

2. Назначение разрешений для рекламного аккаунта.

Чтобы назначить рекламному аккаунту разрешения на отслеживание и чтение, выполните такой запрос:

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

Параметры

3. Настройка отслеживания рекламы

Когда вы обновляете tracking_spec, мы переопределяем эту спецификацию. Сначала выполните запрос GET, а затем добавьте связанную строку String для группы офлайн-событий к имеющейся спецификации tracking_spec. Обратитесь к разделу Управление рекламой или воспользуйтесь Ads Manager. Например, укажите соответствующие параметры отслеживания:

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>

Чтобы обновить параметры отслеживания рекламы, выполните такой запрос:

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>}]

Параметры

4. Загрузка офлайн-событий.

Вы должны загрузить транзакцию в течение 62 дней после конверсии. Загрузите данные конверсии:

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

Чтобы отправить конверсии, выполните запрос 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

Параметры

Чтобы объединить вызовы API для загрузки событий, используйте для них всех одинаковый upload_tag. Это поможет выполнить отладку загрузки событий. Рекомендуем делать так, если загрузка событий выполняется за несколько вызовов API.

Параметры data:

Например, в поле 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,
    }
  ],
}

Чтобы объединить вызовы API для загрузки событий, используйте для них один и тот же upload_tag. Это поможет выполнить отладку загрузки событий. Рекомендуем делать так в тех случаях, когда загрузка событий выполняется за несколько вызовов API.

Ключи сопоставления

match_keys — это набор ID для сопоставления людей с целью атрибуции. Инструкции по нормализации и хэшированию данных см. в этом разделе. Поддерживается только алгоритм SHA-256. Нехэшированные данные не принимаются.

Ответ:

При появлении ошибок будет возвращено исключение с указанием недействительных записей и причины. Исправьте ошибки или пропустите строки данных с ошибками и повторно выполните вызов API.

Просмотр статистики загрузки

Извлечь статистику загрузки может администратор Business Manager или системный пользователь, который создал группу офлайн-событий. Кроме того, эти данные может прочитать любой администратор рекламного аккаунта ad_account, связанного с группой офлайн-событий.

Чтобы просмотреть статистику по группам офлайн-событий, например действительные и сопоставленные записи, выполните следующий вызов:

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

Ежедневные разбивки офлайн-событий можно посмотреть в Offline Events Manager в Business Manager. Чтобы получить более подробные разбивки, выполните следующий вызов:

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

Параметры

Создание специально настроенных офлайн-конверсий

Сейчас специально настроенные офлайн-конверсии не поддерживают обратное заполнение. Мы не учитываем данные о загрузках событий, которые произошли до создания специально настроенной конверсии. Использовать данные о специально настроенных офлайн-конверсиях для оптимизации показа рекламы невозможно. Подробнее см. в справке по специально настроенным конверсиям.

Чтобы создать специально настроенную конверсию с помощью офлайн-событий, выполните запрос 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

Параметры:

Ответ в случае успеха:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Измерение на основании пользовательских данных

С помощью поля custom_data вы можете создавать правила, которые позже будут определять, засчитывается ли конверсия. Это похоже на пользовательские офлайн-аудитории. У одного рекламного аккаунта может быть не более 40 специально настроенных конверсий.

Например, добавьте в загрузки категорию товаров, используя поле 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",
    },
  },
]

Затем с помощью custom_data.{YOUR_CUSTOM_PARAM} создайте правило специально настроенной конверсии:

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"

Офлайн-конверсии для партнеров

Чтобы соотнести события офлайн-конверсии с рекламой клиента, следуйте инструкциям ниже. Для большинства этих действий потребуются те же вызовы API, что и при управлении собственной группой офлайн-событий и кампанией.

1. Партнер — создание группы офлайн-событий.
2. Партнер — предоставление доступа к группе событий аккаунту Business Manager клиента.
3. Клиент — назначение рекламному аккаунту разрешения на отслеживание офлайн.
4. Клиент — настройка отслеживания офлайн для рекламы.
5. Партнер — загрузка офлайн-событий, просмотр статистики.
6. Партнер — отображение статистики рекламы для клиента.

Перечень действий зависит от того, как настроены разрешения для партнера или агентства в рекламных аккаунтах клиента:

• вам могут принадлежать все рекламные аккаунты, группы событий или другие ресурсы клиента;
• у вас может быть разрешение на выполнение определенных действий с объектами клиента.

Инструкции по настройке этих разрешений см. в этом разделе.

Партнер — предоставление доступа к группе событий

Предоставьте доступ к группе событий аккаунту Business Manager клиента. Затем, используя эту группу событий, ваш клиент сможет отслеживать рекламу.

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

Параметры

Клиент — назначение рекламному аккаунту разрешения для отслеживания офлайн

Предоставьте клиенту доступ к группам офлайн-событий, созданным партнером. Чтобы включить отслеживание рекламы для рекламного аккаунта, необходимо быть администратором Business Manager или системным пользователем-администратором, который создал группу офлайн-событий. Если вы администратор рекламного аккаунта, связанного с группой офлайн-событий, вы тоже можете сделать это. Чтобы выполнить этот вызов API, у компании должен быть доступ к группе офлайн-событий.

Чтобы назначить разрешения на просмотр и отслеживание офлайн-событий рекламному аккаунту, выполните следующий вызов:

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

Параметры

Предоставление сторонних ID

Иногда бывает нужно предоставить собственный внешний ID, чтобы представить клиента и сопоставить его с кем-то. Воспользуйтесь для этого extern_id и следуйте инструкциям ниже.

Партнеры по сбору данных, которые прошли процесс сопоставления, могут использовать ID партнера в качестве ID пространства имен и extern_id как tpid.

Предоставьте только match_keys

На основании match_keys мы определяем, можно ли сопоставить предоставленные вами данные конверсии с пользователем Meta. Если вы предоставили match_keys, то не сможете предоставить параметр namespace_id.

Предоставьте match_keys и extern_id

С помощью match_keys мы находим людей в Meta и отправляем сопоставления {dataset_id, extern_id} с {facebook_user_id}. Если вы предоставили match_keys и extern_id, то не сможете предоставить параметр namespace_id.

Предоставьте только extern_id

Если вы уже отправили данные с match_keys и extern_id, Meta извлекает {facebook_user_id} с помощью {dataset_id, extern_id}.

Предоставьте namespace_id

Параметр namespace_id применяется ко всему вызову API. С его помощью вы можете указать другую группу офлайн-событий, которая доступна для ID профиля компании или партнера либо принадлежит ему. Если вы уже отправили данные с match_keys и extern_id, Meta с помощью {namespace_id, extern_id} извлекает {facebook_user_id}. Указывайте только один extern_id на каждую строку данных.

Статистика и атрибуция

Просматривайте офлайн-события, относящиеся к объявлению, которое кто-то просмотрел или нажал. Офлайн-конверсии засчитываются не раньше, чем через один день. Это означает, что вам необходимо задать для окна атрибуции значение 28d_view или action_attribution_windows=['28d_view']'. В противном случае вы не увидите конверсии в отчетах. Подробнее см. в описании Insights API и в руководстве по статистике.

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

Параметры

Результаты будут выглядеть следующим образом:

{
  "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
        },
      ],
      ...
    }
  ]
}

Например, чтобы посмотреть атрибуцию, выполните такой вызов:

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

Результат выглядит следующим образом:

{
  "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"
    }
  }
}

Параметры обработки данных для пользователей в США

{
    "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
        }
    ]
}

Подробнее о вариантах обработки данных см. в этой статье.