WaitHeroReach
ITEN
Torna al sito ↗

Guida per sviluppatori

Evidenziare nel menu e inviare eventi

Il tuo server invia il contesto del menu e Reach ti dice quale voce evidenziare. Poi manda un VIEW quando viene vista e un CLICK quando viene scelta. Base URL: https://adv.api.waithero.com/api/v1. La chiave API segreta va nell’header x-api-key, mai nel browser.

Il campo chiave qui sotto è una simulazione visiva per le prove in pagina. In produzione tutto viene gestito tramite API, dal tuo server.

Serve solo alle prove visive qui sotto. In produzione la chiave non sta nel browser.

Panoramica

Ci sono due modi di integrarsi, e Waithero decide quale vale per il tuo account:

  • Card embed (consigliato per i siti web): inserisci la card di Waithero nella tua pagina e Waithero registra da sé visualizzazioni e clic. Vedi Integra le campagne nel tuo sito.
  • API: mostri la campagna nella tua interfaccia e il tuo server segnala ogni VIEW e CLICK. I tre passaggi qui sotto descrivono questo flusso.

Se l’email di approvazione contiene una chiave pubblicabile (inizia con wh_pk_), il tuo account usa le card embed.

01

Trova cosa evidenziare

Chiedi le campagne adatte a città, ristorante e piatto.

02

Invia un VIEW

Quando una campagna diventa visibile.

03

Invia un CLICK

Quando l’utente la tocca.

Integra le campagne nel tuo sito

Cerchi le campagne, aggiungi un elemento <waithero-campaign> per ogni campagna da mostrare, e Waithero disegna la card e ne conta visualizzazioni e clic. Funziona su qualsiasi sito che possa aggiungere un tag script, con qualunque tecnologia.

1. Le tue due chiavi

L’email che approva la tua candidatura contiene due chiavi:

  • Chiave API segreta: solo per il tuo server. Non metterla mai in una pagina web o in codice che gira nel browser.
  • Chiave pubblicabile (inizia con wh_pk_): puoi metterla nel codice delle tue pagine. Serve solo a cercare campagne, e solo dai domini registrati del tuo sito.

Il dominio registrato è quello dell’indirizzo del sito (https) che hai indicato nella candidatura. Waithero lo registra quando ti approva. Per mostrare le card su un altro dominio, chiedi a Waithero di aggiungerlo.

2. Aggiungi lo script del loader

Aggiungi questo tag una volta in ogni pagina che mostra le card. Definisce l’elemento <waithero-campaign>.

HTML
<script src="https://embed.waithero.com/v1/loader.js" async></script>

3. Cerca le campagne

Chiama POST /client/campaigns/search, la stessa richiesta di Recupera campagne. Dal browser usa la chiave pubblicabile, dal tuo server la chiave segreta: in entrambi i casi va nell’header x-api-key. Per gli account embed la posizione e categoryName sono facoltativi, ma senza posizione ricevi solo le campagne che non puntano a una zona precisa.

Per le card prodotto invia anche price, currency, imageUrl e url per ogni prodotto. La card li mostra e il suo pulsante apre url.

cURL
curl -X POST "https://adv.api.waithero.com/api/v1/client/campaigns/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{"address":"Milano","products":[{"referenceId":"sku-42","productName":"Margherita","categoryName":"Pizza","price":8.5,"currency":"EUR","imageUrl":"https://yoursite.com/img/42.jpg","url":"https://yoursite.com/p/42"}]}'

Ogni campagna nella risposta ha un oggetto embed con il token della sua card: embed.token per una campagna HOMEPAGE, oppure embed.products[].token per le campagne SUGGESTION e HIGHLIGHT (uno per ogni prodotto trovato). I token scadono dopo 7 giorni: cerca a ogni caricamento di pagina e usali subito.

Risposta (ridotta)
{
  "campaigns": [
    {
      "id": 12,
      "type": "HOMEPAGE",
      "embed": { "token": "HOMEPAGE_TOKEN" }
    },
    {
      "id": 42,
      "type": "HIGHLIGHT",
      "embed": {
        "products": [{ "referenceId": "sku-42", "token": "PRODUCT_TOKEN" }]
      }
    }
  ]
}

4. Mostra le card

Crea un elemento <waithero-campaign> per ogni token, con il token nell’attributo token. Questa pagina completa cerca dal browser e mostra al massimo due card. Se la ricerca non riesce o non trova nulla, la pagina non mostra card e non si rompe niente.

HTML
<script src="https://embed.waithero.com/v1/loader.js" async></script>

<div id="waithero-campaigns"></div>

<script type="module">
  async function searchCampaigns() {
    try {
      const res = await fetch("https://adv.api.waithero.com/api/v1/client/campaigns/search", {
        method: "POST",
        headers: { "Content-Type": "application/json", "x-api-key": "wh_pk_YOUR_KEY" },
        body: JSON.stringify({
          address: "Milano",
          products: [{
            referenceId: "sku-42", productName: "Margherita", categoryName: "Pizza",
            price: 8.5, currency: "EUR",
            imageUrl: "https://yoursite.com/img/42.jpg", url: "https://yoursite.com/p/42"
          }]
        })
      });
      if (!res.ok) return [];
      const { campaigns = [] } = await res.json();
      return campaigns;
    } catch {
      return [];
    }
  }

  const campaigns = await searchCampaigns();
  const tokens = campaigns.flatMap((campaign) =>
    campaign.embed?.token
      ? [campaign.embed.token]
      : (campaign.embed?.products ?? []).map((product) => product.token)
  );

  const container = document.getElementById("waithero-campaigns");
  for (const token of tokens.slice(0, 2)) {
    const card = document.createElement("waithero-campaign");
    card.setAttribute("token", token);
    container.append(card);
  }
</script>

Se cerchi dal tuo server, scrivi l’elemento direttamente nel tuo HTML:

HTML
<waithero-campaign token="TOKEN_FROM_SEARCH"></waithero-campaign>

In React, Vue o Angular usa lo stesso tag con l’attributo token. In Vue e Angular va dichiarato come custom element.

5. Adatta la card al tuo sito

Tutti gli attributi sono facoltativi e un valore non valido torna a quello predefinito. La card tiene sempre il testo leggibile e l’etichetta Sponsorizzato visibile.

AttributoValoriPredefinito
layoutcard, oppure compact: una striscia di 120 px (un banner per le campagne HOMEPAGE, una riga per i prodotti).card
themelight, dark o auto (segue l’impostazione di sistema del visitatore, se non indichi colori).light
langit o en.it
navtop: il pulsante della card prodotto apre url. event: la card lancia invece l’evento waithero-click; chiama preventDefault() per navigare dentro la tua app.top
fitcover: l’immagine viene ritagliata per riempire lo spazio. contain: l’immagine si vede intera, e i lati vuoti mostrano una sua copia sfocata. Utile per le foto di prodotto su sfondo neutro, come una bottiglia o un barattolo.cover
bg, text, accentColori esadecimali, per esempio #1f6f50.Dal tema
muted, border, accent-textColori esadecimali, facoltativi.Ricavati dagli altri colori
radiusRaggio degli angoli, da 0 a 24 (px).12
fontUno tra: system, serif, inter, roboto, open-sans, lato, montserrat, poppins, nunito, playfair-displaysystem
font-sizeDa 13 a 16 (px).14
paddingDa 8 a 16 (px).12
heightAltezza della card in px.340 (card) o 120 (compact)
HTML
<waithero-campaign token="TOKEN_FROM_SEARCH" layout="compact" lang="en"
  bg="#fff8ee" text="#3b2a1a" accent="#1f6f50" radius="16" font="inter"></waithero-campaign>

6. Prova e risolvi i problemi

  • Prove: su http://localhost o http://127.0.0.1 le card mostrano un badge TEST e non viene contato né addebitato nulla. Non serve registrare localhost.
  • La card non compare? Apri la console del browser. Il loader spiega il motivo, per esempio il dominio della pagina non è registrato, il token è scaduto o la campagna è finita.
  • Lascia la card visibile: non nasconderla, non coprirla, non rimpicciolirla e non coprire l’etichetta Sponsorizzato. Non mettere la card, o un elemento che la contiene, sotto un’opacity minore di 1, un filter CSS o un transform diverso da una traslazione. Altrimenti le visualizzazioni non vengono contate.
  • Nessun evento da inviare: Waithero conta visualizzazioni e clic direttamente dalla card.
  • Content Security Policy: se il tuo sito ne usa una, consenti https://embed.waithero.com in frame-src e script-src, e l’host dell’API in connect-src se cerchi dal browser.

Categorie di ristoranti

GET /restaurant-categories. Tieni l’id di ogni categoria: ti serve in restaurantCategoryIds.

CampoTipoObbligatorioDescrizione
searchstringNoCerca dentro il nome.
languagestringNoCodice lingua, per esempio it o en.
pageintegerNoDa 1. Predefinito 1.
limitintegerNoDa 1 a 50. Predefinito 20.
cURL
curl "https://adv.api.waithero.com/api/v1/restaurant-categories?search=pizza&language=it"
Prova GET /restaurant-categories

Recupera campagne

POST /client/campaigns/search. Serve solo la posizione: un address, oppure areaLat e areaLon. Senza prodotti ricevi solo campagne HOMEPAGE.

CampoTipoObbligatorioDescrizione
restaurantCategoryIdsinteger[]NoID delle categorie, oppure manda i nomi.
restaurantCategoryNamesstring[]NoNomi delle categorie, per esempio Pizza.
addressstringNoIndirizzo scritto a mano.
areaLat / areaLonnumberNoCoordinate: vanno insieme.
productsProduct[]NoproductName e categoryName obbligatori nel prodotto. referenceId facoltativo.

Ogni campagna ti dà id, type (HOMEPAGE, SUGGESTION, HIGHLIGHT), advisor, promotedProduct, homepage e matchedProductReferenceIds.

cURL
curl -X POST "https://adv.api.waithero.com/api/v1/client/campaigns/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"address":"Milano","restaurantCategoryNames":["Pizza"],"products":[{"referenceId":"sku-123","productName":"Margherita","categoryName":"Pizza"}]}'
Prova POST /client/campaigns/search

Inserisci la tua chiave API in cima alla pagina per provare questa richiesta.

Eventi VIEW e CLICK

POST /events con idAdCampaign e un eventType VIEW o CLICK. Se ne hai mostrate più di una, mandale insieme con POST /events/batch.

CampoTipoObbligatorioDescrizione
idAdCampaignintegerSìL’id che ti ha dato la ricerca.
eventTypeVIEW | CLICKSìL’evento che stai registrando.
idUserintegerNoId dell’utente, se vuoi l’attribuzione.

La risposta dice quanto è stato addebitato (amount) e quanto resta (remainingBudget). Il batch torna un results[] con ok o error per ogni campagna.

Usi le card embed? Non inviare eventi. Li registra Waithero dalla card, e gli endpoint degli eventi rispondono 403 per gli account embed.

cURL
curl -X POST "https://adv.api.waithero.com/api/v1/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "idAdCampaign": 42, "eventType": "VIEW" }'

Esempio completo

JavaScript
const BASE = "https://adv.api.waithero.com/api/v1";
const headers = { "Content-Type": "application/json", "x-api-key": process.env.CAMPAIGNS_API_KEY };
const categories = await fetch(`${BASE}/restaurant-categories?search=pizza`, { headers }).then((r) => r.json());
const { campaigns } = await fetch(`${BASE}/client/campaigns/search`, {
  method: "POST", headers,
  body: JSON.stringify({
    restaurantCategoryIds: categories.data.map((c) => c.id),
    areaLat: 45.4642, areaLon: 9.19,
    products: [{ referenceId: "sku-123", productName: "Margherita", categoryName: "Pizza" }]
  })
}).then((r) => r.json());
for (const campaign of campaigns) {
  await fetch(`${BASE}/events`, { method: "POST", headers, body: JSON.stringify({ idAdCampaign: campaign.id, eventType: "VIEW" }) });
}

Errori e budget

Ogni evento scala costPerView o costPerClick dal budget. Quando il budget finisce, la campagna si chiude e sparisce dalle ricerche.

StatoSignificato
400Campagna non attiva, fuori periodo, o evento non valido.
401Chiave API mancante o non valida.
402Budget finito.
403Non consentito: per esempio una chiave pubblicabile usata da un dominio non registrato, o eventi inviati da un account che usa le card embed.
404Campagna non trovata.