Inserzioni del catalogo Advantage+

Inserzioni per hotel: cataloghi ed elenchi

Per promuovere il tuo inventario di hotel su Facebook, devi condividere le informazioni sui tuoi hotel con Facebook. A tale scopo, crea un catalogo e compilalo con i tuoi hotel. Esistono due modi per compilare e aggiornare il catalogo:

Puoi creare e gestire il tuo catalogo di hotel in Gestione dei cataloghi.

Per usare l'API per la gestione del catalogo:

  1. Crea un catalogo di hotel.
  2. Crea insiemi di prodotti dal tuo catalogo di hotel.
  3. Associa il catalogo alle origini degli eventi.

Elenchi di hotel: caricamento degli hotel su Facebook

Un elenco di hotel è un file con il tuo inventario di hotel. Ogni riga o voce del file rappresenta un singolo hotel. Puoi usare uno o più elenchi di hotel, purché tutti gli elenchi contengano il tuo inventario di hotel completo.

Formati degli elenchi di hotel supportati

CSV

CSV di esempio | TSV di esempio (livello singolo) | TSV di esempio (stile JSON)

  • La prima riga deve contenere i nomi scelti per i campi nell'ordine in cui saranno assegnati i valori. Le righe seguenti devono fornire i valori corrispondenti per ogni hotel.
  • I campi che contengono spazi o virgole devono essere compresi tra "virgolette doppie".
  • I campi nidificati o con più valori, ad esempio address, neighborhood o image, possono essere rappresentati usando valori con codifica JSON o tramite una serie di colonne a testo semplice a livello singolo, etichettate usando una sintassi con percorso JSON (ad es., address.city, neighborhood[0], image[0].url, image[0].tag[0], image[0].tag[1]). Entrambe le convenzioni possono essere usate in modo intercambiabile all'interno dello stesso file.

XML

XML di esempio

  • Un nodo XML <listings> radice comprende una serie di nodi <listing>, dove ciascuno rappresenta un hotel.
  • Il file deve iniziare con un tag di dichiarazione <?xml valido.

Il parser dell'elenco rileva in automatico le codifiche di testo UTF8, UTF16 o UTF32 e imposta LATIN1 come valore predefinito se individua una sequenza di byte non prevista. Puoi fornire testo nei valori dei campi in qualsiasi lingua, ma i nomi dei campi devono essere indicati come mostrato qui sotto, in inglese.

Campi supportati: inserzioni per hotel

I seguenti campi supportati sono progettati per gli articoli che aggiungi al catalogo prodotti.

Per i cataloghi localizzati, vedi i campi supportati per le inserzioni per gli hotel.

Campo e tipoDescrizione

hotel_id

tipo: stringa

Obbligatorio.

Lunghezza massima: 100

Il tuo identificativo unico per l'hotel all'interno del catalogo. Tale ID è abbinato a qualsiasi content_ids fornito nella tua app hotel e negli eventi del pixel. Suggerimento: per migliorare le prestazioni, evita di usare lo spazio per questo campo identificativo unico. Non usare ID duplicati.

Esempio: FB_hotel_1234

room_id

tipo: stringa

Obbligatorio se si aggiungono informazioni sulle stanze dell'hotel.

Immetti un ID unico per il tipo di stanza dell'hotel. Caratteri massimi: 100 Esempio: FB_hotel_room_1234

name

tipo: stringa

Obbligatorio.

Il nome più comune dell'hotel.

Esempio: Facebook Hotel

description

tipo: stringa

Obbligatorio.

Dimensioni massime: 5000

Breve descrizione dell'hotel.

Esempio: Only 30 minutes away from San Francisco.

checkin_date

tipo: stringa

Obbligatorio se si aggiungono informazioni sulle stanze dell'hotel.

Data del check-in per la permanenza in hotel. Puoi aggiungere fino a 180 giorni dalla data di caricamento dell'elenco. Usa lo standard ISO-8601 (YYYY-MM-DD).

Esempio: 2017-08-01

length_of_stay

tipo: stringa

Obbligatorio se si aggiungono informazioni sulle stanze dell'hotel.

Numero di notti di permanenza in hotel.

Esempio: 7

base_price

tipo: stringa

Obbligatorio se si aggiungono informazioni sulle stanze dell'hotel.

Prezzo base della stanza dell'hotel per notte. Assicurati di aggiungere il tipo di valuta al prezzo (ad esempio, USD per i dollari americani). Il prezzo deve avere lo stesso formato del costo, seguito dal codice di valuta ISO, con uno spazio tra costo e valuta.

Esempio: 199.00 EUR

price

tipo: stringa

Obbligatorio se si aggiungono informazioni sulle stanze dell'hotel.

Prezzo totale della permanenza in hotel, in base a checkin_date e length_of_stay. Il prezzo deve avere lo stesso formato del costo, seguito dal codice di valuta ISO, con uno spazio tra costo e valuta.

Esempio: 1393.00 USD

tax

tipo: stringa

Obbligatorio se si aggiungono informazioni sulle stanze dell'hotel.

Aliquota di imposta applicabile al prezzo. Il prezzo deve avere lo stesso formato del costo, seguito dal codice di valuta ISO, con uno spazio tra costo e valuta.

Esempio: 14.00 USD

fees

tipo: stringa

Obbligatorio se si aggiungono informazioni sulle stanze dell'hotel.

Oneri applicabili al prezzo. Formatta il prezzo come il costo, seguito dal codice valuta ISO, con uno spazio tra costo e valuta.

Esempio: 253.00 USD

url

tipo: stringa

Obbligatorio.

Il link al sito esterno in cui è possibile prenotare una stanza dell'hotel. Puoi specificare anche un URL a livello dell'inserzione usando template_url_spec. Gli URL a livello dell'inserzione hanno la precedenza rispetto agli URL nell'elenco.

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

image[0].url

tipo: oggetto

Consulta Parametri dell'oggetto image.

image[0].tag

tipo: oggetto

Consulta Parametri dell'oggetto image.

brand

tipo: stringa

Obbligatorio.

Nome del brand della catena di hotel.

Esempio: Hilton

address

tipo: oggetto

Consulta Parametri dell'oggetto address.

neighborhood[0]

tipo: stringa

Obbligatorio.

Voci max. per quartiere: 20

Quartiere in cui è ubicato l'hotel. Se è presente più di un quartiere, aggiungi ulteriori colonne per ognuno di essi e usa una sintassi con percorso JSON nel nome di ciascuna colonna per indicare il numero di quartieri.

Esempio: Belle Haven

latitude

tipo: float

Obbligatorio.

Latitudine dell'hotel.

Esempio: 37.484100

longitude

tipo: float

Obbligatorio.

Longitudine dell'hotel.

Esempio: -122.148252

sale_price

tipo: stringa

Facoltativo.

Prezzo di vendita per notte di permanenza nell'hotel, in base a checkin_date e length_of_stay. Usa questo parametro quando desideri pubblicizzare sconti sul prezzo dell'hotel. Assicurati di aggiungere il tipo di valuta al prezzo (ad esempio, USD per i dollari americani). Assicurati che il sale_price dell'hotel sia inferiore al rispettivo base_price. Il prezzo deve avere lo stesso formato del costo, seguito dal codice di valuta ISO, con uno spazio tra costo e valuta.

Esempio: 149.00 USD

guest_ratings.score

tipo: oggetto

Consulta Parametri dell'oggetto guest rating.

guest_ratings.rating_system

tipo: oggetto

Consulta Parametri dell'oggetto guest rating.

star_rating

tipo: float

Consulta Parametri dell'oggetto guest rating.

loyalty_program

tipo: stringa

Facoltativo.

Il programma fedeltà che usi per accumulare punti per la permanenza in hotel.

Esempio: Premium program

margin_level

tipo: numero intero

Facoltativo.

Indicatore di redditività dell'hotel; valore da 1 a 10.

Esempio: 9

phone

tipo: stringa

Facoltativo.

Numero di telefono principale dell'hotel.

Esempio: +61 296027455

applink

tipo: oggetto

Facoltativo.

Deep link che reindirizza direttamente alla pagina di informazioni dell'hotel nella tua app mobile usando link all'interno dell'app. Puoi specificare i deep link in ordine di precedenza, dalla più alta alla più bassa:

  1. A livello dell'inserzione usando template_url_spec.
  2. Nell'elenco usando un oggetto Applink.
  3. Aggiungendo meta tag dei link all'interno dell'app per il tuo sito web.

Scopri di più sui deep link dei prodotti.

priority

tipo: numero intero

Facoltativo.

Un indicatore della priorità dell'hotel; valore da 0 (priorità minima) a 5 (priorità massima). Esempio: 5

category

tipo: stringa

Facoltativo.

Il tipo di proprietà. La categoria può essere un tipo qualsiasi di descrizione interna. Esempio: Resort, Day Room

number_of_rooms

tipo: numero intero

Facoltativo.

Numero totale di stanze/unità nell'annuncio di questo hotel.

Esempio: 150

status

Tipo: stringa

Controlla se un articolo è attivo o archiviato nel tuo catalogo. Le persone possono vedere solo gli articoli attivi nelle tue inserzioni, nei tuoi shop o in qualsiasi altro canale. Valori supportati: active, archived. Per impostazione predefinita gli articoli sono attivi. Scopri di più sull'archiviazione di articoli.


Esempio: active


Nota: alcune piattaforme partner come Shopify potrebbero sincronizzare gli articoli sul tuo catalogo con uno stato chiamato staging, che si comporta come archived.

In precedenza questo campo si chiamava visibility. Anche se continueremo a supportare il vecchio nome del campo, consigliamo di usare quello nuovo.

custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4

Tipo: stringa

Limite massimo di caratteri: 100

Fino a 5 campi personalizzati per le informazioni aggiuntive in base alle quali vuoi filtrare gli articoli quando crei degli insiemi. Ad esempio, puoi utilizzare un campo personalizzato per indicare tutte le stanze parte di una promozione estiva e filtrarle poi in un insieme. Il campo supporta qualsiasi valore di testo, inclusi i numeri.


Esempio: Summer Sale

Questo campo è supportato da elenchi supplementari.

custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4

Tipo: int

Fino a 5 campi personalizzati per le informazioni aggiuntive relative ai numeri in base alle quali vuoi filtrare gli articoli quando crei degli insiemi. Questo campo ti consente di filtrare per intervalli numerici (è maggiore di e è minore di) quando crei un insieme. Ad esempio, puoi utilizzare questo campo per indicare l'anno in cui è stato aperto un hotel e poi filtrare un determinato intervallo di anni in un insieme.


Questo campo supporta tutti i numeri tra 0 e 4294967295. Non supporta numeri negativi, decimali o virgole, ad esempio: -2, 5,5 o 10,000.


Esempio: 2022

Parametri dell'oggetto image


Nome e tipo di campoDescrizione

url

tipo: stringa

Obbligatorio.

N. max. di elementi: 20.

URL all'immagine dell'elemento che comparirà nelle inserzioni. Segui queste specifiche dell'immagine:

  • Tutte le immagini devono essere in formato JPG, GIF o PNG.

  • Per le inserzioni carosello e raccolta: immagini visualizzate in formato quadrato (1:1). Le dimensioni minime delle immagini sono 500 x 500 pixel. Per una migliore qualità, consigliamo 1024 x 1024 pixel.

  • Per le inserzioni con singola immagine: immagine visualizzata con proporzioni pari a 1.91:1. Le dimensioni minime dell'immagine sono 500 x 500 pixel. Per una migliore qualità, consigliamo 1200 x 628 pixel.

  • Se è presente più di un'immagine, aggiungi ulteriori colonne per ognuna di esse e usa una sintassi con percorso JSON per indicare il numero di immagini.

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

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

tag

tipo: stringa

Facoltativo.

Tag allegato all'immagine a indicare il contenuto dell'immagine. Puoi associare più tag a un'immagine.

Esempi: Fitness Center, Swimming Pool, suite

INSTAGRAM_STANDARD_PREFERRED: consente agli inserzionisti di taggare una specifica immagine nel proprio elenco come immagine predefinita da usare per Instagram. Questo tag distingue tra maiuscole e minuscole.


Parametri dell'oggetto address

I campi nidificati o con più valori, ad esempio address, possono essere rappresentati usando valori con codifica JSON o tramite una serie di colonne a testo semplice senza struttura, etichettate usando una sintassi con percorso in stile JSON come address.region. Entrambe le convenzioni possono essere usate in modo intercambiabile all'interno dello stesso file.


Nome e tipo di campoDescrizione

addr1 (address.addr1)

tipo: oggetto

Obbligatorio.

Indirizzo principale dell'hotel.

Esempio: 1600 Pennsylvania Avenue

address.addr2

tipo: oggetto

Facoltativo.

Indirizzo secondario dell'hotel.

Esempio: Apartment 1

address.addr3

tipo: oggetto

Facoltativo.

Ulteriore indirizzo dell'hotel.

Esempio: Downstairs

address.city_id (city_id)

tipo: stringa

Facoltativo.

Valore da usare nell'URL del deep link (template_url) nelle creatività dell'inserzione.

Esempio: 12345

address.city (city)

tipo: stringa

Obbligatorio.

Città in cui è ubicato l'hotel.

Esempio: New York

address.region (region)

tipo: stringa

Obbligatorio.

Stato, contea o provincia in cui è ubicato l'hotel.

Esempio: California

address.country (country)

tipo: stringa

Obbligatorio.

Paese in cui è ubicato l'hotel.

Esempio: United States

address.postal_code (postal_code)

tipo: stringa

Obbligatorio per i Paesi con un sistema di codici postali.

Codice postale o CAP dell'hotel.

Esempi: 94125, NW1 3FG

Parametri dell'oggetto guest rating


Nome e tipo di campoDescrizione

guest_ratings.score (score)

tipo: oggetto

Facoltativo.

Numero totale di persone che hanno recensito l'hotel. Se specificato, devi indicare anche score, max_score, number_of_reviewers e rating_system.

Esempio: 9.0/10

guest_ratings.number_of_reviewers (number_of_reviewers) tipo: int

Facoltativo.

Numero totale di persone che hanno valutato l'hotel.

Esempio: 5287

guest_ratings.rating_system (rating_system)

tipo: stringa

Facoltativo.

Sistema che utilizzi per le recensioni degli ospiti.

Esempi: Expedia, TripAdvisor

max_score

tipo: int

Obbligatorio.

Valore massimo per il punteggio delle valutazioni dell'hotel. Deve essere pari o superiore a 0 e pari o inferiore a 100.

Esempio: 10

API Hotel: creazione e gestione diretta degli hotel

Puoi usare l'API Hotel per aggiungere, modificare e rimuovere direttamente gli hotel nel tuo catalogo. Consulta il riferimento all'API Hotel per maggiori informazioni su come gestire gli hotel attraverso l'API.

Le seguenti sezioni sono pertinenti solo per la gestione dei tuoi cataloghi mediante questa API.

Creazione di un catalogo di hotel mediante l'API

Documenti di riferimento

Un catalogo di hotel è un contenitore per il tuo inventario di hotel. Per usare l'API Catalog, assicurati di avere il livello di accesso dell'API Marketing corretto e di aver accettato le Condizioni d'uso creando il tuo primo catalogo mediante Business Manager.

Per creare un catalogo di hotel per le inserzioni per gli hotel, imposta vertical su 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

Caricamento degli elenchi di hotel tramite l'API

Una volta creato il tuo catalogo, devi caricare i tuoi elenchi di hotel su Facebook. Usa l'API per creare un oggetto elenco per ciascun elenco che desideri caricare. Supportiamo caricamenti programmati e diretti.

Come filtrare il catalogo di hotel per insiemi di hotel

Documenti di riferimento

Un insieme di hotel è un sottoinsieme del tuo catalogo. Per configurare le inserzioni per gli hotel, hai bisogno di un insieme di hotel. Pertanto, ne devi creare almeno uno.

Gli insiemi di hotel sono definiti dai filtri applicati al relativo catalogo. Ad esempio, puoi creare un insieme di hotel con tutti quelli caratterizzati da un valore di star_rating superiore a 3. Nota: puoi anche creare un insieme di hotel senza filtri. In questo caso, l'insieme di hotel conterrà tutti gli hotel del tuo catalogo.

Per creare un insieme di hotel contenente tutti gli hotel con l'elemento "sample brand" menzionato nel 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

Il parametro filter è composto dai seguenti operatori e dati:

OperatoriIl tipo di filtro

i_contains

Contiene sottostringhe. L'operatore non distingue tra lettere maiuscole e minuscole.

i_not_contains

Non contiene sottostringhe. L'operatore non distingue tra lettere maiuscole e minuscole.

contains

Contiene sottostringhe. L'operatore non distingue tra lettere maiuscole e minuscole.

not_contains

Non contiene sottostringhe. L'operatore non distingue tra lettere maiuscole e minuscole.

eq

Uguale a. L'operatore non distingue tra lettere maiuscole e minuscole.

neq

Diverso da. L'operatore non distingue tra lettere maiuscole e minuscole.

lt

Minore di. Solo per campi numerici.

lte

Minore di o uguale a. Solo per campi numerici.

gt

Maggiore di. Solo per campi numerici.

gte

Maggiore di o uguale a. Solo per campi numerici.

DatiI dati filtrati.

hotel_id

Il tuo identificativo unico per l'hotel all'interno del catalogo.

brand

Il brand della catena di hotel.

base_price_amount

Il prezzo base per notte per l'hotel. Il prezzo è espresso in centesimi (4999 indica $ 49,99).

sale_price_amount

Il prezzo di vendita per notte per l'hotel. Il prezzo è espresso in centesimi (4999 indica 49,99 dollari).

currency

Valuta

city

Città in cui è ubicato l'hotel.

country

Paese in cui è ubicato l'hotel.

name

Il nome più comune dell'hotel.

star_rating

Numero di stelle dell'hotel. I valori validi sono compresi tra 1 e 5 e devono essere un multiplo di 0,5.