WaitHeroReach
ITEN
Back to the site ↗

Developer guide

Highlight items in the menu and send events

Your server sends the menu context and Reach tells you which item to highlight. It then sends a VIEW when the item is seen and a CLICK when it is chosen. Base URL: https://adv.api.waithero.com/api/v1. Your secret API key goes in the x-api-key header, never in the browser.

The key field below is a visual simulation for the try-it panels on this page. In production everything is handled through the API, from your server.

It is only for the visual try-it panels below. In production the key never lives in the browser.

Overview

There are two ways to integrate, and Waithero decides which one applies to your account:

  • Embed cards (recommended for websites): you place Waithero's card on your page, and Waithero records views and clicks itself. See Embed campaigns on your website.
  • API: you show the campaign in your own interface, and your server reports each VIEW and CLICK. The three steps below are this flow.

If your approval email contains a publishable key (it starts with wh_pk_), your account uses embed cards.

01

Find what to highlight

Ask for campaigns matching the city, restaurant and dish.

02

Send a VIEW

When a campaign becomes visible.

03

Send a CLICK

When the user taps it.

Embed campaigns on your website

You search campaigns, add one <waithero-campaign> element for each campaign you want to show, and Waithero draws the card and counts its views and clicks. Any website that can add a script tag can use it, whatever its stack.

1. Your two keys

The email that approves your application contains two keys:

  • Secret API key: for your server only. Never put it in a web page or in code that runs in the browser.
  • Publishable key (starts with wh_pk_): safe to put in your page code. It can only search campaigns, and only from your registered website domains.

Your registered domain is the one from the website address (https) you gave when you applied. Waithero registers it when it approves you. To show cards on another domain, ask Waithero to add it.

2. Add the loader script

Add this tag once on every page that shows cards. It defines the <waithero-campaign> element.

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

3. Search campaigns

Call POST /client/campaigns/search, the same request as in Fetch campaigns. From the browser, send the publishable key. From your server, send the secret key. Both go in the x-api-key header. For embed accounts the location and categoryName are optional, but without a location you only get campaigns that don't target a specific area.

For product cards, also send price, currency, imageUrl and url for each product. The card shows them, and its button opens 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"}]}'

Each campaign in the response has an embed object with the token for its card: embed.token for a HOMEPAGE campaign, or embed.products[].token for SUGGESTION and HIGHLIGHT campaigns (one per matched product). Tokens expire after 7 days, so search on each page view and use them right away.

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

4. Show the cards

Create one <waithero-campaign> element per token, with the token in its token attribute. This complete page searches from the browser and shows up to two cards. If the search fails or finds nothing, the page shows no cards and nothing breaks.

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>

If you search from your server, write the element straight into your HTML:

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

In React, Vue or Angular, render the same tag with a token attribute. Vue and Angular need to be told it is a custom element.

5. Match your site's style

All attributes are optional, and an invalid value falls back to the default. The card always keeps its text readable and its Sponsored label visible.

AttributeValuesDefault
layoutcard, or compact: a 120 px strip (a banner for HOMEPAGE campaigns, a row for products).card
themelight, dark or auto (follows the visitor's system setting when you set no colours).light
langit or en.it
navtop: the product card's button opens url. event: the card fires a waithero-click event instead; call preventDefault() on it to navigate inside your app.top
fitcover: the image is cropped to fill its space. contain: the whole image is shown, and the empty sides show a blurred copy of it. Useful for product photos on a plain background, such as a bottle or a jar.cover
bg, text, accentHex colours, for example #1f6f50.From the theme
muted, border, accent-textHex colours, optional.Derived from the other colours
radiusCorner radius, 0 to 24 (px).12
fontOne of: system, serif, inter, roboto, open-sans, lato, montserrat, poppins, nunito, playfair-displaysystem
font-size13 to 16 (px).14
padding8 to 16 (px).12
heightHeight of the card in px.340 (card) or 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. Test and troubleshoot

  • Testing: on http://localhost or http://127.0.0.1, cards show a TEST badge and nothing is counted or charged. Localhost doesn't need to be registered.
  • No card? Open the browser console. The loader explains why, for example the page's domain isn't registered, the token expired or the campaign ended.
  • Keep the card visible: don't hide, cover or shrink it, and don't cover its Sponsored label. Don't put the card or any of its parents under an opacity below 1, a CSS filter, or a transform other than a translate. Otherwise views don't count.
  • No events to send: Waithero counts views and clicks from the card itself.
  • Content Security Policy: if your site has one, allow https://embed.waithero.com in frame-src and script-src, and the API host in connect-src if you search from the browser.

Restaurant categories

GET /restaurant-categories. Keep each category id: you need it for restaurantCategoryIds.

FieldTypeRequiredDescription
searchstringNoMatches inside the name.
languagestringNoLanguage code, for example it or en.
pageintegerNoFrom 1. Default 1.
limitintegerNoFrom 1 to 50. Default 20.
cURL
curl "https://adv.api.waithero.com/api/v1/restaurant-categories?search=pizza&language=it"
Try GET /restaurant-categories

Fetch campaigns

POST /client/campaigns/search. Only location is required: an address, or areaLat and areaLon. Without products you only get HOMEPAGE campaigns.

FieldTypeRequiredDescription
restaurantCategoryIdsinteger[]NoCategory IDs, or send names instead.
restaurantCategoryNamesstring[]NoCategory names, for example Pizza.
addressstringNoAddress typed as text.
areaLat / areaLonnumberNoCoordinates: send both.
productsProduct[]NoproductName and categoryName are required on the product. referenceId optional.

Each campaign gives you id, type (HOMEPAGE, SUGGESTION, HIGHLIGHT), advisor, promotedProduct, homepage, and 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"}]}'
Try POST /client/campaigns/search

Enter your API key at the top of the page to try this request.

VIEW and CLICK events

POST /events with idAdCampaign and an eventType of VIEW or CLICK. If you showed more than one, send them together with POST /events/batch.

FieldTypeRequiredDescription
idAdCampaignintegerYesThe id search gave you.
eventTypeVIEW | CLICKYesThe event you are recording.
idUserintegerNoEnd-user id, if you want attribution.

The response tells you how much was charged (amount) and what is left (remainingBudget). The batch returns a results[] with ok or error for each campaign.

Using embed cards? Don't send events. Waithero records them from the card, and the events endpoints answer 403 for embed accounts.

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" }'

Full example

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" }) });
}

Errors and budget

Every event takes costPerView or costPerClick out of the budget. When the budget runs out, the campaign closes and drops out of searches.

StatusMeaning
400Campaign inactive, outside its dates, or invalid event.
401Missing or invalid API key.
402Budget is gone.
403Not allowed: for example a publishable key used from an unregistered domain, or events sent by an account that uses embed cards.
404Campaign not found.