Pubblicare campagne e inviare eventi

L'integrazione è un ciclo breve. Chiedi al nostro server quali campagne mostrare per una determinata posizione e contesto di menu, le mostri e restituisci gli eventi così i budget vengono addebitati e i report restano accurati.

Chiama POST /api/v1/client/campaigns/search con il contesto per cui vuoi gli annunci: gli ID delle categorie di ristoranti, la posizione e i prodotti attualmente visibili. La risposta contiene le campagne da mostrare — conserva l<code>id</code> di ogni campagna, ti servirà per inviare gli eventi.

const res = await fetch(
  "https://adv.api.waithero.com/api/v1/client/campaigns/search",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.CAMPAIGNS_API_KEY,
    },
    body: JSON.stringify({
      restaurantCategoryIds: [12, 34],
      areaLat: 45.4642,
      areaLon: 9.19,
      products: [
        { referenceId: "sku-123", productName: "Margherita", categoryName: "Pizza" },
      ],
    }),
  },
)

const { campaigns } = await res.json()
// Render campaigns, and remember each campaign.id for event reporting.

Ogni campagna nella risposta include il suo id, il type (HOMEPAGE, SUGGESTION o HIGHLIGHT), l<code>advisor</code>, leventuale promotedProduct e matchedProductReferenceIds — i referenceId che hai inviato e a cui questa campagna corrisponde, così sai esattamente dove posizionarla.

Invia un evento a POST /api/v1/events con l<code>idAdCampaign</code> della campagna e un <code>eventType</code> pari a <code>VIEW</code> o <code>CLICK</code>. Invia un <code>VIEW</code> nel momento in cui una campagna diventa visibile e un <code>CLICK</code> quando lutente la tocca.

async function reportEvent(idAdCampaign, eventType) {
  await fetch("https://adv.api.waithero.com/api/v1/events", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.CAMPAIGNS_API_KEY,
    },
    body: JSON.stringify({ idAdCampaign, eventType }),
  })
}

// When the ad is shown:
reportEvent(42, "VIEW")
// When the user taps it:
reportEvent(42, "CLICK")

Una chiamata riuscita restituisce l'evento registrato con l<code>amount</code> addebitato e il nuovo <code>remainingBudget</code> della campagna.

Inviare più campagne insieme

Se hai mostrato più campagne in una sola vista, inviale insieme con POST /api/v1/events/batch — stesso eventType e un elenco di ID campagna.

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

La registrazione di un evento addebita il budget residuo della campagna (il suo costPerView o costPerClick). Quando il budget di una campagna raggiunge zero, viene terminata automaticamente e smette di comparire nelle ricerche successive. Gestisci queste risposte quando invii gli eventi: