Anuncios de catálogo de Advantage+

Anuncios de hoteles: catálogos y lista

Si quieres promocionar tu inventario de hoteles en Facebook, debes compartir información sobre ellos con la plataforma. Para ello, crea un catálogo de hoteles y complétalo con los distintos establecimientos. Existen dos métodos para rellenar el catálogo y actualizarlo:

Puedes crear y administrar los catálogos de hoteles en Commerce Manager.

Para utilizar la API para administrar el catálogo:

  1. Crear un catálogo de hoteles
  2. Crear conjuntos de productos a partir del catálogo de hoteles
  3. Asociar el catálogo a los orígenes de eventos

Listas de hoteles: subir hoteles a Facebook

Una lista de hoteles es un archivo que contiene tu inventario de hoteles. Cada línea o artículo del archivo representa un solo hotel. Puedes usar una o varias listas de hoteles, siempre que el conjunto de todas ellas abarque tu inventario de hoteles al completo.

Formatos de lista de hoteles compatibles

CSV

Ejemplo de CSV | Ejemplo de TSV (aplanado) | Ejemplo de TSV (estilo JSON)

  • La primera fila debe enumerar los nombres de campo elegidos en el mismo orden en que se proporcionan los valores. Las filas siguientes proporcionarán los valores correspondientes de cada hotel.
  • Los campos que contienen espacios en blanco o comas se deben "entrecomillar".
  • Los campos anidados o con varios valores, como address, neighborhood o image, se pueden representar con valores codificados en JSON o con un conjunto de columnas sin formato "aplanadas" etiquetadas con una sintaxis de ruta de acceso JSON, como address.city, neighborhood[0], image[0].url, image[0].tag[0] y image[0].tag[1]. Se pueden utilizar ambas convenciones indistintamente en el mismo archivo.

XML

Ejemplo de XML

  • Un nodo XML raíz <listings> contiene un conjunto de nodos <listing>, cada uno de los cuales representa un hotel.
  • El archivo debe comenzar con una etiqueta de declaración <?xml válida.

El analizador de listas detecta automáticamente las codificaciones de texto UTF8, UTF16 o UTF32, y adopta de forma predeterminada la codificación LATIN1 si encuentra una secuencia de bytes inesperada. Puedes proporcionar texto en cualquier idioma en los valores de los campos, pero los nombres de estos deben facilitarse tal y como se indica a continuación, en inglés.

Campos admitidos: anuncios de hoteles

Los siguientes campos admitidos se han diseñado para los elementos que añades al catálogo de productos.

En el caso de catálogos localizados, consulta los campos admitidos para anuncios de hoteles.

Campo y tipoDescripción

hotel_id

Tipo: cadena

Obligatorio.

Longitud máxima: 100

Tu identificador único para el hotel en el catálogo. Este identificador se corresponderá con cualquier valor de content_ids proporcionado en tus eventos del píxel y aplicación de hotel. Sugerencia: Para mejorar el rendimiento, evita utilizar un espacio para este campo de identificador único. No utilices identificadores duplicados.

Ejemplo: FB_hotel_1234

room_id

Tipo: cadena

Obligatorio si se añade información de la habitación de hotel.

Introduce un identificador único para el tipo de habitación del hotel. Máximo de caracteres: 100. Ejemplo: FB_hotel_room_1234

name

Tipo: cadena

Obligatorio.

Nombre más común del hotel.

Ejemplo: Facebook Hotel

description

Tipo: cadena

Obligatorio.

Tamaño máximo: 5000

Breve descripción del hotel.

Ejemplo: Only 30 minutes away from San Francisco.

checkin_date

Tipo: cadena

Obligatorio si se añade información de la habitación de hotel.

Fecha de entrada de la estancia en el hotel. Puedes añadir hasta 180 días a partir de la fecha de subida de la lista. Utiliza el estándar ISO-8601 (YYYY-MM-DD).

Ejemplo: 2017-08-01

length_of_stay

Tipo: cadena

Obligatorio si se añade información de la habitación de hotel.

Cantidad de noches de estancia en el hotel.

Ejemplo: 7

base_price

Tipo: cadena

Obligatorio si se añade información de la habitación de hotel.

Precio base de la habitación de hotel por noche. Asegúrate de añadir el tipo de divisa al precio (por ejemplo, USD para dólares estadounidenses). Asigna al precio el mismo formato que al coste, seguido del código de divisa ISO, con un espacio entre el coste y la divisa.

Ejemplo: 199.00 EUR

price

Tipo: cadena

Obligatorio si se añade información de la habitación de hotel.

Precio total de la estancia en el hotel, basado en los valores de checkin_date y length_of_stay. Asigna al precio el mismo formato que al coste, seguido del código de divisa ISO , con un espacio entre el coste y la divisa.

Ejemplo: 1393.00 USD

tax

Tipo: cadena

Obligatorio si se añade información de la habitación de hotel.

Tipo impositivo aplicable al precio. Asigna al precio el mismo formato que al coste, seguido del código de divisa ISO, con un espacio entre el coste y la divisa.

Ejemplo: 14.00 USD

fees

Tipo: cadena

Obligatorio si se añade información de la habitación de hotel.

Comisiones aplicables al precio. Asigna al precio el mismo formato que al coste, seguido del código de divisa ISO, con un espacio entre el coste y la divisa.

Ejemplo: 253.00 USD

url

Tipo: cadena

Obligatorio.

Enlace al sitio externo en el que se puede reservar una habitación del hotel. También puedes especificar una URL en el nivel de anuncio mediante template_url_spec. Las direcciones URL del nivel de anuncio tienen prioridad sobre las de la lista.

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

image[0].url

Tipo: objeto

Consulta Parámetros de objeto de imagen.

image[0].tag

Tipo: objeto

Consulta Parámetros del objeto “image”.

brand

Tipo: cadena

Obligatorio.

Nombre de marca de la cadena de hoteles.

Ejemplo: Hilton

address

Tipo: objeto

Consulta Parámetros de objeto de dirección.

neighborhood[0]

Tipo: cadena

Obligatorio.

Máximo de vecindarios permitidos: 20

Vecindario en el que se encuentra el hotel. Si existe más de un vecindario, añade columnas adicionales para cada uno y utiliza la sintaxis de la ruta JSON en cada nombre de columna para indicar el número de vecindarios.

Ejemplo: Belle Haven

latitude

Tipo: flotante

Obligatorio.

Latitud del hotel.

Ejemplo: 37.484100

longitude

Tipo: flotante

Obligatorio.

Longitud del hotel.

Ejemplo: -122.148252

sale_price

Tipo: cadena

Opcional.

Precio por noche de la estancia en el hotel, basado en los valores de checkin_date y length_of_stay. Utiliza esta opción cuando quieras anunciar descuentos sobre el precio habitual del hotel. Asegúrate de añadir el tipo de divisa al precio (por ejemplo, USD para dólares estadounidenses). Asegúrate de que el valor de sale_price de un hotel es menor que su valor de base_price. Asigna al precio el mismo formato que al coste, seguido del código de divisa ISO, con un espacio entre el coste y la divisa.

Ejemplo: 149.00 USD

guest_ratings.score

Tipo: objeto

Consulta Parámetros de objetos de calificación de huéspedes.

guest_ratings.rating_system

Tipo: objeto

Consulta Parámetros de objetos de calificación de huéspedes.

star_rating

Tipo: flotante

Consulta Parámetros de objetos de calificación de huéspedes.

loyalty_program

Tipo: cadena

Opcional.

Programa de fidelidad que utilizas para obtener puntos por la estancia en el hotel.

Ejemplo: Premium program

margin_level

Tipo: entero

Opcional.

Indicador de la rentabilidad del hotel; valor de 1 a 10.

Ejemplo: 9

phone

Tipo: cadena

Opcional.

Número de teléfono principal del hotel.

Ejemplo: +61 296027455

applink

Tipo: objeto

Opcional.

Enlace profundo directo a la página de detalles del hotel en la aplicación para móviles mediante App Links. Puedes especificar enlaces profundos por orden de prioridad (de la más alta a la más baja), de las siguientes formas:

  1. En el nivel de anuncio mediante template_url_spec.
  2. Aquí en la lista mediante un objeto Applink.
  3. Al añadir metaetiquetas de enlace a la aplicación al sitio web.

Obtén más información sobre los enlaces profundos de productos.

priority

Tipo: entero

Opcional.

Indicador de la prioridad del hotel; valor de 0 (prioridad más baja) a 5 (prioridad más alta). Ejemplo: 5

category

Tipo: cadena

Opcional.

Tipo de propiedad. La categoría puede ser cualquier tipo de descripción interna que desees. Ejemplo: Resort, Day Room

number_of_rooms

Tipo: entero

Opcional.

Número total de habitaciones o unidades en el anuncio del hotel.

Ejemplo: 150

status

Tipo: cadena

Controla si un artículo está activo o archivado en el catálogo. Solo los artículos activos aparecen en los anuncios, las tiendas y otros canales. Valores admitidos: active y archived. Los artículos están activos de manera predeterminada. Obtén más información sobre cómo archivar artículos.


Ejemplo: active


Nota: Es posible que algunas plataformas de socios, como Shopify, sincronicen los artículos con tu catálogo con un estado denominado provisional, que se comporta igual que archived.

Anteriormente, este campo se llamaba visibility. Aunque todavía admitimos el nombre antiguo, te recomendamos que utilices el nuevo.

custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4

Tipo: cadena

Límite máx. de caracteres: 100

Hasta cinco campos personalizados de cualquier información adicional por la que quieras filtrar los artículos cuando creas conjuntos. Por ejemplo, puedes utilizar un campo personalizado para especificar todas las habitaciones que forman parte de una oferta de temporada y, después, filtrar esos artículos en un conjunto. Este campo admite cualquier valor de texto, incluidos números.


Ejemplo: Summer Sale

Este campo se admite en las listas complementarias.

custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4

Tipo: entero

Hasta cinco campos personalizados de cualquier información adicional relacionada con números por la que quieras filtrar los artículos cuando creas conjuntos. Este campo permite filtrar por intervalos de números (es mayor que y es menor que) cuando creas un conjunto. Por ejemplo, puedes utilizar este campo para especificar el año en el que se abrió un hotel y, a continuación, filtrar un determinado intervalo de años en un conjunto.


Este campo admite números enteros entre el 0 y el 4294967295. No admite números negativos, decimales ni comas, como -2, 5,5 o 10 000.


Ejemplo: 2022

Parámetros del objeto “image”


Nombre y tipo del campoDescripción

url

Tipo: cadena

Obligatorio.

Máximo de elementos: 20.

Enlace URL a la imagen del elemento que aparecerá en tus anuncios. Sigue estas especificaciones de imagen:

  • Todas las imágenes deben tener el formato JPG, GIF o PNG.

  • En el caso de los anuncios por secuencia y los de colección, las imágenes se muestran en formato cuadrado (1:1). El tamaño mínimo de imagen es de 500 × 500 píxeles. Para obtener la máxima calidad, recomendamos el formato de 1024 x 1024 px.

  • En el caso de los anuncios de una sola imagen, estas presentan una relación de aspecto de 1.91:1. El tamaño de imagen mínimo es de 500 x 500 px. Para obtener la máxima calidad, recomendamos el formato de 1200 x 628 px.

  • Si existe más de una imagen, añade columnas adicionales para cada una y utiliza la sintaxis de la ruta JSON en cada nombre de columna para indicar el número de imágenes.

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

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

tag

Tipo: cadena

Opcional.

Etiqueta anexada a la imagen que indica qué contiene la imagen. Puede haber varias etiquetas asociadas con una imagen.

Ejemplos: Fitness Center, Swimming Pool, suite

INSTAGRAM_STANDARD_PREFERRED: permite a los anunciantes etiquetar una imagen concreta de la lista como predeterminada para utilizarla en Instagram. Esta etiqueta distingue mayúsculas de minúsculas.


Parámetros del objeto “address”

Los campos anidados o con varios valores, como address, se pueden representar con valores cifrados mediante JSON o un conjunto de columnas “aplanadas” de texto sin formato etiquetadas con sintaxis de ruta JSON (por ejemplo, address.region). Se pueden utilizar ambas convenciones indistintamente en el mismo archivo.


Nombre y tipo del campoDescripción

addr1 (address.addr1)

Tipo: objeto

Obligatorio.

Dirección postal principal del hotel.

Ejemplo: 1600 Pennsylvania Avenue

address.addr2

Tipo: objeto

Opcional.

Dirección postal secundaria del hotel.

Ejemplo: Apartment 1

address.addr3

Tipo: objeto

Opcional.

Dirección postal terciaria del hotel.

Ejemplo: Downstairs

address.city_id (city_id)

Tipo: cadena

Opcional.

Valor que se usará en la dirección URL del enlace profundo (template_url), en el contenido del anuncio.

Ejemplo: 12345

address.city (city)

Tipo: cadena

Obligatorio.

Ciudad en la que se encuentra el hotel.

Ejemplo: New York

address.region (region)

Tipo: cadena

Obligatorio.

Estado, condado o provincia donde se encuentra el hotel.

Ejemplo: California

address.country (country)

Tipo: cadena

Obligatorio.

País en el que se encuentra el hotel.

Ejemplo: United States

address.postal_code (postal_code)

Tipo: cadena

Obligatorio para países con un sistema de códigos postales.

Código postal del hotel.

Ejemplos: 94125, NW1 3FG

Parámetros de objetos de calificación de huéspedes


Nombre y tipo del campoDescripción

guest_ratings.score (score)

Tipo: objeto

Opcional.

Número total de personas que han opinado sobre el hotel. Si se especifica, también debes proporcionar los valores de score, max_score, number_of_reviewers y rating_system.

Ejemplo: 9.0/10

Tipo de guest_ratings.number_of_reviewers (number_of_reviewers): entero

Opcional.

Número total de personas que han valorado este hotel.

Ejemplo: 5287

guest_ratings.rating_system (rating_system)

Tipo: cadena

Opcional.

Sistema que utilizas para las opiniones de los huéspedes.

Ejemplos: Expedia, TripAdvisor

max_score

Tipo: entero

Obligatorio.

Valor máximo de la puntuación de la calificación del hotel. Debe ser mayor o igual que 0 y menor o igual que 100.

Ejemplo: 10

API de hoteles: crear y administrar hoteles directamente

Puedes utilizar la API de hoteles para añadir, editar y quitar hoteles directamente en el catálogo. Utiliza la referencia de la API de hoteles para obtener más información sobre cómo administrar hoteles mediante la API.

Las secciones siguientes solo se aplican a la administración de catálogos mediante esta API.

Crear un catálogo de hoteles mediante la API

Documentos de referencia

Un catálogo de hoteles es un contenedor para el inventario de hoteles. Para usar la API del catálogo, asegúrate de tener el nivel de acceso a la API de marketing correspondiente y de aceptar las Condiciones del servicio. Para ello, crea tu primer catálogo mediante Business Manager.

Para crear un catálogo de hoteles para anuncios de hoteles, establece vertical en 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

Subir las listas de hoteles mediante la API

Una vez que hayas creado el catálogo, debes subir las listas de hoteles a Facebook. Crea un objeto “feed” para cada lista que quieras subir con la API. Admitimos cargas programadas y directas.

Filtrar el catálogo de hoteles para obtener conjuntos de hoteles

Documentos de referencia

Un conjunto de hoteles es un subconjunto del catálogo. Para configurar anuncios de hoteles, necesitas un conjunto de hoteles. Por lo tanto, debes crear al menos uno.

Los conjuntos de hoteles se definen por los filtros que se aplican al catálogo. Por ejemplo, puedes crear un conjunto de hoteles con todos los hoteles que tengan un valor de star_rating superior a 3. Nota: También puedes crear un conjunto de hoteles sin ningún filtro. En este caso, el conjunto incluirá todos los hoteles de tu catálogo.

Para crear un conjunto de hoteles que incluya todos los hoteles que contienen el valor "sample brand" mencionado en el 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

El parámetro filter está formado por los operadores y datos siguientes:

OperadoresTipo de filtro

i_contains

Contiene subcadena. No distingue mayúsculas de minúsculas.

i_not_contains

No contiene subcadena. No distingue mayúsculas de minúsculas.

contains

Contiene subcadena. No distingue mayúsculas de minúsculas.

not_contains

No contiene subcadena. No distingue mayúsculas de minúsculas.

eq

Igual a. No distingue mayúsculas de minúsculas.

neq

No es igual a. No distingue mayúsculas de minúsculas.

lt

Menor que. Solo para campos numéricos.

lte

Menor o igual que. Solo para campos numéricos.

gt

Mayor que. Solo para campos numéricos.

gte

Mayor o igual que. Solo para campos numéricos.

DatosDatos que se filtran

hotel_id

Tu identificador único para el hotel en el catálogo.

brand

Marca de la cadena de hoteles

base_price_amount

Precio base por noche del hotel. El precio se indica en centavos (4999 indica 49,99 $).

sale_price_amount

Precio de venta por noche del hotel. El precio se indica en centavos (4999 indica 49,99 USD).

currency

Divisa.

city

Ciudad en la que se encuentra el hotel.

country

País del hotel.

name

Nombre más común del hotel.

star_rating

Calificación de estrellas del hotel. Este campo puede adoptar un valor comprendido entre 1 y 5, que sea múltiplo de 0,5.