Widget prenotazioni
Aggiungi il widget StayParity per prenotazioni dirette al sito dell’hotel con un solo codice. Il codice, il dock, cosa vedono gli ospiti e la CSP necessaria.
Il widget è un piccolo riquadro con i prezzi sul sito dell’hotel. Mostra la tariffa diretta di un soggiorno e, quando l’hotel è il più economico o allo stesso prezzo, accanto i prezzi delle OTA. Funziona in un iframe isolato: non può leggere la pagina che lo contiene e la pagina non può accedere al suo contenuto. L’isolamento gli consente solo due azioni, ognuna solo dopo un clic dell’ospite: aprire la pagina di prenotazione dell’hotel nella scheda in cui si trova l’ospite e aprire stayparity.com in una nuova scheda dal suo link di attribuzione.
La pagina del widget spiega che cosa dice il widget agli ospiti e perché. Questa pagina spiega come inserirlo in un sito.
Aggiungi il widget a una pagina
- Nell’applicazione, vai su Impostazioni → Widget prenotazioni e attiva Widget. L’applicazione ti chiede la pagina di prenotazione dell’hotel, che resta nella stessa schermata, in Pagina di prenotazione, per cambiarla in seguito. Il pulsante Book direct, nella lingua dell’ospite con la traduzione attiva, apre la pagina di prenotazione nella stessa scheda.
- Copia il codice dalla sezione Codice, nella scheda Incolla: il tag script, che contiene la chiave dell’hotel e nient’altro. La scheda Tag manager dà lo stesso tag, con i passaggi per un tag di tipo «HTML personalizzato». La scheda Inoltra dà un messaggio con il codice, dove va e come verificarlo, da mandare a chi si occupa del tuo sito.
- Incollalo una volta in ogni pagina che deve mostrare il widget, o nel footer del tuo sito. Il widget compare in un angolo in basso della finestra, ovunque si trovi il tag, quindi il tag può stare ovunque dentro
<body>. Poi, nella pagina Widget dell’applicazione, inserisci l’indirizzo della pagina in Controlla il mio sito: ti dice se il tag è nella pagina e se la policy di sicurezza del tuo sito permette al widget di caricarsi.
<!-- Widget per prenotazioni dirette di StayParity. L’aspetto si imposta in StayParity. -->
<script src="https://badge.stayparity.com/embed.js" data-hotel="wk_aurora" async></script>Lo script aggiunge l’iframe in fondo alla pagina e non tocca nient’altro. L’iframe adatta l’altezza al contenuto.
Il dock
Il widget è un dock: una barra in un angolo in basso della finestra. Compare quando arriva la tariffa diretta. Con un clic si apre in un pannello con la risposta completa, e la freccia in fondo al pannello o Esc lo richiudono. L’ospite non può chiuderlo del tutto: resta lì per tutta la visualizzazione della pagina. Se nel suo angolo c’è già un pulsante della chat o una barra di prenotazione fissa, il dock sale sopra quell’elemento o passa all’altro angolo in basso, e resta dov’è se nessuna delle due posizioni è libera. Si nasconde mentre un comune banner dei cookie lo copre.
In Aspetto, in Impostazioni → Widget prenotazioni:
- Angolo del dock sceglie l’angolo sinistro o destro, e Altezza del dock quanto sta sopra il bordo inferiore della finestra, fino a 200 pixel.
- Colore del pulsante è Automatico, scuro su uno sfondo chiaro e chiaro su uno scuro, o un colore a tua scelta. Un colore con un contrasto inferiore a 3:1 rispetto allo sfondo viene rifiutato.
- Sfondo è Chiaro, Scuro o Sistema dell’ospite, che segue l’impostazione chiara o scura dell’ospite.
- Angoli può essere Squadrati, Arrotondati o Pillola.
Ogni modifica arriva a ogni pagina con il tag entro un minuto, con lo stesso codice. Il widget chiede le sue impostazioni a StayParity a ogni caricamento di pagina.
Lingua
Il widget è in inglese. Se attivi Traduci il widget in Impostazioni → Widget prenotazioni, appare nella lingua dell’ospite quando il suo browser preferisce il greco, lo spagnolo, l’italiano, il tedesco o il ceco, e in inglese negli altri casi. Segue le lingue impostate nel browser dell’ospite, non la lingua della tua pagina, e scrive prezzi e date come si usa in quella lingua. È disattivato finché non lo attivi, e arriva a ogni pagina con il tag entro un minuto, senza un nuovo codice.
Valuta
Il widget mostra i prezzi nella valuta dell’hotel. Con Gli ospiti possono cambiare valuta attiva, un codice valuta in fondo al dock apre un menu con le valute che offri, prima quella dell’hotel, e ogni prezzo nel pannello passa alla valuta scelta dall’ospite, convertito al tasso di cambio di riferimento del giorno. Il confronto vero e proprio e l’importo addebitato dalla pagina di prenotazione restano nella valuta dell’hotel. Con Apri nella valuta dell’ospite attiva, il widget parte nella valuta della regione dell’ospite, ricavata dalla lingua del suo browser, se la offri.
Attributi
Il tag ha due attributi:
data-hotel, obbligatorio: la chiave dell’hotel,wk_…. Senza questa il tag non mostra nulla.data-consent="none", facoltativo: StayParity non conta quella visualizzazione di pagina nelle statistiche del widget, e il widget non salva nulla nel browser dell’ospite, quindi Salva la notte, Apertura automatica e Offerta di uscita non compaiono su quella pagina e la modalità test dura una sola pagina. I prezzi che mostra non cambiano. Per tenere il widget fuori da una pagina finché l’ospite non dà il consenso, carica invece il tag dal tuo strumento di gestione del consenso o dal tuo tag manager.
L’aspetto, la lingua e la valuta arrivano da StayParity, la notte dalla pagina.
Di quale notte mostra il prezzo
Il widget mostra il prezzo di una notte: la data di arrivo, con la data di partenza o il numero di notti, e il numero di adulti scelti dall’ospite. Li cerca solo nell’indirizzo della tua pagina, nei campi del tuo modulo di prenotazione e, nelle pagine di prenotazione di Mews e Cloudbeds, negli eventi che quei booking engine inviano al dataLayer della pagina, e non legge nient’altro nella pagina. Finché non conosce un soggiorno, mostra la notte più vicina della prossima settimana di cui abbiamo rilevato il prezzo nell’ultimo giorno, se Notte più vicina con prezzo è attiva, come lo è fin dall’inizio. Con l’opzione disattivata, o se non c’è una notte così, non mostra nulla e non occupa spazio. Per un soggiorno senza numero di adulti, o con bambini o più di una camera, mostra il prezzo per due adulti o, se l’hotel non viene controllato per due adulti, per il numero più basso controllato. Mostra la notte dell’ospite appena conosce il soggiorno, per esempio nel momento in cui l’ospite sceglie le date nel tuo modulo di prenotazione.
Il widget avvia un nuovo controllo solo per le occupazioni monitorate per l’hotel. Per le altre mostra un prezzo già rilevato per quell’occupazione o, se non c’è, il prezzo per due adulti o per il numero più basso controllato per l’hotel, e lo indica.
Che cosa legge:
- L’indirizzo della pagina, al caricamento e ogni volta che cambia, come succede quando un booking engine cerca senza ricaricare la pagina. L’arrivo da
checkin,checkInDate,arrival,arrivalDate,arrive,startDate,dateFrom,fromDateomewsStart; la partenza dacheckout,checkOutDate,departure,departureDate,depart,endDate,dateTo,toDateomewsEnd; le notti danightsolos; gli adulti daadults,adult,adultCount,adultQty,numAdults,numberOfAdultsomewsAdultCount; i bambini dachildren,child,childCount,childQty,kidsonumChildren; le camere darooms,numRoomsoroomCount. Maiuscole e punteggiatura non contano, quindi valgono anchecheck_ineCheck-In, ma deve corrispondere il nome intero: coninoitems[0][adults]non legge nulla. Un totale di ospiti, comeguests,pax,personsooccupancy, non conta mai come adulti. - I campi del tuo modulo di prenotazione, appena l’ospite ne cambia uno. Un campo conta se il suo
name, il suoido l’ultima parte[...]del suo nome è uno dei nomi qui sopra, comearrival_dateoinfo[arrival_date]. Non legge mai campi nascosti, di password, email, telefono, file, casella di controllo o pulsante di opzione, campi che il browser compila con un nome, un’email, un numero di telefono o una carta, né campi disattivati. Un modulo così come si è caricato conta solo quando l’ospite cambia uno dei suoi campi, quindi un modulo che si apre con la data di stanotte già compilata lascia visibile la notte più vicina con prezzo finché l’ospite non sceglie.
Prevale l’ultimo soggiorno letto, da qualunque fonte arrivi. Un indirizzo che contiene solo i valori predefiniti di un booking engine, una notte da oggi per due adulti, conta solo quando cambia. La prima notte che conosce viene controllata subito. Dopo, il widget attende mezzo secondo dall’ultima modifica dell’ospite prima di chiedere di nuovo, così un calendario che compila due campi costa un solo controllo. Un selettore che scrive nei suoi campi senza un evento change viene letto 300 millisecondi dopo il clic dell’ospite.
Legge le date scritte come 2027-06-14, 2027/06/14, 20270614, 14/06/2027 o 06/14/2027 (con /, . o -), e come 14 Jun 2027 o Jun 14, 2027, con i nomi dei mesi nelle sei lingue del widget e in francese. Una data numerica che si legge in due modi e dà due soggiorni possibili viene ignorata. Un soggiorno va da 1 a 30 notti, tra oggi e i prossimi 500 giorni. Non legge moduli dentro un altro frame o uno shadow root, né selettori di date o di ospiti che non sono campi di un modulo.
Se il tuo modulo di prenotazione gira in un proprio frame, o usa selettori di date e ospiti che non sono campi di un modulo, il widget non vede la notte: mostra la notte più vicina con prezzo o, con Notte più vicina con prezzo disattivata, niente. In questo caso metti il soggiorno nell’indirizzo della pagina, per esempio ?checkin=2027-06-14&checkout=2027-06-15&adults=2.
Che cosa vedono gli ospiti
Il widget confronta la tariffa diretta con i prezzi delle OTA per quella notte, e mostra le OTA solo quando prenotare direttamente costa meno o lo stesso:
| Quando | Titolo | Mostra anche |
|---|---|---|
| L’hotel è il più economico | Save €16 | Il prezzo di ogni OTA per lo stesso soggiorno |
| L’hotel ha lo stesso prezzo dell’OTA più economica, al centesimo | Same price, booked direct | Il prezzo di ogni OTA per lo stesso soggiorno |
| Un’OTA costa meno | La tariffa diretta, per esempio €188 per night | Nessuna OTA |
| Nessun prezzo OTA per quella notte | La tariffa diretta, per esempio €188 per night | Nessuna OTA |
Compresso, il dock dice Save €16 by booking direct, Same price as Booking.com o, senza OTA da mostrare, Best price here: €188 per night.
Il pannello si apre con una riga che indica la notte di cui mostra il prezzo, per esempio Night of Sat 4 Oct · 2 adults o Tonight, e il tempo trascorso dall’ultimo controllo, per esempio Checked 12 min ago (omesso se il controllo ha più di una settimana). Sotto, sopra il titolo, un sigillo dice Best price here in tutti i casi. Quando il widget mostra le OTA, compaiono sotto Same stay elsewhere, ciascuna con logo, nome e prezzo. Il pulsante Book direct riporta la tariffa diretta della notte. In fondo al pannello, Price check by StayParity apre stayparity.com in una nuova scheda, tra la freccia che richiude il pannello e, se lasci cambiare valuta agli ospiti, il selettore della valuta.
Per contare nel tuo strumento di analisi le prenotazioni che arrivano da Book direct, consulta Misura il widget nei tuoi strumenti di analisi. Per indicare la stessa risposta in un chatbot o in un tuo widget, consulta l’API di verifica dei prezzi.
Durante il primo controllo di un soggiorno, e se non arriva nessun prezzo, il dock non mostra nulla. Il widget non mostra nulla e non occupa spazio quando:
- l’hotel è inattivo in StayParity.
- non è stato rilevato nessun prezzo per il soggiorno, un controllo viene rifiutato (il soggiorno è nel passato o oltre l’orizzonte di monitoraggio del piano dell’hotel, oppure i controlli a disposizione dell’hotel sono esauriti) e non c’è un prezzo nemmeno per due adulti o per il numero più basso controllato per l’hotel.
I prezzi seguono il formato della lingua e del paese dell’ospite, nella valuta dell’hotel o in quella scelta dall’ospite. I testi del widget sono in inglese, o nella lingua dell’ospite se la traduzione è attiva.
Che cosa non mostra mai
- Un prezzo OTA più basso di quello dell’hotel, e nemmeno che esista. Quando un’OTA costa meno, il dock mostra solo la tariffa diretta invece di elencare soltanto le OTA più care. Nemmeno l’API rivela mai una discrepanza: risponde per quella notte esattamente come per una notte che nessuna OTA vende, quindi né un ospite né uno script che interroga l’endpoint possono distinguerle. L’hotel vede comunque la discrepanza nell’applicazione e nelle sue notifiche.
- L’identificatore interno dell’hotel, dove è stato rilevato un prezzo o quanto ne siamo sicuri.
- Un errore. L’iframe non occupa spazio durante il primo controllo e resta nascosto se il controllo non riesce. Se la chiave è sconosciuta o il widget è disattivato, l’iframe si riduce ad altezza zero e non lascia spazi vuoti nella pagina. Il browser di un ospite può continuare a mostrare un widget caricato negli ultimi cinque minuti.
Che cosa salva sul dispositivo dell’ospite
Né l’iframe né lo script usano cookie. Con le opzioni aggiuntive dell’hotel disattivate, non salvano nulla nel browser dell’ospite. Salva la notte, Apertura automatica e Offerta di uscita salvano ognuna una piccola nota sul dispositivo dell’ospite, nello spazio di archiviazione della tua pagina, sotto la chiave dell’hotel:
- Salva la notte: la notte e il numero di adulti che l’ospite ha salvato, nel localStorage, scritti quando tocca Keep. Il widget li rimuove quando l’ospite tocca di nuovo Kept, e alla sua prossima visita a una pagina in cui si carica il tuo widget, se la data di arrivo è passata o l’opzione è disattivata.
- Apertura automatica e Offerta di uscita: nel sessionStorage finché la scheda non viene chiusa, una nota scritta quando il dock si apre da solo o perché l’ospite sta per lasciare la pagina, o quando l’ospite lo richiude, così non si riapre da solo.
- Offerta di uscita: nel sessionStorage finché la scheda non viene chiusa, una nota scritta quando l’offerta compare o l’ospite fa clic su Book direct, così un’uscita successiva non la mostra di nuovo. Nel localStorage, il momento in cui l’ospite ha chiuso l’offerta, così resta chiusa per 7 giorni. Il widget rimuove questa nota alla prossima visita dell’ospite a una pagina in cui si carica il tuo widget, trascorsi i 7 giorni, o quando l’offerta smette di comparire: perché è disattivata o perché nessun codice è attivo.
Il tuo banner dei cookie o la tua gestione del consenso potrebbero dover includere queste note. Con data-consent="none" nessuna di queste note viene letta o scritta.
La modalità test (#stayparity-debug nell’indirizzo della pagina) salva la propria lingua nel sessionStorage di quella scheda.
Che cosa conta
A meno che il tag non abbia data-consent="none", l’iframe invia a StayParity un conteggio per ogni visualizzazione di pagina in cui è comparso, quando la pagina viene nascosta o chiusa o quando l’ospite fa clic su Book direct. Questi conteggi sono i dati del widget nell’applicazione. Il primo invio per ogni visualizzazione di pagina contiene:
- la chiave dell’hotel e l’hostname della pagina;
- la lingua del browser, e se lo schermo ha le dimensioni di uno smartphone;
- di quale notte il widget ha mostrato il prezzo: il soggiorno dell’ospite, la data dell’ospite per un altro numero di adulti, o la notte più vicina con prezzo;
- il suo esito, per esempio che prenotare direttamente costa meno o che il prezzo è lo stesso;
- se è una striscia o un dock, e se la modalità test è attiva;
- se ha mostrato un prezzo ed è stato visto sullo schermo, se l’ospite ha aperto il dock o ha fatto clic su Book direct, se l’offerta di uscita è comparsa, se l’ospite ne ha copiato il codice o ha salvato la notte, e se il dock si è aperto da solo.
Se poi l’ospite fa altro, per esempio copia il codice, un invio successivo contiene solo la chiave dell’hotel, l’hostname e quali di queste azioni ha compiuto l’ospite. Nessun invio contiene ID, indirizzi di pagina né date di soggiorno.
Il server edge che riceve i conteggi usa l’indirizzo IP dell’ospite solo come chiave del suo limite di frequenza, 30 invii al minuto, chiave che Cloudflare conserva per quel minuto. Il server non registra l’indirizzo né lo passa ad altri, e StayParity non lo memorizza mai.
Content Security Policy
Se il sito invia un header Content-Security-Policy, consenti all’origine del widget di caricare lo script e l’iframe, e allo script di leggere le impostazioni del widget:
script-src https://badge.stayparity.com;
frame-src https://badge.stayparity.com;
connect-src https://badge.stayparity.com;Aggiungi l’origine alle fonti esistenti senza sostituirle.
Prima di creare l’iframe lo script chiede all’origine del widget le sue impostazioni, ed è connect-src a consentirlo. Senza questa direttiva il widget funziona comunque, ma il browser registra una violazione CSP a ogni visualizzazione di pagina, e l’iframe parte nel punto del tag e poi lascia il posto a un secondo iframe in fondo alla pagina, quindi si carica due volte. Lo script imposta le dimensioni dell’iframe tramite DOM, non con attributi style nell’HTML, quindi il codice non richiede modifiche a style-src.
I prezzi vengono richiesti dentro l’iframe, con la policy dell’iframe stesso. Se la tua policy per gli script usa nonce o strict-dynamic, aggiungi al tag script il nonce del tuo sito; aggiungere solo l’host all’elenco consentito può non bastare.
Disattiva o sostituisci il widget
- Per disattivarlo, disattiva Widget in Impostazioni → Widget prenotazioni. I nuovi visitatori non vedono nulla, perché l’iframe si riduce fino a sparire; il browser di un ospite può continuare a mostrare un widget caricato negli ultimi cinque minuti. Riattivalo e lo stesso codice funziona di nuovo.
- Per cambiarne l’aspetto o la valuta, modifica Aspetto o le impostazioni della valuta in Impostazioni → Widget prenotazioni. Ogni pagina con il tag si adegua entro un minuto, con lo stesso codice.
- Per tradurlo, attiva Traduci il widget in Impostazioni → Widget prenotazioni. Ogni pagina con il tag si adegua entro un minuto, con lo stesso codice.
- Per sostituirlo, Sostituisci il codice genera una nuova chiave. La vecchia chiave viene rifiutata alla successiva richiesta non in cache, su ogni sito che la usa, finché non incolli il nuovo codice. Un browser può continuare a mostrare un widget messo in cache negli ultimi cinque minuti.
Solo gli amministratori dell’account possono attivare o disattivare il widget, cambiarne l’aspetto, la lingua o la valuta, o sostituire il codice.
Caricamento
Lo script si carica con async, quindi non rallenta mai la pagina. Nella versione compressa che scaricano i browser, lo script pesa circa 9 kB e l’iframe del widget circa altri 32 kB di script, senza font web da scaricare.
Ogni visualizzazione di pagina ha un solo iframe, creato quando la pagina ha finito di caricarsi, o 3 secondi dopo il suo parsing se questo avviene prima, e il browser è inattivo, così non entra mai in competizione con il caricamento della pagina stessa. Quando la policy del sito omette connect-src, l’iframe parte nel punto del tag e viene sostituito in fondo alla pagina, quindi si carica due volte.
Una pagina con il widget disattivato non riceve alcun iframe. Prima di conoscere la notte il widget chiede solo la notte più vicina con prezzo e, con Notte più vicina con prezzo disattivata, niente. Dopo, chiede di nuovo solo quando l’ospite si decide per un’altra notte.
Webhook
L’evento JSON firmato che StayParity invia quando un’OTA vende a meno della tariffa diretta di un hotel. Firme, nuovi tentativi e test.
API di verifica dei prezzi
Porta nel tuo chatbot o nella tua app l’esito del widget StayParity di un hotel: un GET, la tariffa diretta e le OTA che eguaglia o batte, mai una discrepanza.