Skip to content
Contact us
Documentation menuGetting started

Getting started. The first event in six steps.

This guide sets up a source from scratch and verifies that the first event reaches Postlip Metrics. The Setup tab of the source page in the panel writes the same steps with your own key and address.

What you need

  • A Postlip Metrics organization. Organizations are opened by the platform team; its owner receives an invitation e-mail.
  • An app in the organization (Settings › Apps): the measured product, with its time zone and currency.
  • The “Manage sources and keys” permission; for the live stream, “Manage the event schema”. The developer role has both.

  1. Create a source

    In the panel, Data › Sources › Create source. A source is a client that sends data to the app: a website or web app, iOS, Android, a server or another Segment-compatible library. The source kind cannot change later.

    • Pick the environment: production, staging or development. Screens show production by default.
    • For web sources, list the allowed origins; a request from another Origin gets 403 origin_not_allowed.
    • Pick the consent mode (required, implied, none). Details: Consent and privacy.

  2. Get the keys

    On the source’s Keys tab, Create key. The full key is shown once, when it is created; Postlip Metrics keeps only its hash.

    • Write key pk_live_… or pk_test_…: may sit in the open in browsers and mobile apps; it can only send data. Events sent with a test key are marked as test.
    • Signing secret sk_live_… for server sources: lives only in the server’s environment (METRICS_SIGNING_SECRET) and signs requests.

  3. Add the snippet

    Pick the method that fits your source. The snippets are taken from the SDK documentation and the Tracking API guide; replace <alan> or <your-domain> with your collector address and pk_live_… with your write key.

    In the site’s <head> · HTML
    <script>
  !function(){var m=window.metrics=window.metrics||[];if(m.load)return;m.q=[];["page","track","identify","group","alias","reset","consent"].forEach(function(k){m[k]=function(){m.q.push([k].concat([].slice.call(arguments)))}});
  var s=document.createElement("script");s.async=1;s.src="https://collect.<your-domain>/m.js";document.head.appendChild(s);
  m.load=function(k,o){m.q.unshift(["load",k,o])};}();
  metrics.load("pk_live_…", { consent: "required" });
  metrics.page();
</script>

  4. Test the connection

    The Test the connection button on the Setup tab checks the key and (if given) the signature, and stores nothing. You can run the same check yourself with POST /v1/ping; the answer names the source, the environment and the state of the signature.

    Connection test · Bash
    curl -X POST https://collect.<domain>/v1/ping \
  -u "$WRITE_KEY:" -H "Content-Type: application/json" -d '{}'

  5. Verify in the live stream

    Once the snippet is live, open Data › Live stream. Every message appears within seconds with its validation result; a click on a row shows the stored values or the reasons of a rejection. Rejected messages are kept for 7 days.

    • Valid: the event matches the schema and was stored.
    • Unplanned: the event is not in the schema; accepted in the lenient and discover modes and placed in the Discovered inbox.
    • Coerced: a value was converted to the defined type and accepted (e.g. "12" → 12).
    • Rejected: the message was not stored; the reason shows with its code, path and text (e.g. property_required, pii_detected).

  6. Map events to the schema

    Define the events in Data › Event schemas › Discovered with Add as definition, and map each business event to a business role. Once the schema settles, switch the validation mode to strict; check sample events in CI with metrics validate, and generate a typed client with metrics pull.

Next