Объявления из каталога Advantage+

Реклама гостиниц — каталоги и лента

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

Создать каталог гостиниц и управлять им можно в Commerce Manager.

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

  1. Создайте каталог гостиниц.
  2. Создайте группы товаров на основе каталога.
  3. Свяжите каталог с источниками событий.

Ленты гостиниц: загрузка гостиниц на Facebook

Лента гостиниц — это файл с вашими гостиницами. Каждая строка или элемент в этом файле представляет собой одну гостиницу. Вы можете использовать одну или несколько лент гостиниц, при условии, что все ленты вместе составляют весь ваш ассортимент.

Поддерживаемые форматы лент гостиниц

CSV

Пример файла .csv | Пример файла .tsv (упрощенный) | Пример файла .tsv (стиль JSON)

  • Первая строка должна содержать список выбранных имен полей в том порядке, в котором будут указаны значения. В последующих строках будут представлены соответствующие значения по каждой гостинице.
  • Поля, содержащие пробелы или запятые, должны заключаться в двойные кавычки ("").
  • Вложенные поля и поля с несколькими значениями (например, address, neighborhood или image) могут представляться значениями в кодировке JSON либо группой "упрощенных" столбцов с простым текстом, обозначенных с использованием синтаксиса пути JSON (например, address.city, neighborhood[0], image[0].url, image[0].tag[0], image[0].tag[1]). Оба способа записи можно использовать в одном и том же файле.

XML

Пример файла XML

  • Корневой XML-узел <listings> включает в себя набор узлов <listing>, каждый из которых представляет гостиницу.
  • Файл должен начинаться с допустимого тега объявления <?xml.

Анализатор лент автоматически определяет кодировки UTF8, UTF16 или UTF32. При обнаружении неожиданной последовательности байтов используется кодировка по умолчанию — LATIN1. Текст в значениях полей может быть на любом языке, но названия правил должны быть написаны на английском языке в точности, как показано ниже.

Поддерживаемые поля — реклама гостиниц

Для позиций, добавляемых в каталог товаров, поддерживаются перечисленные ниже поля.

Список полей для локализованных каталогов см. здесь.

Имя и тип поляОписание

hotel_id

Тип: строка

Обязательный параметр.

Максимальная длина: 100.

Уникальный идентификатор гостиницы в каталоге. Он будет сопоставляться с идентификаторами content_ids в событиях приложения и пикселя, связанных с hotel. Совет. Чтобы проверка прошла успешно, не используйте в этом уникальном идентификаторе пробелы. ID не должны повторяться.

Пример: FB_hotel_1234.

room_id

Тип: строка

Обязательно при добавлении информации о гостиничных номерах.

Введите уникальный ID для типа гостиничного номера. Максимальная длина: 100. Пример: FB_hotel_room_1234.

name

Тип: строка

Обязательный параметр.

Наиболее употребительное название гостиницы.

Пример: Facebook Hotel.

description

Тип: строка

Обязательный параметр.

Максимальный размер: 5 000.

Краткое описание гостиницы.

Пример: Only 30 minutes away from San Francisco..

checkin_date

Тип: строка

Обязательно при добавлении информации о гостиничных номерах.

Дата заезда в гостиницу. Можно добавить до 180 дней начиная со дня загрузки ленты. Используется стандарт ISO-8601 (YYYY-MM-DD).

Пример: 2017-08-01.

length_of_stay

Тип: строка

Обязательно при добавлении информации о гостиничных номерах.

Количество ночей проживания в гостинице.

Пример: 7.

base_price

Тип: строка

Обязательно при добавлении информации о гостиничных номерах.

Базовая цена за ночь в гостинице. Значение необходимо указывать вместе с валютой (например, USD для долларов США). Используйте денежный формат с кодом валюты по стандарту ISO через пробел.

Пример: 199.00 EUR.

price

Тип: строка

Обязательно при добавлении информации о гостиничных номерах.

Общая стоимость проживания в гостинице с учетом checkin_date и length_of_stay. Используйте денежный формат с кодом валюты по стандарту ISO через пробел.

Пример: 1393.00 USD.

tax

Тип: строка

Обязательно при добавлении информации о гостиничных номерах.

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

Пример: 14.00 USD.

fees

Тип: строка

Обязательно при добавлении информации о гостиничных номерах.

Комиссии, применимые к стоимости. Используйте денежный формат с кодом валюты по стандарту ISO через пробел.

Пример: 253.00 USD.

url

Тип: строка

Обязательный параметр.

Ссылка на внешний сайт, на котором можно забронировать номер в гостинице. Вы также можете указать URL на уровне рекламы при помощи template_url_spec. URL на уровне рекламы имеют приоритет над URL в ленте.

Пример: https://www.facebook.com/hotel.

image[0].url

Тип: объект

См. раздел Параметры объектов image.

image[0].tag

Тип: объект

См. раздел Параметры объектов image.

brand

Тип: строка

Обязательный параметр.

Бренд сети гостиниц.

Пример: Hilton.

address

Тип: объект

См. раздел Параметры объектов address.

neighborhood[0]

Тип: строка

Обязательный параметр.

Максимальное количество районов: 20.

Район, где расположена гостиница. Если вы хотите указать более одного района, добавьте по столбцу для каждого района и используйте в названии каждого столбца синтаксис пути JSON, чтобы указать количество районов.

Пример: Belle Haven.

latitude

Тип: число с плавающей запятой

Обязательный параметр.

Географическая широта гостиницы.

Пример: 37.484100.

longitude

Тип: число с плавающей запятой

Обязательный параметр.

Географическая долгота гостиницы.

Пример: -122.148252.

sale_price

Тип: строка

Необязательный параметр.

Цена со скидкой за сутки в гостинице с учетом checkin_date и length_of_stay. Используйте, чтобы предлагать скидки от обычной цены. Значение необходимо указывать вместе с валютой (например, USD для долларов США). Значение sale_price для гостиниц должно быть меньше значения base_price. Используйте денежный формат с кодом валюты по стандарту ISO через пробел.

Пример: 149.00 USD.

guest_ratings.score

Тип: объект

См. раздел Параметры объектов guest_ratings.

guest_ratings.rating_system

Тип: объект

См. раздел Параметры объектов guest_ratings.

star_rating

Тип: число с плавающей запятой

См. раздел Параметры объектов guest_ratings.

loyalty_program

Тип: строка

Необязательный параметр.

Программа лояльности, в которой людям начисляются баллы за пребывание в гостинице.

Пример: Premium program.

margin_level

Тип: целое число

Необязательный параметр.

Индикатор прибыльности гостиницы со значением от 1 до 10.

Пример: 9.

phone

Тип: строка

Необязательный параметр.

Основной номер телефона гостиницы.

Пример: +61 296027455.

applink

Тип: объект

Необязательный параметр.

Добавьте глубокую ссылку на страницу сведений о гостинице в мобильном приложении, используя App Links. Вы можете указать глубокие ссылки (в порядке убывания значимости):

  1. На уровне рекламы при помощи template_url_spec.
  2. В ленте, используя объект Applink.
  3. Путем добавления на сайт метатегов App Links.

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

priority

Тип: целое число

Необязательный параметр.

Индикатор приоритета гостиницы от 0 (самый низкий приоритет) до 5 (самый высокий приоритет). Пример: 5.

category

Тип: строка

Необязательный параметр.

Тип объекта недвижимости. Можно использовать любые внутренние категории. Пример: Resort, Day Room.

number_of_rooms

Тип: целое число

Необязательный параметр.

Общее количество номеров в объявлении.

Пример: 150.

status

Тип: строка

Контролирует, активна позиция в каталоге или она находится в архиве. Люди могут смотреть в вашей рекламе, магазинах и на других каналах только активные позиции. Поддерживаемые значения: active, archived. По умолчанию все позиции активны. Подробнее о позициях в архиве см. в этой статье.


Пример: active.


Примечание. Некоторые партнерские платформы могут синхронизировать позиции со статусом Перенос, который аналогичен статусу archived.

Раньше это поле называлось visibility. Предыдущее название до сих пор поддерживается, но мы рекомендуем использовать новое.

custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4

Тип: строка

Максимальное количество символов: 100.

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


Пример: Summer Sale.

Это поле поддерживается дополнительными полями.

custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4

Тип: целое число

Вы можете использовать до пяти пользовательских полей с любой дополнительной числовой информацией для фильтрации товаров при создании групп. Это поле позволяет фильтровать товары по числовым диапазонам (is greater than (больше) и is less than (меньше)) при создании групп. Например, в этом поле можно указать год производства товара и с помощью фильтра добавить в группу определенный диапазон.


Поле поддерживает целые числа в диапазоне от 0 до 4 294 967 295. Не поддерживаются отрицательные числа, числа с десятичным разделителем и запятые, например –2, 5.5 или 10,000.


Пример: 2022.

Параметры объектов image


Имя и тип поляОписание

url

Тип: строка

Обязательный параметр.

Максимальное количество элементов: 20.

URL изображения гостиницы, которое будет показываться в рекламе. Изображения должны соответствовать следующим условиям:

  • Все изображения должны иметь формат .jpg, .gif или .png.

  • Для рекламы с кольцевой галереей и рекламных подборок: изображения выводятся в квадратном формате (1:1). Минимальный размер изображения — 500 × 500 пикселей. Для оптимального качества рекомендуется размер 1 024 x 1 024 пикселей.

  • Для рекламы с одним изображением: изображения выводятся с соотношением сторон 1,91:1. Минимальный размер изображения — 500 x 500 пикселей. Для оптимального качества рекомендуется размер 1 200 x 628 пикселей.

  • Если изображений несколько, добавьте по столбцу для каждого изображения и используйте в названии каждого столбца синтаксис пути JSON, чтобы указать количество изображений.

Пример: image[0].url; image[1].url.

Пример: https://www.facebook.com/facebook_hotel.jpg.

tag

Тип: строка

Необязательный параметр.

Добавленная к изображению метка с его описанием. С одним изображением может быть связано несколько меток.

Примеры: Fitness Center, Swimming Pool, suite.

Метка INSTAGRAM_STANDARD_PREFERRED позволяет рекламодателю отметить определенное изображение в ленте как используемое по умолчанию в Instagram. В этой метке учитывается регистр.


Параметры объектов address

Вложенные поля и поля со множественными значениями, например address, могут представляться с использованием значений в кодировке JSON либо в виде группой "упрощенных" столбцов с простым текстом, обозначенных с помощью синтаксиса пути JSON (например, address.region). Оба способа записи можно использовать в одном и том же файле.


Имя и тип поляОписание

addr1 (address.addr1)

Тип: объект

Обязательный параметр.

Основой адрес гостиницы.

Пример: 1600 Pennsylvania Avenue.

address.addr2

Тип: объект

Необязательный параметр.

Дополнительный адрес гостиницы.

Пример: Apartment 1.

address.addr3

Тип: объект

Необязательный параметр.

Третий адрес гостиницы.

Пример: Downstairs.

address.city_id (city_id)

Тип: строка

Необязательный параметр.

Значение, которое будет использоваться в URL глубокой ссылки (template_url) в рекламном креативе.

Пример: 12345.

address.city (city)

Тип: строка

Обязательный параметр.

Город, в котором находится гостиница.

Пример: New York.

address.region (region)

Тип: строка

Обязательный параметр.

Штат, область, провинция и т. п., где находится гостиница.

Пример: California.

address.country (country)

Тип: строка

Обязательный параметр.

Страна, в которой находится гостиница.

Пример: United States.

address.postal_code (postal_code)

Тип: строка

Обязательное поле для стран, в которых используются почтовые индексы.

Почтовый индекс гостиницы.

Примеры: 94125, NW1 3FG.

Параметры объектов guest_ratings


Имя и тип поляОписание

guest_ratings.score (score)

Тип: объект

Необязательный параметр.

Общее количество людей, оставивших отзыв об этой гостинице. Если задано, необходимо также указать score, max_score, number_of_reviewers и rating_system.

Пример: 9.0/10.

guest_ratings.number_of_reviewers (number_of_reviewers) Тип: целое число

Необязательный параметр.

Общее количество людей, оценивших гостиницу.

Пример: 5287.

guest_ratings.rating_system (rating_system)

Тип: строка

Необязательный параметр.

Система, используемая для сбора отзывов.

Примеры: Expedia, TripAdvisor.

max_score

Тип: целое число

Обязательный параметр.

Максимальное значение для рейтинга гостиницы. Должно быть не менее нуля и не более 100.

Пример: 10.

Создание гостиниц и управление ими через API

С помощью Hotel API можно добавлять гостиницы в каталог, изменять и удалять их. Подробнее см. в справке по Hotel API.

Следующие разделы относятся только к управлению каталогами через этот API.

Создание каталога гостиниц через API

Справочная документация

Каталог — это контейнер для всех ваших гостиниц. Чтобы использовать API каталога, убедитесь, что у вас есть нужный уровень доступа к Marketing API и вы приняли пользовательское соглашение при создании первого каталога в Business Manager.

Чтобы создать каталог для рекламы гостиниц, установите для параметра vertical значение hotels:

curl -X POST \
  -F 'name="Test Hotel Catalog"' \
  -F 'vertical="hotels"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v10.0/BUSINESS_ID/owned_product_catalogs

Загрузка лент гостиниц через API

После создания каталога нужно загрузить ленты гостиниц на Facebook. Создайте с помощью API объект ленты для каждой ленты, которую нужно загрузить. Поддерживаются как загрузка по расписанию, так и прямая.

Фильтрация каталога для создания группы гостиниц

Справочная документация

Группа гостиниц — это подмножество элементов вашего каталога. Для настройки рекламы гостиниц необходима хотя бы одна такая группа. Поэтому ее нужно создать.

Для создания группы гостиниц используются фильтры в каталоге. Например, вы можете создать группу из всех гостиниц, значение star_rating у которых превышает 3. Примечание. Создать группу гостиниц можно и без фильтров. В этом случае она будет содержать все гостиницы из каталога.

Вот как можно создать группу со всеми гостиницами, в поле brand которых содержится текст "sample brand":

curl -X POST \
  -F 'name="Test Hotel Set"' \
  -F 'filter={
       "brand": {
         "i_contains": "sample brand"
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<PRODUCT_CATALOG_ID>/product_sets
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const ProductCatalog = bizSdk.ProductCatalog;
const ProductSet = bizSdk.ProductSet;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<PRODUCT_CATALOG_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'Test Hotel Set',
  'filter' : {'brand':{'i_contains':'sample brand'}},
};
const product_sets = (new ProductCatalog(id)).createProductSet(
  fields,
  params
);
logApiCallResult('product_sets api call complete.', product_sets);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\ProductCatalog;
use FacebookAds\Object\ProductSet;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<PRODUCT_CATALOG_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'Test Hotel Set',
  'filter' => array('brand' => array('i_contains' => 'sample brand')),
);
echo json_encode((new ProductCatalog($id))->createProductSet(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.productcatalog import ProductCatalog
from facebook_business.adobjects.productset import ProductSet
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<PRODUCT_CATALOG_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'Test Hotel Set',
  'filter': {'brand':{'i_contains':'sample brand'}},
}
print ProductCatalog(id).create_product_set(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<PRODUCT_CATALOG_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new ProductCatalog(id, context).createProductSet()
      .setName(\"Test Hotel Set\")
      .setFilter(\"{\\"brand\\":{\\"i_contains\\":\\"sample brand\\"}}\")
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<PRODUCT_CATALOG_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

product_catalog = FacebookAds::ProductCatalog.get(id)
product_sets = product_catalog.product_sets.create({
    name: 'Test Hotel Set',
    filter: {'brand':{'i_contains':'sample brand'}},
})
Open In Graph API Explorer

Параметр filter может содержать следующие операторы и данные:

ОператорыТип фильтра

i_contains

Содержит подстроку. Оператор нечувствителен к регистру.

i_not_contains

Не содержит подстроку. Оператор нечувствителен к регистру.

contains

Содержит подстроку. Оператор нечувствителен к регистру.

not_contains

Не содержит подстроку. Оператор нечувствителен к регистру.

eq

Равно. Оператор нечувствителен к регистру.

neq

Не равно. Оператор нечувствителен к регистру.

lt

Меньше. Только числовые поля.

lte

Меньше или равно. Только числовые поля.

gt

Больше. Только числовые поля.

gte

Больше или равно. Только числовые поля.

ДанныеФильтруемые данные

hotel_id

Уникальный идентификатор гостиницы в каталоге.

brand

Бренд сети гостиниц.

base_price_amount

Базовая цена за ночь в гостинице. Цена указывается в дробных денежных единицах. Например, 4 999 означает 49,99 долл.

sale_price_amount

Цена со скидкой за ночь в гостинице. Цена указывается в дробных денежных единицах. Например, 4 999 означает 49,99 долл.

currency

Валюта.

city

Город, в котором находится гостиница.

country

Страна, в которой находится гостиница.

name

Наиболее употребительное название гостиницы.

star_rating

Количество звезд у гостиницы. Допустимы значения от 1 до 5, кратные 0,5.