Skip to content

Coatro POP Ingestion Guide ​

Coatro POP (Proof of Play) ingestion API for the MeldCX Platform. Use Coatro to send POP events from your players, screens, and sites into MeldCX.

Core Concepts ​

POP Event ​

A POP event represents a single interaction at a screen or site, such as:

  • A creative being played
  • An impression being recorded
  • A dwell event
  • Any other interaction you want to track

Canonical vs Dynamic Schemas ​

Canonical Schema - Use when your events match the fixed canonical POP structure with fields like campaignId, creativeId, screenId, siteId, etc.

Dynamic Schema - Use when you need to send events with your own structure. You control the fields and track changes using a schemaVersion.

When to Use Which Endpoint ​

Use Canonical POP (POST /coatro/v1/pop/events) ​

When:

  • Your events can be mapped to the canonical POP fields (campaignId, creativeId, screenId, siteId, etc.)
  • You want to use the standard impression and age bucket structure
  • You prefer a fixed, well-defined schema

Use Dynamic POP (POST /coatro/v1/pop/dynamic) ​

When:

  • Your event structure doesn't match the canonical schema
  • Your schema is still evolving
  • You need different fields per integration
  • You want to ship quickly and iterate on your schema

Use Dynamic Bulk Ingestion ​

When:

  • You need to backfill historical data with dynamic POP events
  • You have daily or weekly exports from external systems
  • You're processing large files (NDJSON, JSON, or CSV) with dynamic schemas
  • You want to upload files rather than send individual events

INFO

Canonical bulk ingestion for processing large files with canonical POP events will be available soon.

Getting Started ​

  1. Get your credentials — Contact MeldCX to obtain either:
    • A Keycloak service account (client_id + client_secret) — recommended for new integrations
    • A legacy API key (viana_sk_*) — for existing integrations
  2. Choose your endpoint based on your use case (see above)
  3. Authenticate your requests — see Authentication for details
  4. Send your events using the appropriate endpoint
  5. Monitor responses to ensure your events are being accepted

Required Fields Summary ​

Canonical POP (POST /coatro/v1/pop/events) ​

  • Request body must include events with at least one item.
  • Each event requires: campaignId, creativeId, durationMs, eventId, playedAt, screenId.

Dynamic POP (POST /coatro/v1/pop/dynamic) ​

  • Request body requires schemaVersion and events.
  • schemaVersion must be a non-empty string.
  • events must include at least one item.

Next Steps ​