Skip to main content
Skill set-up-an-event-source · version 1.0.0 · for buyers.

​
When to use

  • A person wants a campaign to optimize for purchases, leads or another conversion.
  • A person asks whether their site is sending conversion events.
  • Set up a campaign found a conversion goal in the brief.

​
Before you start

  • You are connected to the buyer account and know the advertiserId.
  • You know which conversions matter to the person and on which domains they happen.
  • Someone who can change the advertiser’s website or app is available to install the tag.

​
Steps

  1. Call get_status and confirm the account and advertiser.
  2. Call search with kind: "measurement_source", filter.advertiserId, and the person’s words as query (it matches the name, eventSourceId and integration platform). Reuse an event source that already covers the advertiser.
  3. Call get with kind: "measurement_source", the source’s id (it begins with event:) and the advertiserId. Read its event types, allowed domains and health: not_seen, receiving or needs_attention.
  4. If there is no suitable source, confirm the event types and allowed domains with the person, then call save_measurement_source with sourceType: "event", a stable eventSourceId of your choosing, a clear name, the exact eventTypes, and integrationPlatform set to the system that will send the events (the person’s server, CRM or measurement partner). Or call open_page with page: "event_sources" and the advertiserId in arguments so the person creates it there.
  5. The person’s server sends events: the Event sources page shows a server-side snippet and a Send test event button. From an agent, log_event sends events to the source; only send real events the person gives you, never invented ones.
  6. Call get on the source again until its health is receiving. If it stays not_seen or turns needs_attention, tell the person what the page reports.
  7. If the person wants the campaign to optimize for the conversion, read the campaign first, then call save_campaign with optimizationGoals: an event goal whose eventSources entry names the source’s eventSourceId (its key, not the event: id) and an event type the source sends (another type is refused with unsupportedEventTypes). Send the whole ranked list (primary first); null removes every goal. An unknown key is refused with unknownEventSourceIds. If the person goes ahead without tracking, leave the goal out and say the campaign won’t optimize for that outcome.
  8. Tell the person what happens next: when the campaign sends a buy to a seller, Semicola registers the source on that seller and the goal goes with the seller’s own id. GET /api/v2/buyer/event-sources?advertiserId=… lists each seller in sellerProvisioning: provisioned, needs_install, unsupported or failed. A goal whose source isn’t provisioned on a seller is left out of that seller’s buy. Changing the goals on a live campaign sends them to its live buys too (optimizationGoalsCascadeResult in the response).
  9. If the advertiser needs an integration Semicola does not offer yet, file it with save_ask and type: "integration".

​
Guardrails

  • Never send or ask for personal data about the people behind the events.
  • Do not say events are arriving until the health says receiving.
  • Missing conversions are unavailable, not zero.
  • Never attach a guessed or unregistered eventSourceId to a goal.
  • Don’t promise attribution or conversion reporting: Semicola counts events and forwards them to sellers the source is provisioned on; each seller does its own optimization.
  • Send test event sends test traffic (testEventCode): validated, never counted as a conversion, and it doesn’t change the health. Use testEventCode on log_event only for test events.

​
Done when

  • The event source reports receiving.
  • The campaign carries the event goal (or the person chose to go without one), and the brief states the conversion goal.
  • The person knows which events are counted and where to check health later.