Custom events can be any arbitrary JSON as long as you provide a MetaRouter Schema.

MetaRouter requires a small set of structured metadata to accept and deliver events. In most cases, providing 2 fields is all we need to process your data: writeKey and eventName.

The MetaRouter Schema consists of the following required and optional fields:

All field types are strings.

FieldRequiredDescription
writeKeyrequiredWrite Key is your API key.
eventNamerequiredEvent Name is an arbitrary category for the event. Examples: "order created", "page view", "sign in"
eventIDoptional (auto-generated if absent)Event ID is a guid/uuid for tracing the lifecycle of an event. If absent, MetaRouter creates a random UUIDv4.
timestampoptional (auto-generated if absent)Timestamp is when the event was created. Must be a string in ISO 8601 format. If absent, MetaRouter sets this field to the current server time.
anonymousIDoptionalAnonymous ID is used for tracking and attribution. It should be a persistent, unique identifier (like a uuid) for an unauthenticated user.
userIDoptionalUser ID is used for tracking and attribution. It should be a persistent, unique identifier (like a hashed email or database id) for an authenticated user.

Inside an event, the schema is referenced as a simple JSON object with reserved key _mrSchema. The _mrSchema key must be part of the root object.

{
  "_mrSchema": {
    "writeKey": "abc123",
    "eventName": "page view",
    "eventID": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-08-17T15:10:33Z",
    "anonymousID": "456e4567-e89b-12d3-a456-426614174000",
    "userID": "98765"
  },
  "event": "my event fields",
  "json": "whatever json you want"
}

You're free to omit optional fields or fields that MetaRouter auto-generates.

{
  "_mrSchema": {
    "writeKey": "abc123",
    "eventName": "page view"
  },
  "event": "my event fields",
  "json": "whatever json you want"
}

JSONPath

To reduce burden on clients, you can use JSONPath expressions inside the schema to use values from your event to populate the MetaRouter Schema.

JSONPath syntax resources:

Note the _mrSchema.eventName is a JSONPath expression. In English, this JSONPath query says "use the value at productCategory as the eventName".

curl -X POST https://staging.mr-in.com/v1/custom/event \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
  "_mrSchema": {
    "writeKey": "example",
    "eventName": "{ ..productCategory }"
  },
  "event": "my event fields",
  "productCategory": "kitchen"
}'

Notice the _mrSchema.eventName is set to 'kitchen'. Returns 201 response:

{
  "event": {
    "_mrSchema": {
      "eventID": "a4d896bb-f425-4dac-a214-31940cf94006",
      "eventName": "kitchen",
      "writeKey": "example",
      "timestamp": "2021-08-17T18:08:09Z"
    },
    "event": "my event fields",
    "productCategory": "kitchen"
  },
  "success": true
}

Request Header

Placing an "_mrSchema": {} object in your event is one way to submit events to the Ingest API.

You can also set the X-MR-Schema header to provide an MetaRouter Schema object

curl -X POST https://staging.mr-in.com/v1/custom/event \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-Mr-Schema: {"writeKey": "example", "eventName": "{ ..productCategory }"}' \
  -d '{"event": "my event fields", "productCategory": "kitchen" }'

Returns 201 response:

{
  "event": {
    "_mrSchema": {
      "eventID": "defc1d32-01d7-416e-b9ba-534e04c13121",
      "eventName": "kitchen",
      "writeKey": "example",
      "timestamp": "2021-08-17T18:08:38Z"
    },
    "event": "my event fields",
    "productCategory": "kitchen"
  },
  "success": true
}

Request Query Params

Placing an "_mrSchema": {} object in your event is one way to submit events to the Ingest API.

Finally, you can place the MetaRouter Schema in the request query params.

curl -X POST https://staging.mr-in.com/v1/custom/event?writeKey=example&eventName=%7B%20..productCategory%20%7D \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"event": "my event fields", "productCategory": "kitchen" }'

Returns 201 response:

{
  "event": {
    "_mrSchema": {
      "eventID": "89e4438d-471e-4993-88b5-7e5692239da2",
      "eventName": "kitchen",
      "writeKey": "example",
      "timestamp": "2021-08-17T18:09:06Z"
    },
    "event": "my event fields",
    "productCategory": "kitchen"
  },
  "success": true
}

Schema Precedence

If a schema is present in X-MR-Schema header or the query params, the schema is merged with any _mrSchema object in the event. Matching fields in the header or params overrides any existing values in the _mrSchema object.

If you submit both an X-MR-Schema header and query params, the header takes precedence and the query params are ignored.

Language
Response
Click Try It! to start a request and see the response here!