Anúncios de Catálogo Advantage+

Anúncios de hotel – Catálogos e feed

Para promover seu inventário de hotéis no Facebook, compartilhe informações sobre seus hotéis com o Facebook. Para isso, crie um catálogo de hotéis e preencha-o com hotéis. É possível preencher o catálogo e atualizá-lo de duas maneiras:

Crie e gerencie catálogos de hotéis no Gerenciador de Comércio.

Para usar a API no gerenciamento do seu catálogo, faça o seguinte:

  1. Crie um catálogo de hotéis.
  2. Crie conjuntos de produtos a partir do seu catálogo de hotéis.
  3. Associe o catálogo às origens de evento.

Feeds de hotéis – Carregue hotéis no Facebook

Um feed de hotéis é um arquivo com seu inventário de hotéis. Cada linha ou item no arquivo representa um único hotel. Você pode usar um ou mais feeds de hotel, contanto que todos os feeds reunidos contenham seu inventário de hotéis completo.

Formatos de feed de hotéis compatíveis

CSV

Exemplo de CSV | Exemplo de TSV (simples) | Exemplo de TSV (estilo JSON)

  • A primeira linha deve listar os nomes de campos escolhidos na ordem que os valores são fornecidos. As linhas seguintes fornecem os valores correspondentes para cada hotel.
  • Os campos com espaços em branco ou vírgulas devem ficar entre "aspas duplas".
  • Os campos aninhados ou com diversos valores, como address, neighborhood ou image, podem ser representados por valores codificados em JSON ou por um conjunto de colunas de texto sem formatação "simples" rotuladas com a sintaxe de caminho JSON, por exemplo, address.city, neighborhood[0], image[0].url, image[0].tag[0] e image[0].tag[1]. As duas convenções podem ser usadas alternadamente no mesmo arquivo.

XML

Exemplo de XML

  • Um nó de XML <listings> raiz inclui um conjunto de nós <listing>, cada um representando um hotel.
  • O arquivo deve iniciar por uma tag de declaração <?xml válida.

O analisador de feed detecta automaticamente codificações de texto UTF8, UTF16 ou UTF32 e adota LATIN1 como padrão caso encontre sequências de byte inesperadas. É possível fornecer texto nos valores de campo em qualquer idioma, mas os nomes de campo devem ser fornecidos exatamente como mostrado abaixo, em inglês.

Campos compatíveis – Anúncios de hotel

Os campos compatíveis a seguir foram desenvolvidos para itens que você adiciona ao seu catálogo de produtos.

Para catálogos localizados, veja campos compatíveis para anúncios de hotéis.

Campo e tipoDescrição

hotel_id

Tipo: string

Obrigatório.

Comprimento máximo: 100

O identificador exclusivo do hotel no catálogo. Será associado a todos os content_ids fornecidos no app do hotel e nos pixels de eventos. Dica: para aumentar o desempenho, evite usar espaços nesse campo de identificador único. Não utilize números de identificação duplicados.

Exemplo: FB_hotel_1234

room_id

Tipo: string

Obrigatório ao adicionar informações sobre o quarto de hotel.

Insira uma identificação única para o tipo de quarto do hotel. Máximo de caracteres: 100. Exemplo: FB_hotel_room_1234

name

Tipo: string

Obrigatório.

O nome mais comum do hotel.

Exemplo: Facebook Hotel

description

Tipo: string

Obrigatório.

Tamanho máximo: 5.000

Uma breve descrição do hotel.

Exemplo: Only 30 minutes away from San Francisco.

checkin_date

Tipo: string

Obrigatório ao adicionar informações sobre o quarto de hotel.

Data de check-in para a estadia no hotel. Adicione até 180 dias a partir da data de carregamento do feed. Usa o padrão ISO-8601 (YYYY-MM-DD).

Exemplo: 2017-08-01

length_of_stay

Tipo: string

Obrigatório ao adicionar informações sobre o quarto de hotel.

Número de noites da estadia no hotel.

Exemplo: 7

base_price

Tipo: string

Obrigatório ao adicionar informações sobre o quarto de hotel.

O preço-base do pernoite no quarto de hotel. Inclua o tipo de moeda no preço (por exemplo, USD no caso de dólar americano). Formate o preço como o custo seguido pelo código ISO da moeda, com um espaço entre o custo e a moeda.

Exemplo: 199.00 EUR

price

Tipo: string

Obrigatório ao adicionar informações sobre o quarto de hotel.

Preço total da estadia no hotel, com base em checkin_date e length_of_stay. Formate o preço como o custo seguido pelo código ISO da moeda, com um espaço entre o custo e a moeda.

Exemplo: 1393.00 USD

tax

Tipo: string

Obrigatório ao adicionar informações sobre o quarto de hotel.

A alíquota de imposto aplicável para o preço. Formate o preço como o custo seguido pelo código ISO da moeda, com um espaço entre o custo e a moeda.

Exemplo: 14.00 USD

fees

Tipo: string

Obrigatório ao adicionar informações sobre o quarto de hotel.

Taxas aplicáveis ao preço. Formate o preço como o custo seguido pelo código ISO da moeda, com um espaço entre o custo e a moeda.

Exemplo: 253.00 USD

url

Tipo: string

Obrigatório.

Link do site externo onde é possível reservar um quarto de hotel. Também é possível especificar uma URL no nível do anúncio usando template_url_spec. As URLs no nível do anúncio têm prioridade sobre as URLs no feed.

Exemplo: https://www.facebook.com/hotel

image[0].url

Tipo: objeto

Consulte Parâmetros do objeto Image.

image[0].tag

Tipo: objeto

Consulte Parâmetros do objeto Image.

brand

Tipo: string

Obrigatório.

Nome da marca da rede de hotéis.

Exemplo: Hilton

address

Tipo: objeto

Consulte Parâmetros do objeto Address.

neighborhood[0]

Tipo: string

Obrigatório.

Máximo de bairros permitidos: 20

Bairro onde o hotel está localizado. Se houver mais de um bairro, inclua colunas adicionais e use a sintaxe de caminho JSON em cada nome de coluna para indicar o número de bairros.

Exemplo: Belle Haven

latitude

Tipo: float

Obrigatório.

Latitude da localização do hotel.

Exemplo: 37.484100

longitude

Tipo: float

Obrigatório.

Longitude da localização do hotel.

Exemplo: -122.148252

sale_price

Tipo: string

Opcional.

Preço total da estadia no hotel, com base na checkin_date e na length_of_stay. Use essa informação para divulgar descontos sobre o preço normal do hotel. Inclua o tipo de moeda no preço (por exemplo, USD no caso de dólar americano). Verifique se o sale_price do hotel está mais baixo que o base_price. Formate o preço como o custo seguido pelo código ISO da moeda, com um espaço entre o custo e a moeda.

Exemplo: 149.00 USD

guest_ratings.score

Tipo: objeto

Consulte Parâmetros do objeto Guest Rating.

guest_ratings.rating_system

Tipo: objeto

Consulte Parâmetros do objeto Guest Rating.

star_rating

Tipo: float

Consulte Parâmetros do objeto Guest Rating.

loyalty_program

Tipo: string

Opcional.

O programa de fidelidade que você usa para obter pontos pela sua estadia no hotel.

Exemplo: Premium program

margin_level

Tipo: número inteiro

Opcional.

Indicador de lucratividade do hotel. Valor entre 1 e 10.

Exemplo: 9

phone

Tipo: string

Opcional.

Telefone principal do hotel.

Exemplo: +61 296027455

applink

Tipo: objeto

Opcional.

Deep link que encaminha diretamente para a página de detalhes do hotel no seu app para celular usando App Links. Você pode especificar deep links (em ordem de prioridade, da mais alta para a mais baixa):

  1. No nível do anúncio, usando template_url_spec.
  2. Aqui no feed, via objeto Applink.
  3. Ao adicionar metatags de App Link ao seu site.

Saiba mais sobre deep links de produtos.

priority

Tipo: número inteiro

Opcional.

Um indicador da prioridade do hotel. Valor entre 0 (prioridade mais baixa) e 5 (prioridade mais alta). Exemplo: 5

category

Tipo: string

Opcional.

O tipo de propriedade. A categoria pode apresentar todos os tipos de descrição interna desejados. Exemplo: Resort, Day Room

number_of_rooms

Tipo: número inteiro

Opcional.

Número total de quartos/unidades nos classificados do hotel.

Exemplo: 150

status

Tipo: string

Controla se um item está ativo ou foi arquivado no seu catálogo. Apenas itens ativos podem ser vistos por pessoas nos seus anúncios, lojas ou outros canais. Valores compatíveis: active, archived. Os itens estão ativos por padrão. Saiba mais sobre como arquivar itens.


Exemplo: active


Observação: algumas plataformas parceiras como a Shopify podem sincronizar itens ao seu catálogo com um status chamado staging. Ele se comporta da mesma forma que archived.

Esse campo era chamado anteriormente de visibility. Apesar da compatibilidade do antigo nome desse campo, recomendamos que você use o novo nome.

custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4

Tipo: string

Limite máximo de caracteres: 100

Até cinco campos personalizados para as informações adicionais que deseja usar para filtrar os itens ao criar conjuntos. Por exemplo, você pode usar um campo personalizado para indicar todos os quartos que fazem parte de uma promoção de verão e depois filtrar esses itens para formar um conjunto. Esse campo é compatível com qualquer valor de texto, incluindo números.


Exemplo: Summer Sale

Esse campo é compatível com feeds complementares.

custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4

Tipo: número inteiro

Até cinco campos personalizados para informações numéricas adicionais que você quer usar para filtrar itens ao criar conjuntos. Esse campo permite que você filtre por intervalos de números (é maior que e é menor que) ao criar um conjunto. Por exemplo, é possível usar esse campo para indicar o ano em que o hotel foi inaugurado e depois filtrar um intervalo de anos específico no conjunto.


Esse campo é compatível com números inteiros entre 0 e 4294967295. Não é possível usar números negativos, vírgulas ou pontos, como -2, 5,5 ou 10.000.


Exemplo: 2022

Parâmetros do objeto Image


Nome e tipo de campoDescrição

url

Tipo: string

Obrigatório.

Máximo de itens: 20

Link de URL da imagem do item que será exibido nos anúncios. Siga estas especificações de imagem:

  • Todas as imagens precisam estar em formato JPG, GIF ou PNG.

  • Para anúncios em carrossel e em coleções: as imagens são exibidas no formato quadrado (1:1). O tamanho mínimo da imagem é 500 x 500 px. Recomendamos 1.024 x 1.024 px para garantir melhor qualidade.

  • Para anúncios de imagem única: a imagem é exibida na taxa de proporção 1.91:1. O tamanho mínimo da imagem é 500 x 500 px. Recomendamos 1.200 x 628 px para garantir a melhor qualidade.

  • Se houver mais de uma imagem, adicione colunas extras para cada uma e use a sintaxe de caminho JSON em cada nome de coluna para indicar o número de imagens.

Exemplo: image[0].url; image[1].url

Exemplo: https://www.facebook.com/facebook_hotel.jpg

tag

Tipo: string

Opcional.

Tag anexada à imagem que exibe o que aparece na figura. É possível associar diversas marcações a uma imagem.

Exemplos: Fitness Center, Swimming Pool, suite

INSTAGRAM_STANDARD_PREFERRED – permite que os anunciantes marquem uma imagem específica no próprio feed como a imagem-padrão a ser usada no Instagram. A tag diferencia letras maiúsculas de minúsculas.


Parâmetros do objeto Address

Os campos aninhados ou com diversos valores (como address) podem ser representados por valores JSON codificados ou por um conjunto de colunas simples, com texto sem formatação, rotuladas usando a sintaxe de caminho JSON (como address.region). As duas convenções podem ser usadas alternadamente no mesmo arquivo.


Nome e tipo de campoDescrição

addr1 (address.addr1)

Tipo: objeto

Obrigatório.

Endereço principal do hotel.

Exemplo: 1600 Pennsylvania Avenue

address.addr2

Tipo: objeto

Opcional.

Endereço secundário do hotel.

Exemplo: Apartment 1

address.addr3

Tipo: objeto

Opcional.

Endereço terciário do hotel.

Exemplo: Downstairs

address.city_id (city_id)

Tipo: string

Opcional.

Valor a ser usado na URL do deep link (template_url) em um criativo do anúncio.

Exemplo: 12345

address.city (city)

Tipo: string

Obrigatório.

Cidade onde o hotel está localizado.

Exemplo: New York

address.region (region)

Tipo: string

Obrigatório.

Estado, região ou província onde o hotel está localizado.

Exemplo: California

address.country (country)

Tipo: string

Obrigatório.

País onde o hotel está localizado.

Exemplo: United States

address.postal_code (postal_code)

Tipo: string

Obrigatório para países com um sistema de código postal.

O código postal ou o CEP do hotel.

Exemplos: 94125, NW1 3FG

Parâmetros do objeto Guest Rating


Nome e tipo de campoDescrição

guest_ratings.score (score)

Tipo: objeto

Opcional.

Número total de pessoas que avaliaram seu hotel. Se especificado, você também precisará fornecer score, max_score, number_of_reviewers e rating_system.

Exemplo: 9.0/10

guest_ratings.number_of_reviewers (number_of_reviewers) Tipo: número inteiro

Opcional.

Número total de pessoas que classificaram o hotel.

Exemplo: 5287

guest_ratings.rating_system (rating_system)

Tipo: string

Opcional.

Sistema que você usa para avaliações de hóspedes.

Exemplos: Expedia, TripAdvisor

max_score

Tipo: número inteiro

Obrigatório.

Valor máximo da pontuação de classificação do hotel. Precisa ser maior ou igual a 0 e menor ou igual a 100.

Exemplo: 10

API de Hotel – Criar e gerenciar hotéis diretamente

Use a API de Hotel para adicionar, editar e remover hotéis do catálogo diretamente. Use a referência sobre a API de Hotel para obter mais informações sobre como gerenciar hotéis usando a API.

As seções a seguir são relevantes apenas para gerenciar seus catálogos com a API.

Criar um catálogo de hotéis usando a API

Documentos de referência

Um catálogo de hotéis é um contêiner para seu inventário de hotéis. Para usar a API de catálogo, verifique se você tem o nível de acesso à API de Marketing adequado e se aceitou os Termos de Serviço ao criar seu primeiro catálogo por meio do Gerenciador de Negócios.

Crie um catálogo de hotéis para anúncios configurando vertical como 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

Carregar os feeds de hotéis pela API

Depois de criar o catálogo, é necessário carregar seus feeds de hotéis no Facebook. Use a API para criar um objeto feed para todo feed que você queira carregar. Aceitamos carregamentos agendados e diretos.

Filtrar o catálogo de hotéis para obter conjunto de hotéis

Documentos de referência

Um conjunto de hotéis é um subconjunto do seu catálogo. Para configurar anúncios de hotéis, é preciso um conjunto de hotéis. Portanto, você precisa criar pelo menos um conjunto.

Os conjuntos de hotéis são definidos por filtros aplicados ao catálogo de hotéis. Por exemplo, você pode criar um conjunto de hotéis contendo todos os hotéis com star_rating mais alta que 3. Nota: também é possível criar um conjunto de hotéis sem filtros. Nesse caso, o conjunto conterá todos os hotéis do seu catálogo.

Para criar um conjunto que inclua todos os hotéis com a "sample brand" ("marca de amostra") mencionada no campo 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

O parâmetro filter é composto pelos seguintes operadores e dados:

OperadoresTipo de filtro

i_contains

Contém substring. O operador não diferencia letras maiúsculas de minúsculas.

i_not_contains

Não contém substring. O operador não diferencia letras maiúsculas de minúsculas.

contains

Contém substring. O operador não diferencia letras maiúsculas de minúsculas.

not_contains

Não contém substring. O operador não diferencia letras maiúsculas de minúsculas.

eq

Igual a. O operador não diferencia letras maiúsculas de minúsculas.

neq

Não é igual a. O operador não diferencia letras maiúsculas de minúsculas.

lt

Menor que. Somente para campos numéricos.

lte

Menor ou igual a. Somente para campos numéricos.

gt

Maior que. Somente para campos numéricos.

gte

Maior ou igual a. Somente para campos numéricos.

DadosDados que estão sendo filtrados

hotel_id

O identificador exclusivo do hotel no catálogo.

brand

Marca da rede de hotéis.

base_price_amount

Preço de base por noite deste hotel. O preço é em centavos (4999 significa US$ 49,99).

sale_price_amount

Preço de venda por noite deste hotel. O preço é em centavos (4999 significa US$ 49,99).

currency

A moeda.

city

Cidade onde o hotel está localizado.

country

País do hotel.

name

O nome mais comum do hotel.

star_rating

Classificação por estrelas do hotel. Os valores válidos ficam entre 1 e 5, devendo ser um múltiplo de 0,5.